Support for the Microsoft SQL Server database.

The following table summarizes current support levels for database release versions.

DBAPI Support¶

The following dialect/DBAPI options are available. Please refer to individual DBAPI sections for connect information.

• PyODBC

• mxODBC

• pymssql

外部方言¶

除了上述具有本机SQLAlChemy支持的DBAPI层之外，还有与SQL Server兼容的其他DBAPI层的第三方方言。请参阅上的“外部方言”列表。 方言 佩奇。

自动增量行为/标识列¶

SQL Server使用 IDENTITY 构造，它可以放置在表中的任何单个整数列上。SQL炼金术考虑 IDENTITY 在整数主键列的默认“autoincrement”行为中，如中所述 Column.autoincrement . 这意味着默认情况下，在 Table 将被视为标识列-除非它与 Sequence -并将生成如下DDL:：

from sqlalchemy import Table, MetaData, Column, Integer

m = MetaData()
t = Table('t', m,
        Column('id', Integer, primary_key=True),
        Column('x', Integer))
m.create_all(engine)

上面的示例将生成DDL，如下所示：

CREATE TABLE t (
    id INTEGER NOT NULL IDENTITY,
    x INTEGER NULL,
    PRIMARY KEY (id)
)

对于此默认生成的 IDENTITY 不需要，请指定 False 对于 Column.autoincrement 标志，在第一个整数主键列上：：

m = MetaData()
t = Table('t', m,
        Column('id', Integer, primary_key=True, autoincrement=False),
        Column('x', Integer))
m.create_all(engine)

添加 IDENTITY 关键字到非主键列，请指定 True 对于 Column.autoincrement 所需的标志 Column 反对，并确保 Column.autoincrement 设置为 False 在任何整数主键列上：：

m = MetaData()
t = Table('t', m,
        Column('id', Integer, primary_key=True, autoincrement=False),
        Column('x', Integer, autoincrement=True))
m.create_all(engine)

from sqlalchemy import Table, Integer, Column, Identity

test = Table(
    'test', metadata,
    Column(
        'id',
        Integer,
        primary_key=True,
        Identity(start=100, increment=10)
    ),
    Column('name', String(20))
)

CREATE TABLE test (
  id INTEGER NOT NULL IDENTITY(100,10) PRIMARY KEY,
  name VARCHAR(20) NULL,
  )

m = MetaData()
t = Table('t', m, Column('id', Integer, primary_key=True),
                Column('x', Integer))
m.create_all(engine)

with engine.begin() as conn:
    conn.execute(t.insert(), {'id': 1, 'x':1}, {'id':2, 'x':2})

CREATE TABLE t (
    id INTEGER NOT NULL IDENTITY(1,1),
    x INTEGER NULL,
    PRIMARY KEY (id)
)

COMMIT
SET IDENTITY_INSERT t ON
INSERT INTO t (id, x) VALUES (?, ?)
((1, 1), (2, 2))
SET IDENTITY_INSERT t OFF
COMMIT

序列支持¶

这个 Sequence 对象现在创建“真实”序列，即。， CREATE SEQUENCE . 为了与其他方言兼容， Sequence 默认为起始值1，即使T-SQL的默认值是-9223372036854775808。

varchar/nvarchar上的最大值¶

SQL Server支持 VARCHAR 和 NVARCHAR 数据类型，表示“可能的最大长度”。方言当前在基类型中将其处理为“无”的长度，而不是提供这些类型的方言特定版本，以便指定基类型，例如 VARCHAR(None) 可以在多个后端上假定“unengthed”行为，而不使用特定于方言的类型。

要生成最大长度的SQL Server varchar或nvarchar，请使用none:：

my_table = Table(
    'my_table', metadata,
    Column('my_data', VARCHAR(None)),
    Column('my_n_data', NVARCHAR(None))
)

排序规则支持¶

字符串参数“collation”：指定的基本字符串类型支持字符排序规则：

from sqlalchemy import VARCHAR
Column('login', VARCHAR(32, collation='Latin1_General_CI_AS'))

当这样的列与 Table ，此列的create table语句将生成：

login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL

极限/偏移支撑¶

从SQLServer2012开始，MSSQL通过“OFFSET n ROWS”和“FETCH NEXT n ROWS”子句添加了对LIMIT/OFFSET的支持。如果检测到SQL Server 2012或更高版本，SQLAlchemy将自动支持这些语法。

对于只指定LIMIT和no OFFSET的语句，SQL Server的所有版本都支持TOP关键字。当不存在OFFSET子句时，此语法用于所有SQL Server版本。例如：

select(some_table).limit(5)

将呈现类似于：

SELECT TOP 5 col1, col2.. FROM table

对于SQL Server 2012之前的SQL Server版本，将使用 ROW_NUMBER() 窗口功能。例如：

select(some_table).order_by(some_table.c.col3).limit(5).offset(10)

将呈现类似于：

SELECT anon_1.col1, anon_1.col2 FROM (SELECT col1, col2,
ROW_NUMBER() OVER (ORDER BY col3) AS
mssql_rn FROM table WHERE t.x = :x_1) AS
anon_1 WHERE mssql_rn > :param_1 AND mssql_rn <= :param_2 + :param_1

请注意，在使用LIMIT和/或OFFSET时，无论使用旧的还是新的SQL Server语法，该语句也必须具有ORDER BY，否则 CompileError 提高了。

事务隔离级别¶

所有SQL Server方言都支持通过方言特定参数设置事务隔离级别。 create_engine.isolation_level 被接受 create_engine() 以及 Connection.execution_options.isolation_level 传递给的参数 Connection.execution_options() . 此功能通过发出命令来工作 SET TRANSACTION ISOLATION LEVEL <level> 对于每个新连接。

要设置隔离级别，请使用 create_engine() ：：

engine = create_engine(
    "mssql+pyodbc://scott:tiger@ms_2008",
    isolation_level="REPEATABLE READ"
)

使用每个连接执行选项进行设置：

connection = engine.connect()
connection = connection.execution_options(
    isolation_level="READ COMMITTED"
)

的有效值 isolation_level 包括：

• AUTOCOMMIT -pyodbc/pymssql特定

• READ COMMITTED

• READ UNCOMMITTED

• REPEATABLE READ

• SERIALIZABLE

• SNAPSHOT -特定于SQL Server

空属性¶

MSSQL支持三个级别的列可空性。默认的可空性允许空值，并且在创建表构造中是显式的：：

name VARCHAR(20) NULL

如果 nullable=None 如果指定，则不制定规范。换句话说，使用数据库的配置默认值。这将呈现：

name VARCHAR(20)

如果 nullable 是 True 或 False 那么这个列将是 NULL 或 NOT NULL 分别。

日期/时间处理¶

支持日期和时间。绑定参数根据大多数MSSQL驱动程序的要求转换为datetime.datetime（）对象，如果需要，将从字符串中处理结果。日期和时间类型不适用于MSSQL2005和以前版本-如果检测到低于2008的服务器版本，这些类型的DDL将作为日期时间发出。

大文本/二进制类型取消预测¶

每 SQL Server 2012/2014 Documentation ，即 NTEXT ， TEXT 和 IMAGE 数据类型将在将来的版本中从SQL Server中删除。SQLAlChemy通常将这些类型与 UnicodeText ， TextClause 和 LargeBinary 数据类型。

为了适应这种变化，新的标志 deprecate_large_types 添加到方言中，如果用户未进行其他设置，则将根据正在使用的服务器版本检测自动进行设置。此标志的行为如下：

• 当此标志为 True , the UnicodeText ， TextClause 和 LargeBinary 当用于呈现DDL时，数据类型将呈现这些类型 NVARCHAR(max) ， VARCHAR(max) 和 VARBINARY(max) ，分别。这是添加此标志后的新行为。

• 当此标志为 False , the UnicodeText ， TextClause 和 LargeBinary 当用于呈现DDL时，数据类型将呈现这些类型 NTEXT ， TEXT 和 IMAGE ，分别。这是这些类型的长期行为。

• 标志以值开头 None ，在建立数据库连接之前。如果方言用于呈现没有设置标志的DDL，则解释为 False .

• 在第一次连接时，方言将检测SQL Server 2012或更高版本是否在使用中；如果标志仍在 None 它把它设置为 True 或 False 基于是否检测到2012或更高版本。

• 标志可以设置为 True 或 False 创建方言时，通常通过 create_engine() ：：

  eng = create_engine("mssql+pymssql://user:pass@host/db",
                  deprecate_large_types=True)

• 在所有SQLAlchemy版本中，通过使用大写类型对象，可以完全控制呈现“旧”类型还是“新”类型： NVARCHAR ， VARCHAR ， VARBINARY ， TEXT ， NTEXT ， IMAGE 将始终保持固定，并始终准确输出该类型。

多部分架构名称¶

SQL Server模式有时需要对其“模式”限定符使用多个部分，即将数据库名称和所有者名称作为单独的标记，例如 mydatabase.dbo.some_table . 这些多部分名称可以使用 Table.schema 的参数 Table ：：

Table(
    "some_table", metadata,
    Column("q", String(50)),
    schema="mydatabase.dbo"
)

在执行表或组件反射等操作时，包含点的架构参数将被拆分为单独的“数据库”和“所有者”组件，以便正确查询SQL Server信息架构表，因为这两个值是单独存储的。此外，在为DDL或SQL呈现模式名称时，这两个组件将分别引用区分大小写的名称和其他特殊字符。给出如下参数：

Table(
    "some_table", metadata,
    Column("q", String(50)),
    schema="MyDataBase.dbo"
)

上面的模式将呈现为 [MyDataBase].dbo 以及在反射中，将使用“dbo”作为所有者，“mydatabase”作为数据库名称进行反射。

要控制模式名称如何分解为数据库/所有者，请在名称中指定方括号（在SQL Server中，方括号引用字符）。以下“业主”将被视为 MyDataBase.dbo “数据库”将为无：

Table(
    "some_table", metadata,
    Column("q", String(50)),
    schema="[MyDataBase.dbo]"
)

要使用特殊字符或嵌入点分别指定数据库和所有者名称，请使用两组括号：

Table(
    "some_table", metadata,
    Column("q", String(50)),
    schema="[MyDataBase.Period].[MyOwner.Dot]"
)

旧架构模式¶

MSSQL方言的非常旧的版本引入了这样的行为：当在select语句中使用模式限定表时，该表将自动别名；给定一个表：

account_table = Table(
    'account', metadata,
    Column('id', Integer, primary_key=True),
    Column('info', String(100)),
    schema="customer_schema"
)

这种传统的呈现模式假定“customer_schema.account”不会被SQL语句的所有部分接受，如下所示：

>>> eng = create_engine("mssql+pymssql://mydsn", legacy_schema_aliasing=True)
>>> print(account_table.select().compile(eng))
SELECT account_1.id, account_1.info
FROM customer_schema.account AS account_1

默认情况下，此行为模式现在处于关闭状态，因为它似乎没有任何作用；但是，在遗留应用程序依赖它的情况下，可以使用 legacy_schema_aliasing 参数 create_engine() 如上图所示。

聚集索引支持¶

MSSQL方言通过 mssql_clustered 选择权。此选项可用于 Index ， UniqueConstraint . 和 PrimaryKeyConstraint .

要生成聚集索引，请执行以下操作：

Index("my_index", table.c.x, mssql_clustered=True)

它将索引呈现为 CREATE CLUSTERED INDEX my_index ON table (x) .

要生成群集主键，请使用：

Table('my_table', metadata,
      Column('x', ...),
      Column('y', ...),
      PrimaryKeyConstraint("x", "y", mssql_clustered=True))

例如，它将表呈现为：

CREATE TABLE my_table (x INTEGER NOT NULL, y INTEGER NOT NULL,
                       PRIMARY KEY CLUSTERED (x, y))

类似地，我们可以使用以下方法生成集群唯一约束：

Table('my_table', metadata,
      Column('x', ...),
      Column('y', ...),
      PrimaryKeyConstraint("x"),
      UniqueConstraint("y", mssql_clustered=True),
      )

要显式请求非聚集主键（例如，当需要单独的聚集索引时），请使用：

Table('my_table', metadata,
      Column('x', ...),
      Column('y', ...),
      PrimaryKeyConstraint("x", "y", mssql_clustered=False))

例如，它将表呈现为：

CREATE TABLE my_table (x INTEGER NOT NULL, y INTEGER NOT NULL,
                       PRIMARY KEY NONCLUSTERED (x, y))

MSSQL特定索引选项¶

除了集群之外，MSSQL方言还支持 Index .

Index("my_index", table.c.x, mssql_include=['y'])

Index("my_index", table.c.x, mssql_where=table.c.x > 10)

Index("my_index", table.c.x.desc())

兼容级别¶

MSSQL支持在数据库级别设置兼容级别的概念。例如，这允许在SQL2005数据库服务器上运行与SQL2000兼容的数据库。 server_version_info 将始终返回数据库服务器版本信息（在本例中是SQL2005），而不是兼容级别信息。因此，如果在向后兼容模式下运行，则SQLAlchemy可能会尝试使用数据库服务器无法分析的T-SQL语句。

触发器¶

默认情况下，SQLAlchemy使用插入的输出通过标识列或其他服务器端默认值获取新生成的主键值。MS-SQL不允许在具有触发器的表上使用插入的输出。要禁用按表插入的输出，请指定 implicit_returning=False 对于每一个 Table 触发条件：

Table('mytable', metadata,
    Column('id', Integer, primary_key=True),
    # ...,
    implicit_returning=False
)

声明形式：

class MyClass(Base):
    # ...
    __table_args__ = {'implicit_returning':False}

也可以使用 implicit_returning=False 争论 create_engine() .

行数支持/ORM版本控制¶

SQL Server驱动程序返回更新或删除语句中更新的行数的能力可能有限。

在撰写本文时，当使用插入的输出时，pyodbc驱动程序无法返回行数。这会影响SQLAlchemy ORM的版本控制功能，在许多情况下，服务器端的值生成器正在使用中，当版本控制操作可以成功时，ORM不能总是检查更新或删除语句是否与预期的行数匹配，这就是它验证版本标识符是否匹配的方式。出现这种情况时，将发出警告，但操作将继续。

通过设置 Table.implicit_returning 旗到 False 关于某一特定 Table ，在声明式中如下所示：

class MyTable(Base):
    __tablename__ = 'mytable'
    id = Column(Integer, primary_key=True)
    stuff = Column(String(10))
    timestamp = Column(TIMESTAMP(), default=text('DEFAULT'))
    __mapper_args__ = {
        'version_id_col': timestamp,
        'version_id_generator': False,
    }
    __table_args__ = {
        'implicit_returning': False
    }

启用快照隔离¶

SQL Server有一个默认的事务隔离模式，该模式锁定整个表，并导致即使是轻微并发的应用程序具有长时间持有的锁和频繁的死锁。建议将数据库作为一个整体启用快照隔离，以获得现代级别的并发支持。这是通过在SQL提示下执行以下alter database命令来实现的：

ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON

ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON

有关SQL Server快照隔离的背景信息，请参阅https://msdn.microsoft.com/en-us/library/ms175095.aspx.

SQL Server SQL构造¶

function sqlalchemy.dialects.mssql.try_cast(*arg, **kw)¶

创建TRYu CAST表达式。

TryCast 是SQLAlchemy的一个子类 Cast 构造，并以相同的方式工作，但呈现的SQL表达式是“TRY泳CAST”而不是“CAST”：

from sqlalchemy import select
from sqlalchemy import Numeric
from sqlalchemy.dialects.mssql import try_cast

stmt = select(
    try_cast(product_table.c.unit_price, Numeric(10, 4))
)

以上将呈现：

SELECT TRY_CAST (product_table.unit_price AS NUMERIC(10, 4))
FROM product_table

1.3.7 新版功能.

SQL Server数据类型¶

与所有的SQLAlchemy方言一样，已知对SQL Server有效的所有大写类型都可以从顶级方言导入，无论它们是否源自 sqlalchemy.types 或者来自当地方言：

from sqlalchemy.dialects.mssql import \
    BIGINT, BINARY, BIT, CHAR, DATE, DATETIME, DATETIME2, \
    DATETIMEOFFSET, DECIMAL, FLOAT, IMAGE, INTEGER, JSON, MONEY, \
    NCHAR, NTEXT, NUMERIC, NVARCHAR, REAL, SMALLDATETIME, \
    SMALLINT, SMALLMONEY, SQL_VARIANT, TEXT, TIME, \
    TIMESTAMP, TINYINT, UNIQUEIDENTIFIER, VARBINARY, VARCHAR

特定于SQL Server或具有特定于SQL Server的构造参数的类型如下：

class sqlalchemy.dialects.mssql.BIT(create_constraint=False, name=None, _create_events=True)¶

MSSQL位类型。

pyodbc和pymssql都以Python<class‘bool’>的形式从位列返回值，所以只返回子类boolean。

类签名

class sqlalchemy.dialects.mssql.BIT (sqlalchemy.types.Boolean)

method sqlalchemy.dialects.mssql.BIT.__init__(create_constraint=False, name=None, _create_events=True)¶

inherited from the sqlalchemy.types.Boolean.__init__ method of Boolean

构造一个布尔值。

参数

• create_constraint¶ -- 默认为False。如果布尔值生成为int/mall int，还可以在表上创建一个CHECK约束，以确保值为1或0。。。注意：强烈建议CHECK约束有一个明确的名称，以支持模式管理问题。这可以通过设置 Boolean.name 参数或设置适当的命名约定；请参见 配置约束命名约定 作为背景。。。VersionChanged：：1.4-此标志现在默认为False，这意味着不会为非本机枚举类型生成检查约束。

• name¶ -- 如果生成了检查约束，请指定约束的名称。

class sqlalchemy.dialects.mssql.CHAR(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

SQL字符类型。

类签名

class sqlalchemy.dialects.mssql.CHAR (sqlalchemy.types.String)

method sqlalchemy.dialects.mssql.CHAR.__init__(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

inherited from the sqlalchemy.types.String.__init__ method of String

创建字符串保持类型。

参数

• length¶ -- 可选，用于DDL和CAST表达式的列的长度。如果没有，可以安全地省略 CREATE TABLE 将发布。某些数据库可能需要 length 在DDL中使用，并在 CREATE TABLE 如果 VARCHAR 不包括长度。该值是否解释为字节或字符是特定于数据库的。

• collation¶ -- 可选，在DDL和CAST表达式中使用的列级排序规则。使用SQLite、MySQL和PostgreSQL支持的COLLATE关键字呈现。E、 g.：>>>从sqlalchemy import cast，select，String>>>打印（select（cast（'some String'，String（collation='utf8'）））select cast（：param_1 AS VARCHAR COLLATE utf8）AS anon_

• convert_unicode¶ -- 当设置为 True , the String 类型将假定输入将作为python 2下的python unicode对象传递，结果将作为python unicode对象返回。在DBAPI在python 2下不支持pythonUnicode的罕见情况下，sqlachemy将在字符串上使用自己的编码器/解码器功能，参考 create_engine.encoding 参数参数传递给 create_engine() 作为编码。…已弃用：：1.3 String.convert_unicode 参数已弃用，将在将来的版本中删除。所有现代DBAPI现在都直接支持PythonUnicode，而这个参数是不必要的。对于极为罕见的情况，python unicode将由sqlachemy在后端进行编码/解码， does 本机支持python unicode，字符串值 "force" 可以在此处传递，这将导致无条件使用SQLAlchemy的编码/解码服务。…注意：：sqlacalchemy的unicode转换标志和特性只适用于python 2；在python 3中，所有字符串对象都是unicode对象。出于这个原因，以及事实上，几乎所有现代DBAPI现在都支持Unicode，即使在Python2下， String.convert_unicode 标志本身就是一个遗留功能。…注：在绝大多数情况下， Unicode 或 UnicodeText 数据类型应用于 Column 它期望存储非ascii数据。这些数据类型将确保在数据库端使用正确的类型，并在Python2下设置正确的Unicode行为。。另请参见： create_engine.convert_unicode - Engine 宽参数

• unicode_error¶ -- 可选，用于处理Unicode转换错误的方法。表现得像 errors 标准库的关键字参数 string.decode() 函数，要求 String.convert_unicode 设置为 "force" …已弃用：：1.3 String.unicode_errors 参数已弃用，将在将来的版本中删除。这个参数对于现代的python dbapis来说是不必要的，并且会显著降低性能。

class sqlalchemy.dialects.mssql.DATETIME2(precision=None, **kw)¶

类签名

class sqlalchemy.dialects.mssql.DATETIME2 (sqlalchemy.dialects.mssql.base._DateTimeBase, sqlalchemy.types.DateTime)

method sqlalchemy.dialects.mssql.DATETIME2.__init__(precision=None, **kw)¶

class sqlalchemy.dialects.mssql.DATETIMEOFFSET(precision=None, **kw)¶

类签名

class sqlalchemy.dialects.mssql.DATETIMEOFFSET (sqlalchemy.dialects.mssql.base._DateTimeBase, sqlalchemy.types.DateTime)

method sqlalchemy.dialects.mssql.DATETIMEOFFSET.__init__(precision=None, **kw)¶

class sqlalchemy.dialects.mssql.IMAGE(length=None)¶

类签名

class sqlalchemy.dialects.mssql.IMAGE (sqlalchemy.types.LargeBinary)

method sqlalchemy.dialects.mssql.IMAGE.__init__(length=None)¶

inherited from the sqlalchemy.types.LargeBinary.__init__ method of LargeBinary

构造一个大二进制类型。

参数

length¶ -- 可选，用于ddl语句中的列的长度，用于接受长度的二进制类型，例如mysql blob类型。

class sqlalchemy.dialects.mssql.JSON(none_as_null=False)¶

MSSQL JSON类型。

自SQL Server 2016起，MSSQL支持JSON格式的数据。

这个 JSON DDL级别的数据类型将把数据类型表示为 NVARCHAR(max) ，但提供了JSON级别的比较函数以及Python强制行为。

JSON 每当基地 JSON 数据类型用于SQL Server后端。

参见

JSON -通用跨平台JSON数据类型的主要文档。

这个 JSON 类型支持JSON值的持久性以及由提供的核心索引操作 JSON 数据类型，通过调整操作来呈现 JSON_VALUE 或 JSON_QUERY 数据库级别的函数。

SQL服务器 JSON 类型必须使用 JSON_QUERY 和 JSON_VALUE 查询JSON对象元素时的函数。这两个功能有一个主要的限制，因为它们是 互斥的 基于要返回的对象类型。这个 JSON_QUERY 功能 only 返回JSON字典或列表，但不返回单个字符串、数字或布尔元素；该 JSON_VALUE 功能 only 返回单个字符串、数值或布尔元素。 如果没有针对正确的预期值使用这两个函数，则返回NULL或引发错误 .

为了处理这种尴尬的需求，索引访问规则如下：

1. 当从本身是JSON字典或列表的JSON中提取子元素时 Comparator.as_json() 应使用访问器：

   stmt = select(
       data_table.c.data["some key"].as_json()
   ).where(
       data_table.c.data["some key"].as_json() == {"sub": "structure"}
   )

2. 当从JSON中提取一个子元素时，如果JSON是纯布尔型、字符串型、整数型或浮点型，请在 Comparator.as_boolean() ， Comparator.as_string() ， Comparator.as_integer() ， Comparator.as_float() ：：

   stmt = select(
       data_table.c.data["some key"].as_string()
   ).where(
       data_table.c.data["some key"].as_string() == "some string"
   )

1.4 新版功能.

类签名

class sqlalchemy.dialects.mssql.JSON (sqlalchemy.types.JSON)

method sqlalchemy.dialects.mssql.JSON.__init__(none_as_null=False)¶

inherited from the sqlalchemy.types.JSON.__init__ method of JSON

构建一个 JSON 类型。

参数

none_as_null=False¶ -- 如果为True，则持久值 None 作为SQL null值，而不是 null 。请注意，当此标志为false时， null() 构造仍然可以用于持久化NULL值：：FROM sqlalChemy import null connec.ecute(table.insert()，data=null())..注：： JSON.none_as_null 会吗？ not 应用于传递给的值 Column.default 和 Column.server_default ；价值为 None 为这些参数传递表示“没有默认存在”。此外，在SQL比较表达式中使用Python值时， None 继续引用SQL NULL，而不是JSON NULL。这个 JSON.none_as_null 标志显式引用 持之以恒 INSERT或UPDATE语句中的值的。这个 JSON.NULL 值应用于希望与JSON NULL进行比较的SQL表达式。。。另请参阅：： JSON.NULL

class sqlalchemy.dialects.mssql.MONEY¶

类签名

class sqlalchemy.dialects.mssql.MONEY (sqlalchemy.types.TypeEngine)

method sqlalchemy.dialects.mssql.MONEY.__init__()¶

inherited from the builtins.object.__init__ method of builtins.object

class sqlalchemy.dialects.mssql.NCHAR(length=None, **kwargs)¶

SQL NChar类型。

类签名

class sqlalchemy.dialects.mssql.NCHAR (sqlalchemy.types.Unicode)

method sqlalchemy.dialects.mssql.NCHAR.__init__(length=None, **kwargs)¶

inherited from the sqlalchemy.types.Unicode.__init__ method of Unicode

创建一个 Unicode 对象。

参数与 String ，除了 convert_unicode 默认为 True .

class sqlalchemy.dialects.mssql.NTEXT(length=None, **kwargs)¶

mssql ntext类型，用于长度不超过2^30个字符的Unicode文本。

类签名

class sqlalchemy.dialects.mssql.NTEXT (sqlalchemy.types.UnicodeText)

method sqlalchemy.dialects.mssql.NTEXT.__init__(length=None, **kwargs)¶

inherited from the sqlalchemy.types.UnicodeText.__init__ method of UnicodeText

创建一个Unicode转换文本类型。

参数与 TextClause ，除了 convert_unicode 默认为 True .

class sqlalchemy.dialects.mssql.NVARCHAR(length=None, **kwargs)¶

SQL nvarchar类型。

类签名

class sqlalchemy.dialects.mssql.NVARCHAR (sqlalchemy.types.Unicode)

method sqlalchemy.dialects.mssql.NVARCHAR.__init__(length=None, **kwargs)¶

inherited from the sqlalchemy.types.Unicode.__init__ method of Unicode

创建一个 Unicode 对象。

参数与 String ，除了 convert_unicode 默认为 True .

class sqlalchemy.dialects.mssql.REAL(**kw)¶

类签名

class sqlalchemy.dialects.mssql.REAL (sqlalchemy.types.REAL)

method sqlalchemy.dialects.mssql.REAL.__init__(**kw)¶

构造一个浮点。

参数

• precision¶ -- 用于DDL的数字精度 CREATE TABLE .

• asdecimal¶ -- 与…相同的标志 Numeric ，但默认为 False . 请注意，将此标志设置为 True 导致浮点转换。

• decimal_return_scale¶ -- 从浮点转换为python小数时使用的默认小数位数。由于小数点不准确，浮点值通常要长得多，而且大多数浮点数据库类型没有“小数位数”的概念，因此默认情况下，浮点类型在转换时查找前十位小数。指定此值将覆盖该长度。注意，如果没有另外指定，mysql float类型（包括“scale”）将使用“scale”作为decimal_return_scale的默认值。…版本已添加：：0.9.0

class sqlalchemy.dialects.mssql.ROWVERSION(convert_int=False)¶

实现SQL Server行版本类型。

rowversion数据类型是timestamp数据类型的SQL Server同义词，但是当前的SQL Server文档建议对新数据类型使用rowversion。

rowversion数据类型 not 从数据库中反射（例如自省）本身；返回的数据类型将为 TIMESTAMP .

这是一个只读数据类型，不支持插入值。

1.2 新版功能.

参见

TIMESTAMP

类签名

class sqlalchemy.dialects.mssql.ROWVERSION (sqlalchemy.dialects.mssql.base.TIMESTAMP)

method sqlalchemy.dialects.mssql.ROWVERSION.__init__(convert_int=False)¶

inherited from the sqlalchemy.dialects.mssql.base.TIMESTAMP.__init__ method of TIMESTAMP

构造时间戳或行版本类型。

参数

convert_int¶ -- 如果为真，则二进制整数值将在读取时转换为整数。

1.2 新版功能.

class sqlalchemy.dialects.mssql.SMALLDATETIME(timezone=False)¶

类签名

class sqlalchemy.dialects.mssql.SMALLDATETIME (sqlalchemy.dialects.mssql.base._DateTimeBase, sqlalchemy.types.DateTime)

method sqlalchemy.dialects.mssql.SMALLDATETIME.__init__(timezone=False)¶

inherited from the sqlalchemy.types.DateTime.__init__ method of DateTime

构建新的 DateTime .

参数

timezone¶ -- 布尔函数。指示日期时间类型应启用时区支持（如果在 base date/time-holding type only . 建议使用 TIMESTAMP 当使用此标志时直接使用数据类型，因为某些数据库包含独立的通用日期/时间保持类型，这与支持时区的时间戳数据类型不同，例如Oracle。

class sqlalchemy.dialects.mssql.SMALLMONEY¶

类签名

class sqlalchemy.dialects.mssql.SMALLMONEY (sqlalchemy.types.TypeEngine)

method sqlalchemy.dialects.mssql.SMALLMONEY.__init__()¶

inherited from the builtins.object.__init__ method of builtins.object

class sqlalchemy.dialects.mssql.SQL_VARIANT¶

类签名

class sqlalchemy.dialects.mssql.SQL_VARIANT (sqlalchemy.types.TypeEngine)

method sqlalchemy.dialects.mssql.SQL_VARIANT.__init__()¶

inherited from the builtins.object.__init__ method of builtins.object

class sqlalchemy.dialects.mssql.TEXT(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

SQL文本类型。

类签名

class sqlalchemy.dialects.mssql.TEXT (sqlalchemy.types.Text)

method sqlalchemy.dialects.mssql.TEXT.__init__(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

inherited from the sqlalchemy.types.String.__init__ method of String

创建字符串保持类型。

参数

• length¶ -- 可选，用于DDL和CAST表达式的列的长度。如果没有，可以安全地省略 CREATE TABLE 将发布。某些数据库可能需要 length 在DDL中使用，并在 CREATE TABLE 如果 VARCHAR 不包括长度。该值是否解释为字节或字符是特定于数据库的。

• collation¶ -- 可选，在DDL和CAST表达式中使用的列级排序规则。使用SQLite、MySQL和PostgreSQL支持的COLLATE关键字呈现。E、 g.：>>>从sqlalchemy import cast，select，String>>>打印（select（cast（'some String'，String（collation='utf8'）））select cast（：param_1 AS VARCHAR COLLATE utf8）AS anon_

• convert_unicode¶ -- 当设置为 True , the String 类型将假定输入将作为python 2下的python unicode对象传递，结果将作为python unicode对象返回。在DBAPI在python 2下不支持pythonUnicode的罕见情况下，sqlachemy将在字符串上使用自己的编码器/解码器功能，参考 create_engine.encoding 参数参数传递给 create_engine() 作为编码。…已弃用：：1.3 String.convert_unicode 参数已弃用，将在将来的版本中删除。所有现代DBAPI现在都直接支持PythonUnicode，而这个参数是不必要的。对于极为罕见的情况，python unicode将由sqlachemy在后端进行编码/解码， does 本机支持python unicode，字符串值 "force" 可以在此处传递，这将导致无条件使用SQLAlchemy的编码/解码服务。…注意：：sqlacalchemy的unicode转换标志和特性只适用于python 2；在python 3中，所有字符串对象都是unicode对象。出于这个原因，以及事实上，几乎所有现代DBAPI现在都支持Unicode，即使在Python2下， String.convert_unicode 标志本身就是一个遗留功能。…注：在绝大多数情况下， Unicode 或 UnicodeText 数据类型应用于 Column 它期望存储非ascii数据。这些数据类型将确保在数据库端使用正确的类型，并在Python2下设置正确的Unicode行为。。另请参见： create_engine.convert_unicode - Engine 宽参数

• unicode_error¶ -- 可选，用于处理Unicode转换错误的方法。表现得像 errors 标准库的关键字参数 string.decode() 函数，要求 String.convert_unicode 设置为 "force" …已弃用：：1.3 String.unicode_errors 参数已弃用，将在将来的版本中删除。这个参数对于现代的python dbapis来说是不必要的，并且会显著降低性能。

class sqlalchemy.dialects.mssql.TIME(precision=None, **kwargs)¶

类签名

class sqlalchemy.dialects.mssql.TIME (sqlalchemy.types.TIME)

method sqlalchemy.dialects.mssql.TIME.__init__(precision=None, **kwargs)¶

class sqlalchemy.dialects.mssql.TIMESTAMP(convert_int=False)¶

实现SQL Server时间戳类型。

注意这是 完全不同 而不是SQL Server不支持的SQL标准时间戳类型。它是只读数据类型，不支持插入值。

1.2 新版功能.

参见

ROWVERSION

类签名

class sqlalchemy.dialects.mssql.TIMESTAMP (sqlalchemy.types._Binary)

method sqlalchemy.dialects.mssql.TIMESTAMP.__init__(convert_int=False)¶

构造时间戳或行版本类型。

参数

convert_int¶ -- 如果为真，则二进制整数值将在读取时转换为整数。

1.2 新版功能.

class sqlalchemy.dialects.mssql.TINYINT¶

类签名

class sqlalchemy.dialects.mssql.TINYINT (sqlalchemy.types.Integer)

method sqlalchemy.dialects.mssql.TINYINT.__init__()¶

inherited from the builtins.object.__init__ method of builtins.object

class sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER¶

类签名

class sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER (sqlalchemy.types.TypeEngine)

method sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER.__init__()¶

inherited from the builtins.object.__init__ method of builtins.object

class sqlalchemy.dialects.mssql.VARCHAR(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

SQL varchar类型。

类签名

class sqlalchemy.dialects.mssql.VARCHAR (sqlalchemy.types.String)

method sqlalchemy.dialects.mssql.VARCHAR.__init__(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

inherited from the sqlalchemy.types.String.__init__ method of String

创建字符串保持类型。

参数

• length¶ -- 可选，用于DDL和CAST表达式的列的长度。如果没有，可以安全地省略 CREATE TABLE 将发布。某些数据库可能需要 length 在DDL中使用，并在 CREATE TABLE 如果 VARCHAR 不包括长度。该值是否解释为字节或字符是特定于数据库的。

• collation¶ -- 可选，在DDL和CAST表达式中使用的列级排序规则。使用SQLite、MySQL和PostgreSQL支持的COLLATE关键字呈现。E、 g.：>>>从sqlalchemy import cast，select，String>>>打印（select（cast（'some String'，String（collation='utf8'）））select cast（：param_1 AS VARCHAR COLLATE utf8）AS anon_

• convert_unicode¶ -- 当设置为 True , the String 类型将假定输入将作为python 2下的python unicode对象传递，结果将作为python unicode对象返回。在DBAPI在python 2下不支持pythonUnicode的罕见情况下，sqlachemy将在字符串上使用自己的编码器/解码器功能，参考 create_engine.encoding 参数参数传递给 create_engine() 作为编码。…已弃用：：1.3 String.convert_unicode 参数已弃用，将在将来的版本中删除。所有现代DBAPI现在都直接支持PythonUnicode，而这个参数是不必要的。对于极为罕见的情况，python unicode将由sqlachemy在后端进行编码/解码， does 本机支持python unicode，字符串值 "force" 可以在此处传递，这将导致无条件使用SQLAlchemy的编码/解码服务。…注意：：sqlacalchemy的unicode转换标志和特性只适用于python 2；在python 3中，所有字符串对象都是unicode对象。出于这个原因，以及事实上，几乎所有现代DBAPI现在都支持Unicode，即使在Python2下， String.convert_unicode 标志本身就是一个遗留功能。…注：在绝大多数情况下， Unicode 或 UnicodeText 数据类型应用于 Column 它期望存储非ascii数据。这些数据类型将确保在数据库端使用正确的类型，并在Python2下设置正确的Unicode行为。。另请参见： create_engine.convert_unicode - Engine 宽参数

• unicode_error¶ -- 可选，用于处理Unicode转换错误的方法。表现得像 errors 标准库的关键字参数 string.decode() 函数，要求 String.convert_unicode 设置为 "force" …已弃用：：1.3 String.unicode_errors 参数已弃用，将在将来的版本中删除。这个参数对于现代的python dbapis来说是不必要的，并且会显著降低性能。

class sqlalchemy.dialects.mssql.XML(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

MSSQL XML类型。

这是一个用于反射的占位符类型，不包含任何Python端数据类型支持。它目前也不支持其他参数，例如“content”、“document”、“xml-schema-collection”。

1.1.11 新版功能.

类签名

class sqlalchemy.dialects.mssql.XML (sqlalchemy.types.Text)

method sqlalchemy.dialects.mssql.XML.__init__(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶

inherited from the sqlalchemy.types.String.__init__ method of String

创建字符串保持类型。

参数

• length¶ -- 可选，用于DDL和CAST表达式的列的长度。如果没有，可以安全地省略 CREATE TABLE 将发布。某些数据库可能需要 length 在DDL中使用，并在 CREATE TABLE 如果 VARCHAR 不包括长度。该值是否解释为字节或字符是特定于数据库的。

• collation¶ -- 可选，在DDL和CAST表达式中使用的列级排序规则。使用SQLite、MySQL和PostgreSQL支持的COLLATE关键字呈现。E、 g.：>>>从sqlalchemy import cast，select，String>>>打印（select（cast（'some String'，String（collation='utf8'）））select cast（：param_1 AS VARCHAR COLLATE utf8）AS anon_

• convert_unicode¶ -- 当设置为 True , the String 类型将假定输入将作为python 2下的python unicode对象传递，结果将作为python unicode对象返回。在DBAPI在python 2下不支持pythonUnicode的罕见情况下，sqlachemy将在字符串上使用自己的编码器/解码器功能，参考 create_engine.encoding 参数参数传递给 create_engine() 作为编码。…已弃用：：1.3 String.convert_unicode 参数已弃用，将在将来的版本中删除。所有现代DBAPI现在都直接支持PythonUnicode，而这个参数是不必要的。对于极为罕见的情况，python unicode将由sqlachemy在后端进行编码/解码， does 本机支持python unicode，字符串值 "force" 可以在此处传递，这将导致无条件使用SQLAlchemy的编码/解码服务。…注意：：sqlacalchemy的unicode转换标志和特性只适用于python 2；在python 3中，所有字符串对象都是unicode对象。出于这个原因，以及事实上，几乎所有现代DBAPI现在都支持Unicode，即使在Python2下， String.convert_unicode 标志本身就是一个遗留功能。…注：在绝大多数情况下， Unicode 或 UnicodeText 数据类型应用于 Column 它期望存储非ascii数据。这些数据类型将确保在数据库端使用正确的类型，并在Python2下设置正确的Unicode行为。。另请参见： create_engine.convert_unicode - Engine 宽参数

• unicode_error¶ -- 可选，用于处理Unicode转换错误的方法。表现得像 errors 标准库的关键字参数 string.decode() 函数，要求 String.convert_unicode 设置为 "force" …已弃用：：1.3 String.unicode_errors 参数已弃用，将在将来的版本中删除。这个参数对于现代的python dbapis来说是不必要的，并且会显著降低性能。

脓毒症¶

Support for the Microsoft SQL Server database via the PyODBC driver.

mssql+pyodbc://<username>:<password>@<dsnname>

engine = create_engine("mssql+pyodbc://scott:tiger@some_dsn")

DSN=some_dsn;UID=scott;PWD=tiger

engine = create_engine("mssql+pyodbc://scott:tiger@myhost:port/databasename?driver=ODBC+Driver+17+for+SQL+Server")

engine = create_engine(
    "mssql+pyodbc://scott:tiger@myhost:49242/databasename"
    "?driver=ODBC+Driver+17+for+SQL+Server"
    "&authentication=ActiveDirectoryIntegrated"
)

from sqlalchemy.engine import URL
connection_url = URL.create(
    "mssql+pyodbc",
    username="scott",
    password="tiger",
    host="myhost",
    port=49242,
    database="databasename",
    query={
        "driver": "ODBC Driver 17 for SQL Server",
        "authentication": "ActiveDirectoryIntegrated",
    },
)

from sqlalchemy.engine import URL
connection_string = "DRIVER={SQL Server Native Client 10.0};SERVER=dagger;DATABASE=test;UID=user;PWD=password"
connection_url = URL.create("mssql+pyodbc", query={"odbc_connect": connection_string})

engine = create_engine(connection_url)

import struct
from sqlalchemy import create_engine, event
from sqlalchemy.engine.url import URL
from azure import identity

SQL_COPT_SS_ACCESS_TOKEN = 1256  # Connection option for access tokens, as defined in msodbcsql.h
TOKEN_URL = "https://database.windows.net/"  # The token URL for any Azure SQL database

connection_string = "mssql+pyodbc://@my-server.database.windows.net/myDb?driver=ODBC+Driver+17+for+SQL+Server"

engine = create_engine(connection_string)

azure_credentials = identity.DefaultAzureCredential()

@event.listens_for(engine, "do_connect")
def provide_token(dialect, conn_rec, cargs, cparams):
    # remove the "Trusted_Connection" parameter that SQLAlchemy adds
    cargs[0] = cargs[0].replace(";Trusted_Connection=Yes", "")

    # create token credential
    raw_token = azure_credentials.get_token(TOKEN_URL).token.encode("utf-16-le")
    token_struct = struct.pack(f"<I{len(raw_token)}s", len(raw_token), raw_token)

    # apply it to keyword arguments
    cparams["attrs_before"] = {SQL_COPT_SS_ACCESS_TOKEN: token_struct}

connection_url = sa.engine.URL.create(
    "mssql+pyodbc",
    username="scott",
    password="tiger",
    host="dw.azure.example.com",
    database="mydb",
    query={
        "driver": "ODBC Driver 17 for SQL Server",
        "autocommit": "True",
    },
)

engine = create_engine(connection_url).execution_options(
    isolation_level="AUTOCOMMIT"
)

import pyodbc

pyodbc.pooling = False

# don't use the engine before pooling is set to False
engine = create_engine("mssql+pyodbc://user:pass@dsn")

engine = create_engine(
    "mssql+pyodbc://scott:tiger@mssql2017:1433/test?driver=ODBC+Driver+13+for+SQL+Server",
    fast_executemany=True)

engine = create_engine("mssql+pyodbc://...", use_setinputsizes=True)

MXODBC¶

Support for the Microsoft SQL Server database via the mxODBC driver.

mssql+mxodbc://<username>:<password>@<dsnname>

PysSQL¶

通过pymssql驱动程序支持Microsoft SQL Server数据库。

mssql+pymssql://<username>:<password>@<freetds_name>/?charset=utf8

pymssql是一个Python模块，提供Python DBAPI接口 FreeTDS 。

此驱动程序的现代版本与来自Linux的sqlserver和FreeTDS非常配合，因此强烈推荐使用。但是，pymssql目前没有被维护，并且在支持sqlserver的更新功能方面落后于microsoftobc驱动程序的进度。在编写本文档时，pymssql的最新官方版本是2.1.4版（2018年8月），它不支持：

1. 表值参数（TVP），

2. datetimeoffset 使用时区感知的列 datetime 对象（值以字符串形式发送和检索），以及

3. 从预构建的控制盘安装pymssql时，加密连接（例如，到azuresql）。对加密连接的支持需要从源代码构建pymssql，这可能是一个麻烦，尤其是在Windows下。

当使用Microsoft的ODBC Driver for SQL Server（msodbcsql）时，上述功能都受mssql+pyodbc的支持，该驱动程序现在可用于Windows（多种版本）Linux和macOS。