Microsoft SQL Server¶

Support for the Microsoft SQL Server database.

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

**Supported Microsoft SQL Server versions**¶
Support type	Versions
Supported version	2012+
Best effort	2005+

DBAPI Support¶

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

PyODBC
pymssql
aioodbc

外部方言¶

External Dialects

中文

除了上述原生支持 SQLAlchemy 的 DBAPI 层之外，还有其他与 SQL Server 兼容的 DBAPI 层的第三方方言。请参阅:ref:dialect_toplevel 页面上的“外部方言”列表。

英文

In addition to the above DBAPI layers with native SQLAlchemy support, there are third-party dialects for other DBAPI layers that are compatible with SQL Server. See the “External Dialects” list on the Dialects page.

自动增量行为 / IDENTITY 列¶

Auto Increment Behavior / IDENTITY Columns

中文

SQL Server 使用 IDENTITY 构造提供所谓的“自增”功能，可用于表中的任意单个整数列。 SQLAlchemy 将 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，可在首个整数主键列上将 Column.autoincrement 显式设置为 False:

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

要将 IDENTITY 用于非主键列，可在目标 Column 上设置 autoincrement=True，同时确保任何整数主键列的 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)

在 1.4 版本发生变更: 在 Column 中新增 Identity 构造，以指定 IDENTITY 的起始值与增量值。此方式取代使用 Sequence 来设置相关参数。

自 1.4 版本弃用: 传递给 Column 的 mssql_identity_start 与 mssql_identity_increment 参数已弃用，应使用 Identity 对象替代。若同时指定两种配置方式将导致编译错误。此外，这两个参数也不再出现在 Inspector.get_columns() 方法返回结果中的 dialect_options 字段下，应使用 identity 字段获取相关信息。

在 1.4 版本发生变更: 移除了通过 Sequence 对象修改 IDENTITY 特性的能力。Sequence 现在仅用于操作真正的 T-SQL SEQUENCE 类型。

备注

每个表只能存在一个 IDENTITY 列。当通过 autoincrement=True 启用 IDENTITY 关键字时，SQLAlchemy 不会限制多个列同时指定该选项的行为。数据库自身将在执行 CREATE TABLE 时拒绝这种定义。

备注

若向标有 IDENTITY 的列插入值，SQL Server 将拒绝该 INSERT 语句。若要允许插入值，必须启用会话级的 “SET IDENTITY_INSERT” 选项。 SQLAlchemy 的 SQL Server 方言在使用核心层的 Insert 构造时会自动启用该选项；若执行时明确为 IDENTITY 列提供值，则将在语句执行期间启用 “IDENTITY_INSERT”。不过，这种方式性能较低，不应作为常规方案使用。若表中的整数主键列并不需要 IDENTITY 行为，应在建表时设置 autoincrement=False 来禁用该关键字。

英文

SQL Server provides so-called “auto incrementing” behavior using the IDENTITY construct, which can be placed on any single integer column in a table. SQLAlchemy considers IDENTITY within its default “autoincrement” behavior for an integer primary key column, described at Column.autoincrement. This means that by default, the first integer primary key column in a Table will be considered to be the identity column - unless it is associated with a Sequence - and will generate DDL as such:

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)

The above example will generate DDL as:

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

For the case where this default generation of IDENTITY is not desired, specify False for the Column.autoincrement flag, on the first integer primary key column:

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

To add the IDENTITY keyword to a non-primary key column, specify True for the Column.autoincrement flag on the desired Column object, and ensure that Column.autoincrement is set to False on any integer primary key column:

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

在 1.4 版本发生变更: Added Identity construct in a Column to specify the start and increment parameters of an IDENTITY. These replace the use of the Sequence object in order to specify these values.

自 1.4 版本弃用: The mssql_identity_start and mssql_identity_increment parameters to Column are deprecated and should we replaced by an Identity object. Specifying both ways of configuring an IDENTITY will result in a compile error. These options are also no longer returned as part of the dialect_options key in Inspector.get_columns(). Use the information in the identity key instead.

在 1.4 版本发生变更: Removed the ability to use a Sequence object to modify IDENTITY characteristics. Sequence objects now only manipulate true T-SQL SEQUENCE types.

备注

There can only be one IDENTITY column on the table. When using autoincrement=True to enable the IDENTITY keyword, SQLAlchemy does not guard against multiple columns specifying the option simultaneously. The SQL Server database will instead reject the CREATE TABLE statement.

备注

An INSERT statement which attempts to provide a value for a column that is marked with IDENTITY will be rejected by SQL Server. In order for the value to be accepted, a session-level option “SET IDENTITY_INSERT” must be enabled. The SQLAlchemy SQL Server dialect will perform this operation automatically when using a core Insert construct; if the execution specifies a value for the IDENTITY column, the “IDENTITY_INSERT” option will be enabled for the span of that statement’s invocation.However, this scenario is not high performing and should not be relied upon for normal use. If a table doesn’t actually require IDENTITY behavior in its integer primary key column, the keyword should be disabled when creating the table by ensuring that autoincrement=False is set.

控制“起始”和“增量”¶

Controlling “Start” and “Increment”

中文

要精确控制 IDENTITY 的起始值与增量值，可将 Identity 传入 Column，并使用其 Identity.start 和 Identity.increment 参数:

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)),
)

上述 Table 对象将生成如下 CREATE TABLE 语句：

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

备注

Identity 对象除了 start 与 increment 外，还支持多个其他参数。然而 SQL Server 并不支持这些额外参数，因此它们在生成 DDL 时将被忽略。

英文

Specific control over the “start” and “increment” values for the IDENTITY generator are provided using the Identity.start and Identity.increment parameters passed to the Identity object:

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)),
)

The CREATE TABLE for the above Table object would be:

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

)

备注

The Identity object supports many other parameter in addition to start and increment. These are not supported by SQL Server and will be ignored when generating the CREATE TABLE ddl.

将 IDENTITY 与非整数数值类型结合使用¶

Using IDENTITY with Non-Integer numeric types

中文

SQL Server 还允许在 NUMERIC 列上使用 IDENTITY。为在 SQLAlchemy 中顺利实现此模式，建议列的主类型仍为 Integer，但可通过 TypeEngine.with_variant() 方法将其在底层数据库中具体实现为 Numeric:

from sqlalchemy import Column
from sqlalchemy import Integer
from sqlalchemy import Numeric
from sqlalchemy import String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()


class TestTable(Base):
    __tablename__ = "test"
    id = Column(
        Integer().with_variant(Numeric(10, 0), "mssql"),
        primary_key=True,
        autoincrement=True,
    )
    name = Column(String)

在上述示例中，使用 Integer().with_variant() 明确表达了意图。关于 autoincrement 仅适用于 Integer 类型的限制，是在元数据层面定义的，而非每个方言各自决定的。

采用上述模式时，插入行所返回的主键标识符（即赋值给 ORM 实例，如上例中的 TestTable 的 id）将是 Decimal() 实例，而不是 int，因为 SQL Server 返回的数值类型是 Numeric。若希望该返回类型为浮点数，可向 Numeric.asdecimal 传入 False。若希望将 Numeric(10, 0) 类型的值归一化为 Python 的整数类型（在 Python 3 中也支持任意精度长整型），可使用 TypeDecorator 进行如下封装:

from sqlalchemy import TypeDecorator


class NumericAsInteger(TypeDecorator):
    "将浮点返回值规范化为整数"

    impl = Numeric(10, 0, asdecimal=False)
    cache_ok = True

    def process_result_value(self, value, dialect):
        if value is not None:
            value = int(value)
        return value


class TestTable(Base):
    __tablename__ = "test"
    id = Column(
        Integer().with_variant(NumericAsInteger, "mssql"),
        primary_key=True,
        autoincrement=True,
    )
    name = Column(String)

英文

SQL Server also allows IDENTITY to be used with NUMERIC columns. To implement this pattern smoothly in SQLAlchemy, the primary datatype of the column should remain as Integer, however the underlying implementation type deployed to the SQL Server database can be specified as Numeric using TypeEngine.with_variant():

from sqlalchemy import Column
from sqlalchemy import Integer
from sqlalchemy import Numeric
from sqlalchemy import String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()


class TestTable(Base):
    __tablename__ = "test"
    id = Column(
        Integer().with_variant(Numeric(10, 0), "mssql"),
        primary_key=True,
        autoincrement=True,
    )
    name = Column(String)

In the above example, Integer().with_variant() provides clear usage information that accurately describes the intent of the code. The general restriction that autoincrement only applies to Integer is established at the metadata level and not at the per-dialect level.

When using the above pattern, the primary key identifier that comes back from the insertion of a row, which is also the value that would be assigned to an ORM object such as TestTable above, will be an instance of Decimal() and not int when using SQL Server. The numeric return type of the Numeric type can be changed to return floats by passing False to Numeric.asdecimal. To normalize the return type of the above Numeric(10, 0) to return Python ints (which also support “long” integer values in Python 3), use TypeDecorator as follows:

from sqlalchemy import TypeDecorator


class NumericAsInteger(TypeDecorator):
    "normalize floating point return values into ints"

    impl = Numeric(10, 0, asdecimal=False)
    cache_ok = True

    def process_result_value(self, value, dialect):
        if value is not None:
            value = int(value)
        return value


class TestTable(Base):
    __tablename__ = "test"
    id = Column(
        Integer().with_variant(NumericAsInteger, "mssql"),
        primary_key=True,
        autoincrement=True,
    )
    name = Column(String)

INSERT 行为¶

INSERT behavior

中文

处理 IDENTITY 列的插入时间涉及两种关键技术。最常见的做法是能够获取给定 IDENTITY 列的“最后插入值”，这个过程在许多情况下由 SQLAlchemy 隐式执行，最重要的是在 ORM 中。

获取此值的过程有几种变体：

在绝大多数情况下，SQL Server 中的 INSERT 语句会与 RETURNING 一起使用，以获取新生成的主键值：
```
INSERT INTO t (x) OUTPUT inserted.id VALUES (?)
```
从 SQLAlchemy 2.0 开始，默认情况下也会使用 INSERT 语句的“插入多个值”行为特性来优化多行 INSERT 语句；对于 SQL Server，这个特性会作用于带有 RETURNING 和不带 RETURNING 的 INSERT 语句。

在 2.0.10 版本发生变更: 由于行排序问题，SQLAlchemy 2.0.9 暂时禁用了 SQL Server 的 INSERT 语句的“插入多个值”行为特性。从 2.0.10 开始，该特性已重新启用，并针对事务单元要求的 RETURNING 排序进行了特殊处理。
当 RETURNING 不可用或通过 implicit_returning=False 被禁用时，将使用 scope_identity() 函数或 @@identity 变量；行为依据后端不同而有所不同：
- 在使用 PyODBC 时，会在 INSERT 语句的末尾附加 ; select scope_identity()；会获取第二个结果集以接收值。给定如下表：
  
  t = Table(
  “t”, metadata, Column(“id”, Integer, primary_key=True), Column(“x”, Integer), implicit_returning=False,
  
  )
  
  一个 INSERT 语句将如下所示：
```
INSERT INTO t (x) VALUES (?); select scope_identity()
```
- 其他方言如 pymssql 会在 INSERT 语句之后调用 SELECT scope_identity() AS lastrowid。如果将 use_scope_identity=False 传递给 create_engine()，则会使用 SELECT @@identity AS lastrowid 代替。

包含 IDENTITY 列的表将禁止显式引用身份列的 INSERT 语句。SQLAlchemy 方言会检测到当通过核心 insert() 构造（而非普通字符串 SQL）创建的 INSERT 构造中引用了身份列，并在这种情况下会在执行插入语句前发出 SET IDENTITY_INSERT ON，执行后发出 SET IDENTITY_INSERT OFF。给定如下示例：

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})

上述列将以 IDENTITY 创建，但我们发出的 INSERT 语句指定了显式值。在回显输出中我们可以看到 SQLAlchemy 如何处理：

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

这是一个适用于测试和批量插入场景的辅助用例。

英文

Handling of the IDENTITY column at INSERT time involves two key techniques. The most common is being able to fetch the “last inserted value” for a given IDENTITY column, a process which SQLAlchemy performs implicitly in many cases, most importantly within the ORM.

The process for fetching this value has several variants:

In the vast majority of cases, RETURNING is used in conjunction with INSERT statements on SQL Server in order to get newly generated primary key values:
```
INSERT INTO t (x) OUTPUT inserted.id VALUES (?)
```
As of SQLAlchemy 2.0, the INSERT 语句的“插入多个值”行为 feature is also used by default to optimize many-row INSERT statements; for SQL Server the feature takes place for both RETURNING and-non RETURNING INSERT statements.

在 2.0.10 版本发生变更: The INSERT 语句的“插入多个值”行为 feature for SQL Server was temporarily disabled for SQLAlchemy version 2.0.9 due to issues with row ordering. As of 2.0.10 the feature is re-enabled, with special case handling for the unit of work’s requirement for RETURNING to be ordered.
When RETURNING is not available or has been disabled via implicit_returning=False, either the scope_identity() function or the @@identity variable is used; behavior varies by backend:
- when using PyODBC, the phrase ; select scope_identity() will be appended to the end of the INSERT statement; a second result set will be fetched in order to receive the value. Given a table as:
```
t = Table(
    "t",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("x", Integer),
    implicit_returning=False,
)
```
  an INSERT will look like:
```
INSERT INTO t (x) VALUES (?); select scope_identity()
```
- Other dialects such as pymssql will call upon SELECT scope_identity() AS lastrowid subsequent to an INSERT statement. If the flag use_scope_identity=False is passed to create_engine(), the statement SELECT @@identity AS lastrowid is used instead.

A table that contains an IDENTITY column will prohibit an INSERT statement that refers to the identity column explicitly. The SQLAlchemy dialect will detect when an INSERT construct, created using a core insert() construct (not a plain string SQL), refers to the identity column, and in this case will emit SET IDENTITY_INSERT ON prior to the insert statement proceeding, and SET IDENTITY_INSERT OFF subsequent to the execution. Given this example:

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})

The above column will be created with IDENTITY, however the INSERT statement we emit is specifying explicit values. In the echo output we can see how SQLAlchemy handles this:

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

This is an auxiliary use case suitable for testing and bulk insert scenarios.

SEQUENCE 支持¶

SEQUENCE support

中文

Sequence 对象创建“真实”序列，即 CREATE SEQUENCE：

>>> from sqlalchemy importSequence>>> from sqlalchemy.schema importCreateSequence>>> from sqlalchemy.dialects importmssql>>> print(...     CreateSequence(Sequence("my_seq", start=1)).compile(...         dialect=mssql.dialect()...     )... )CREATE SEQUENCE my_seq START WITH 1

对于整数主键生成，SQL Server 的 IDENTITY 构造通常应优先于序列。

小技巧

T-SQL 的默认起始值是 -2**63，而不是大多数其他 SQL 数据库中的 1。用户应显式将 Sequence.start 设置为 1（如果这是期望的默认值）：

seq = Sequence(“my_sequence”, start=1)

在 1.4 版本加入: 添加了 SQL Server 对 Sequence 的支持

在 2.0 版本发生变更: SQL Server 方言将不再隐式渲染 CREATE SEQUENCE 中的 “START WITH 1”，这在 1.4 版本中首次实现。

英文

The Sequence object creates “real” sequences, i.e., CREATE SEQUENCE:

>>> from sqlalchemy importSequence>>> from sqlalchemy.schema importCreateSequence>>> from sqlalchemy.dialects importmssql>>> print(...     CreateSequence(Sequence("my_seq", start=1)).compile(...         dialect=mssql.dialect()...     )... )CREATE SEQUENCE my_seq START WITH 1

For integer primary key generation, SQL Server’s IDENTITY construct should generally be preferred vs. sequence.

小技巧

The default start value for T-SQL is -2**63 instead of 1 as in most other SQL databases. Users should explicitly set the Sequence.start to 1 if that’s the expected default:

seq = Sequence("my_sequence", start=1)

在 1.4 版本加入: added SQL Server support for Sequence

在 2.0 版本发生变更: The SQL Server dialect will no longer implicitly render “START WITH 1” for CREATE SEQUENCE, which was the behavior first implemented in version 1.4.

VARCHAR / NVARCHAR 上的 MAX¶

MAX on VARCHAR / NVARCHAR

中文

SQL Server 支持在 VARCHAR 和 NVARCHAR 数据类型中使用特殊字符串 “MAX” 来表示“最大长度”。该方言目前将其作为基本类型中的 “None” 长度处理，而不是提供这些类型的方言特定版本，这样指定如 VARCHAR(None) 的基本类型可以在多个后端上假设为“无长度”行为，而不使用特定方言的类型。

要构建一个 SQL Server VARCHAR 或 NVARCHAR 最大长度的列，可以使用 None：

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

)

英文

SQL Server supports the special string “MAX” within the VARCHAR and NVARCHAR datatypes, to indicate “maximum length possible”. The dialect currently handles this as a length of “None” in the base type, rather than supplying a dialect-specific version of these types, so that a base type specified such as VARCHAR(None) can assume “unlengthed” behavior on more than one backend without using dialect-specific types.

To build a SQL Server VARCHAR or NVARCHAR with MAX length, use None:

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

排序规则支持¶

Collation Support

中文

字符排序规则由基本字符串类型支持，通过字符串参数 “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

英文

Character collations are supported by the base string types, specified by the string argument “collation”:

from sqlalchemy import VARCHAR

Column("login", VARCHAR(32, collation="Latin1_General_CI_AS"))

When such a column is associated with a Table, the CREATE TABLE statement for this column will yield:

login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL

LIMIT/OFFSET 支持¶

LIMIT/OFFSET Support

中文

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

在 1.4 版本发生变更: 添加了对 SQL Server “OFFSET n ROWS” 和 “FETCH NEXT n ROWS” 语法的支持。

对于只指定 LIMIT 而没有 OFFSET 的语句，所有版本的 SQL Server 都支持 TOP 关键字。此语法在没有 OFFSET 子句的情况下用于所有 SQL Server 版本。像如下的语句：

select(some_table).limit(5)

将会转换为类似以下的 SQL：

SELECT TOP 5 col1, col2.. FROM table

对于 SQL Server 2012 之前的版本，使用 LIMIT 和 OFFSET，或者仅使用 OFFSET 的语句将会通过 ROW_NUMBER() 窗口函数进行转换。像如下的语句：

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

将会转换为类似以下的 SQL：

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。

英文

MSSQL has added support for LIMIT / OFFSET as of SQL Server 2012, via the “OFFSET n ROWS” and “FETCH NEXT n ROWS” clauses. SQLAlchemy supports these syntaxes automatically if SQL Server 2012 or greater is detected.

在 1.4 版本发生变更: support added for SQL Server “OFFSET n ROWS” and “FETCH NEXT n ROWS” syntax.

For statements that specify only LIMIT and no OFFSET, all versions of SQL Server support the TOP keyword. This syntax is used for all SQL Server versions when no OFFSET clause is present. A statement such as:

select(some_table).limit(5)

will render similarly to:

SELECT TOP 5 col1, col2.. FROM table

For versions of SQL Server prior to SQL Server 2012, a statement that uses LIMIT and OFFSET, or just OFFSET alone, will be rendered using the ROW_NUMBER() window function. A statement such as:

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

will render similarly to:

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

Note that when using LIMIT and/or OFFSET, whether using the older or newer SQL Server syntaxes, the statement must have an ORDER BY as well, else a CompileError is raised.

DDL 注释支持¶

DDL Comment Support

中文

评论支持，包括对 Table.comment 和 Column.comment 等属性的 DDL 渲染，以及反射这些注释的功能，在使用支持的 SQL Server 版本时得到支持。如果首次连接时检测到不支持的版本（如 Azure Synapse），通过检查 fn_listextendedproperty SQL 函数的存在，则会禁用评论支持，包括渲染和表注释反射，因为这两个功能依赖于 SQL Server 存储过程和函数，而这些在并非所有后端类型中可用。

要强制开启或关闭评论支持，可以绕过自动检测，在 create_engine() 中设置 supports_comments 参数：

e = create_engine(“mssql+pyodbc://u:p@dsn”, supports_comments=False)

在 2.0 版本加入: 为 SQL Server 方言添加了对表和列注释的支持，包括 DDL 生成和反射。

英文

Comment support, which includes DDL rendering for attributes such as Table.comment and Column.comment, as well as the ability to reflect these comments, is supported assuming a supported version of SQL Server is in use. If a non-supported version such as Azure Synapse is detected at first-connect time (based on the presence of the fn_listextendedproperty SQL function), comment support including rendering and table-comment reflection is disabled, as both features rely upon SQL Server stored procedures and functions that are not available on all backend types.

To force comment support to be on or off, bypassing autodetection, set the parameter supports_comments within create_engine():

e = create_engine("mssql+pyodbc://u:p@dsn", supports_comments=False)

在 2.0 版本加入: Added support for table and column comments for the SQL Server dialect, including DDL generation and reflection.

事务隔离级别¶

Transaction Isolation Level

中文

所有 SQL Server 方言都支持通过方言特定的参数 create_engine.isolation_level 来设置事务隔离级别，该参数由 create_engine() 接受，以及传递给 Connection.execution_options() 的 Connection.execution_options.isolation_level 参数。此功能通过为每个新连接发出 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 特有

隔离级别配置还有更多选项，例如链接到主 Engine 的“子引擎”对象，每个对象应用不同的隔离级别设置。有关背景信息，请参见设置事务隔离级别（包括 DBAPI 自动提交）。

参见

设置事务隔离级别（包括 DBAPI 自动提交）

英文

All SQL Server dialects support setting of transaction isolation level both via a dialect-specific parameter create_engine.isolation_level accepted by create_engine(), as well as the Connection.execution_options.isolation_level argument as passed to Connection.execution_options(). This feature works by issuing the command SET TRANSACTION ISOLATION LEVEL <level> for each new connection.

To set isolation level using create_engine():

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

To set using per-connection execution options:

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

Valid values for isolation_level include:

AUTOCOMMIT - pyodbc / pymssql-specific
READ COMMITTED
READ UNCOMMITTED
REPEATABLE READ
SERIALIZABLE
SNAPSHOT - specific to SQL Server

There are also more options for isolation level configurations, such as “sub-engine” objects linked to a main Engine which each apply different isolation level settings. See the discussion at 设置事务隔离级别（包括 DBAPI 自动提交） for background.

参见

设置事务隔离级别（包括 DBAPI 自动提交）

连接池的临时表/资源重置¶

Temporary Table / Resource Reset for Connection Pooling

中文

SQLAlchemy Engine 对象使用的 QueuePool 连接池实现包括 reset on return 行为，当连接返回到连接池时，会调用 DBAPI 的 .rollback() 方法。虽然此回滚将清除上一个事务使用的即时状态，但它并不涵盖会话级别的更广泛状态，包括临时表以及其他服务器状态，如预处理语句句柄和语句缓存。已知 SQL Server 有一个未记录的存储过程 sp_reset_connection，它是解决此问题的一个变通方法，可以重置连接上的大部分会话状态，包括临时表。

要将 sp_reset_connection 安装为执行 reset-on-return 的方法，可以使用 PoolEvents.reset() 事件钩子，如下例所示。通过将 create_engine.pool_reset_on_return 参数设置为 None，以便自定义方案可以完全替代默认行为。自定义钩子实现会在任何情况下调用 .rollback()，因为通常需要确保 DBAPI 自身的提交/回滚跟踪与事务的状态保持一致：

from sqlalchemy import create_engine from sqlalchemy import event

mssql_engine = create_engine(
“mssql+pyodbc://scott:tiger^5HHH@mssql2017:1433/test?driver=ODBC+Driver+17+for+SQL+Server”, # 禁用默认的 reset-on-return 方案 pool_reset_on_return=None,

)

@event.listens_for(mssql_engine, “reset”) def _reset_mssql(dbapi_connection, connection_record, reset_state):

if not reset_state.terminate_only:
dbapi_connection.execute(“{call sys.sp_reset_connection}”)

# 以便 DBAPI 本身知道连接已被重置 dbapi_connection.rollback()

在 2.0.0b3 版本发生变更: 为 PoolEvents.reset() 事件添加了额外的状态参数，并确保在所有“重置”发生时调用该事件，以便它适合作为自定义“重置”处理程序的地方。以前使用 PoolEvents.checkin() 处理程序的方案仍然可用。

参见

返回时重置 - 参见连接池文档

英文

The QueuePool connection pool implementation used by the SQLAlchemy Engine object includes reset on return behavior that will invoke the DBAPI .rollback() method when connections are returned to the pool. While this rollback will clear out the immediate state used by the previous transaction, it does not cover a wider range of session-level state, including temporary tables as well as other server state such as prepared statement handles and statement caches. An undocumented SQL Server procedure known as sp_reset_connection is known to be a workaround for this issue which will reset most of the session state that builds up on a connection, including temporary tables.

To install sp_reset_connection as the means of performing reset-on-return, the PoolEvents.reset() event hook may be used, as demonstrated in the example below. The create_engine.pool_reset_on_return parameter is set to None so that the custom scheme can replace the default behavior completely. The custom hook implementation calls .rollback() in any case, as it’s usually important that the DBAPI’s own tracking of commit/rollback will remain consistent with the state of the transaction:

from sqlalchemy import create_engine
from sqlalchemy import event

mssql_engine = create_engine(
    "mssql+pyodbc://scott:tiger^5HHH@mssql2017:1433/test?driver=ODBC+Driver+17+for+SQL+Server",
    # disable default reset-on-return scheme
    pool_reset_on_return=None,
)


@event.listens_for(mssql_engine, "reset")
def _reset_mssql(dbapi_connection, connection_record, reset_state):
    if not reset_state.terminate_only:
        dbapi_connection.execute("{call sys.sp_reset_connection}")

    # so that the DBAPI itself knows that the connection has been
    # reset
    dbapi_connection.rollback()

在 2.0.0b3 版本发生变更: Added additional state arguments to the PoolEvents.reset() event and additionally ensured the event is invoked for all “reset” occurrences, so that it’s appropriate as a place for custom “reset” handlers. Previous schemes which use the PoolEvents.checkin() handler remain usable as well.

参见

返回时重置 - in the 连接池 documentation

可空性¶

Nullability

中文

MSSQL 支持三种列的空值可用性级别。默认的空值可用性允许空值，并在 CREATE TABLE 语句中明确指定：

name VARCHAR(20) NULL

如果指定 nullable=None，则不做任何指定。换句话说，使用数据库配置的默认值。这将会渲染为：

name VARCHAR(20)

如果 nullable 为 True 或 False，则列将分别为 NULL 或 NOT NULL。

英文

MSSQL has support for three levels of column nullability. The default nullability allows nulls and is explicit in the CREATE TABLE construct:

name VARCHAR(20) NULL

If nullable=None is specified then no specification is made. In other words the database’s configured default is used. This will render:

name VARCHAR(20)

If nullable is True or False then the column will be NULL or NOT NULL respectively.

日期/时间处理¶

Date / Time Handling

中文

DATE 和 TIME 类型是支持的。绑定参数将根据大多数 MSSQL 驱动程序的要求转换为 datetime.datetime() 对象，并且如果需要，结果将从字符串中进行处理。对于 SQL Server 2005 及之前的版本，DATE 和 TIME 类型不可用。如果检测到 2008 以下的服务器版本，这些类型的 DDL 将会作为 DATETIME 类型发出。

英文

DATE and TIME are supported. Bind parameters are converted to datetime.datetime() objects as required by most MSSQL drivers, and results are processed from strings if needed. The DATE and TIME types are not available for MSSQL 2005 and previous - if a server version below 2008 is detected, DDL for these types will be issued as DATETIME.

大型文本/二进制类型弃用¶

Large Text/Binary Type Deprecation

中文

根据 SQL Server 2012/2014 文档，NTEXT、TEXT 和 IMAGE 数据类型将在未来的 SQL Server 版本中被移除。SQLAlchemy 通常将这些类型与 UnicodeText、TextClause 和 LargeBinary 数据类型相关联。

为了适应这一变化，方言中新增了一个标志 deprecate_large_types，该标志将在首次连接时自动根据使用的服务器版本进行设置，除非用户另行设置。该标志的行为如下：

当该标志为 True 时，使用 UnicodeText、TextClause 和 LargeBinary 数据类型进行 DDL 渲染时，将分别渲染为 NVARCHAR(max)、VARCHAR(max) 和 VARBINARY(max) 类型。这是添加该标志后的新行为。
当该标志为 False 时，使用 UnicodeText、TextClause 和 LargeBinary 数据类型进行 DDL 渲染时，将分别渲染为 NTEXT、TEXT 和 IMAGE 类型。这是这些类型的长期行为。
在数据库连接建立之前，标志的初始值为 None。如果使用方言渲染 DDL 而未设置该标志，它将被解释为 False。
在首次连接时，方言会检测是否使用了 SQL Server 2012 或更高版本；如果标志仍为 None，则会根据是否检测到 2012 或更高版本，将其设置为 True 或 False。
在创建方言时，可以将标志设置为 True 或 False，通常通过 create_engine() 完成:
```
eng = create_engine(
    "mssql+pymssql://user:pass@host/db", deprecate_large_types=True
)
```
通过使用大写类型对象，可以完全控制是否渲染“旧”或“新”类型： NVARCHAR、VARCHAR、VARBINARY、TEXT、NTEXT、IMAGE，这些类型将始终固定并始终输出精确的类型。

英文

Per SQL Server 2012/2014 Documentation, the NTEXT, TEXT and IMAGE datatypes are to be removed from SQL Server in a future release. SQLAlchemy normally relates these types to the UnicodeText, TextClause and LargeBinary datatypes.

In order to accommodate this change, a new flag deprecate_large_types is added to the dialect, which will be automatically set based on detection of the server version in use, if not otherwise set by the user. The behavior of this flag is as follows:

When this flag is True, the UnicodeText, TextClause and LargeBinary datatypes, when used to render DDL, will render the types NVARCHAR(max), VARCHAR(max), and VARBINARY(max), respectively. This is a new behavior as of the addition of this flag.
When this flag is False, the UnicodeText, TextClause and LargeBinary datatypes, when used to render DDL, will render the types NTEXT, TEXT, and IMAGE, respectively. This is the long-standing behavior of these types.
The flag begins with the value None, before a database connection is established. If the dialect is used to render DDL without the flag being set, it is interpreted the same as False.
On first connection, the dialect detects if SQL Server version 2012 or greater is in use; if the flag is still at None, it sets it to True or False based on whether 2012 or greater is detected.
The flag can be set to either True or False when the dialect is created, typically via create_engine():
```
eng = create_engine(
    "mssql+pymssql://user:pass@host/db", deprecate_large_types=True
)
```
Complete control over whether the “old” or “new” types are rendered is available in all SQLAlchemy versions by using the UPPERCASE type objects instead: NVARCHAR, VARCHAR, VARBINARY, TEXT, NTEXT, IMAGE will always remain fixed and always output exactly that type.

多部分架构名称¶

Multipart Schema Names

中文

SQL Server 架构有时需要多个部分来组成它们的“架构”限定符，即将数据库名称和所有者名称作为独立的令牌来表示，例如 mydatabase.dbo.some_table。可以使用 Table.schema 参数一次性设置这些多部分名称，方法如下:

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，而 “数据库” 将为 None:

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

要单独指定包含特殊字符或嵌入点的数据库和所有者名称，可以使用两组括号:

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

英文

SQL Server schemas sometimes require multiple parts to their “schema” qualifier, that is, including the database name and owner name as separate tokens, such as mydatabase.dbo.some_table. These multipart names can be set at once using the Table.schema argument of Table:

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

When performing operations such as table or component reflection, a schema argument that contains a dot will be split into separate “database” and “owner” components in order to correctly query the SQL Server information schema tables, as these two values are stored separately. Additionally, when rendering the schema name for DDL or SQL, the two components will be quoted separately for case sensitive names and other special characters. Given an argument as below:

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

The above schema would be rendered as [MyDataBase].dbo, and also in reflection, would be reflected using “dbo” as the owner and “MyDataBase” as the database name.

To control how the schema name is broken into database / owner, specify brackets (which in SQL Server are quoting characters) in the name. Below, the “owner” will be considered as MyDataBase.dbo and the “database” will be None:

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

To individually specify both database and owner name with special characters or embedded dots, use two sets of brackets:

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

传统架构模式¶

Legacy Schema Mode

中文

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 参数来启用，如上所示。

自 1.4 版本弃用: legacy_schema_aliasing 标志现在已被弃用，并将在未来的版本中移除。

英文

Very old versions of the MSSQL dialect introduced the behavior such that a schema-qualified table would be auto-aliased when used in a SELECT statement; given a table:

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

this legacy mode of rendering would assume that “customer_schema.account” would not be accepted by all parts of the SQL statement, as illustrated below:

>>> 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

This mode of behavior is now off by default, as it appears to have served no purpose; however in the case that legacy applications rely upon it, it is available using the legacy_schema_aliasing argument to create_engine() as illustrated above.

自 1.4 版本弃用: The legacy_schema_aliasing flag is now deprecated and will be removed in a future release.

聚集索引支持¶

Clustered Index Support

中文

MSSQL 方言通过 mssql_clustered 选项支持聚集索引（以及主键）。该选项可用于 Index、UniqueConstraint 和 PrimaryKeyConstraint。对于索引，该选项可与 mssql_columnstore 选项结合使用，以创建聚集列存储索引。

要生成聚集索引，使用如下代码:

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),

)

该表将被渲染为如下 SQL 语句：

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),

)

该表将被渲染为如下 SQL 语句：

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

英文

The MSSQL dialect supports clustered indexes (and primary keys) via the mssql_clustered option. This option is available to Index, UniqueConstraint. and PrimaryKeyConstraint. For indexes this option can be combined with the mssql_columnstore one to create a clustered columnstore index.

To generate a clustered index:

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

which renders the index as CREATE CLUSTERED INDEX my_index ON table (x).

To generate a clustered primary key use:

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

which will render the table, for example, as:

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

Similarly, we can generate a clustered unique constraint using:

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

To explicitly request a non-clustered primary key (for example, when a separate clustered index is desired), use:

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

which will render the table, for example, as:

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

列存储索引支持¶

Columnstore Index Support

中文

MSSQL 方言通过 mssql_columnstore 选项支持列存储索引。该选项可用于 Index。它可以与 mssql_clustered 选项结合使用，以创建聚集列存储索引。

要生成列存储索引，使用如下代码:

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

该索引将被渲染为 CREATE COLUMNSTORE INDEX my_index ON table (x)。

要生成聚集列存储索引，提供空的列定义:

idx = Index("my_index", mssql_clustered=True, mssql_columnstore=True)
# 需要将索引与表关联
table.append_constraint(idx)

上述代码将会渲染为 CREATE CLUSTERED COLUMNSTORE INDEX my_index ON table。

英文

The MSSQL dialect supports columnstore indexes via the mssql_columnstore option. This option is available to Index. It be combined with the mssql_clustered option to create a clustered columnstore index.

To generate a columnstore index:

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

which renders the index as CREATE COLUMNSTORE INDEX my_index ON table (x).

To generate a clustered columnstore index provide no columns:

idx = Index("my_index", mssql_clustered=True, mssql_columnstore=True)
# required to associate the index with the table
table.append_constraint(idx)

the above renders the index as CREATE CLUSTERED COLUMNSTORE INDEX my_index ON table.

在 2.0.18 版本加入.

MSSQL 特定索引选项¶

MSSQL-Specific Index Options

中文

除了集群之外，MSSQL 方言还支持 Index 的其他特殊选项。

英文

In addition to clustering, the MSSQL dialect supports other special options for Index.

INCLUDE¶

INCLUDE

中文

mssql_include 选项会将给定字符串名称渲染为 INCLUDE(colname):

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

会将索引渲染为 CREATE INDEX my_index ON table (x) INCLUDE (y)

英文

The mssql_include option renders INCLUDE(colname) for the given string names:

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

would render the index as CREATE INDEX my_index ON table (x) INCLUDE (y)

筛选索引¶

Filtered Indexes

中文

mssql_where 选项会针对给定的字符串名称渲染 WHERE(condition) 语句:

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

会将索引渲染为 CREATE INDEX my_index ON table (x) WHERE x > 10。

英文

The mssql_where option renders WHERE(condition) for the given string names:

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

would render the index as CREATE INDEX my_index ON table (x) WHERE x > 10.

索引排序¶

Index ordering

中文

索引排序可以通过函数表达式实现，例如:

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

会将索引渲染为 CREATE INDEX my_index ON table (x DESC)

参见

功能索引

英文

Index ordering is available via functional expressions, such as:

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

would render the index as CREATE INDEX my_index ON table (x DESC)

参见

功能索引

兼容级别¶

Compatibility Levels

中文

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

英文

MSSQL supports the notion of setting compatibility levels at the database level. This allows, for instance, to run a database that is compatible with SQL2000 while running on a SQL2005 database server. server_version_info will always return the database server version information (in this case SQL2005) and not the compatibility level information. Because of this, if running under a backwards compatibility mode SQLAlchemy may attempt to use T-SQL statements that are unable to be parsed by the database server.

触发器¶

Triggers

中文

默认情况下，SQLAlchemy 使用 OUTPUT INSERTED 来获取通过 IDENTITY 列或其他服务器端默认值生成的新主键值。MS-SQL 不允许在具有触发器的表上使用 OUTPUT INSERTED。要禁用在每个表级别上使用 OUTPUT INSERTED，可以为每个具有触发器的 Table 指定 implicit_returning=False:

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

声明式形式:

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

英文

SQLAlchemy by default uses OUTPUT INSERTED to get at newly generated primary key values via IDENTITY columns or other server side defaults. MS-SQL does not allow the usage of OUTPUT INSERTED on tables that have triggers. To disable the usage of OUTPUT INSERTED on a per-table basis, specify implicit_returning=False for each Table which has triggers:

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

Declarative form:

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

行数支持/ORM 版本控制¶

Rowcount Support / ORM Versioning

中文

SQL Server 驱动程序可能在返回 UPDATE 或 DELETE 语句的更新行数方面存在限制。

截至目前，PyODBC 驱动程序在使用 OUTPUT INSERTED 时无法返回行数。因此，SQLAlchemy 的早期版本在依赖准确行数以匹配版本号与匹配行数的功能（如 “ORM 版本控制” 功能）上存在限制。

SQLAlchemy 2.0 现在通过手动检索这些特定用例的 “rowcount” 来解决这个问题，方法是通过计算 RETURNING 中返回的行数；因此，尽管驱动程序仍然存在此限制，但 ORM 版本控制功能不再受其影响。自 SQLAlchemy 2.0.5 起，pyodbc 驱动程序已完全恢复 ORM 版本控制支持。

在 2.0.5 版本发生变更: 恢复了对 pyodbc 驱动程序的 ORM 版本控制支持。之前，在 ORM 刷新期间会发出警告，指示版本控制不受支持。

英文

The SQL Server drivers may have limited ability to return the number of rows updated from an UPDATE or DELETE statement.

As of this writing, the PyODBC driver is not able to return a rowcount when OUTPUT INSERTED is used. Previous versions of SQLAlchemy therefore had limitations for features such as the “ORM Versioning” feature that relies upon accurate rowcounts in order to match version numbers with matched rows.

SQLAlchemy 2.0 now retrieves the “rowcount” manually for these particular use cases based on counting the rows that arrived back within RETURNING; so while the driver still has this limitation, the ORM Versioning feature is no longer impacted by it. As of SQLAlchemy 2.0.5, ORM versioning has been fully re-enabled for the pyodbc driver.

在 2.0.5 版本发生变更: ORM versioning support is restored for the pyodbc driver. Previously, a warning would be emitted during ORM flush that versioning was not supported.

启用快照隔离¶

Enabling Snapshot Isolation

中文

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 has a default transaction isolation mode that locks entire tables, and causes even mildly concurrent applications to have long held locks and frequent deadlocks. Enabling snapshot isolation for the database as a whole is recommended for modern levels of concurrency support. This is accomplished via the following ALTER DATABASE commands executed at the SQL prompt:

ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON

ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON

Background on SQL Server snapshot isolation is available at https://msdn.microsoft.com/en-us/library/ms175095.aspx.

SQL Server SQL 构造¶

SQL Server SQL Constructs

Object Name	Description
try_cast(expression, type_)	Produce a `TRY_CAST` expression for backends which support it; this is a `CAST` which returns NULL for un-castable conversions.

function sqlalchemy.dialects.mssql.try_cast(expression: _ColumnExpressionOrLiteralArgument[Any], type_: _TypeEngineArgument[_T]) → TryCast[_T]¶

Produce a TRY_CAST expression for backends which support it; this is a CAST which returns NULL for un-castable conversions.

In SQLAlchemy, this construct is supported only by the SQL Server dialect, and will raise a CompileError if used on other included backends. However, third party backends may also support this construct.

小技巧

As try_cast() originates from the SQL Server dialect, it’s importable both from sqlalchemy. as well as from sqlalchemy.dialects.mssql.

try_cast() returns an instance of TryCast and generally behaves similarly to the Cast construct; at the SQL level, the difference between CAST and TRY_CAST is that TRY_CAST returns NULL for an un-castable expression, such as attempting to cast a string "hi" to an integer value.

E.g.:

from sqlalchemy import select, try_cast, Numeric

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

The above would render on Microsoft SQL Server as:

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

在 2.0.14 版本加入: try_cast() has been generalized from the SQL Server dialect into a general use construct that may be supported by additional dialects.

SQL Server 数据类型¶

SQL Server Data Types

中文

与所有SQLAlchemy方言一样，所有已知对SQL Server有效的UPPERCASE类型都可以从顶级方言中导入，无论它们是来自 sqlalchemy.types 还是来自本地方言:

from sqlalchemy.dialects.mssql import (
   BIGINT,
   BINARY,
   BIT,
   CHAR,
   DATE,
   DATETIME,
   DATETIME2,
   DATETIMEOFFSET,
   DECIMAL,
   DOUBLE_PRECISION,
   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特定构造参数的类型如下：

英文

As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with SQL server are importable from the top level dialect, whether they originate from sqlalchemy.types or from the local dialect:

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

Types which are specific to SQL Server, or have SQL Server-specific construction arguments, are as follows:

Object Name	Description
BIT	MSSQL BIT type.
DATETIME2
DATETIMEOFFSET
DOUBLE_PRECISION	the SQL Server DOUBLE PRECISION datatype.
IMAGE
JSON	MSSQL JSON type.
MONEY
NTEXT	MSSQL NTEXT type, for variable-length unicode text up to 2^30 characters.
REAL	the SQL Server REAL datatype.
ROWVERSION	Implement the SQL Server ROWVERSION type.
SMALLDATETIME
SMALLMONEY
SQL_VARIANT
TIME
TIMESTAMP	Implement the SQL Server TIMESTAMP type.
TINYINT
UNIQUEIDENTIFIER
XML	MSSQL XML type.

class sqlalchemy.dialects.mssql.BIT¶

MSSQL BIT type.

Both pyodbc and pymssql return values from BIT columns as Python <class ‘bool’> so just subclass Boolean.

Members

__init__()

Class signature

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

method sqlalchemy.dialects.mssql.BIT.__init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)¶

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

Construct a Boolean.

参数:

create_constraint¶ –
defaults to False. If the boolean is generated as an int/smallint, also create a CHECK constraint on the table that ensures 1 or 0 as a value.

备注

it is strongly recommended that the CHECK constraint have an explicit name in order to support schema-management concerns. This can be established either by setting the Boolean.name parameter or by setting up an appropriate naming convention; see 配置约束命名约定 for background.

在 1.4 版本发生变更: - this flag now defaults to False, meaning no CHECK constraint is generated for a non-native enumerated type.
name¶ – if a CHECK constraint is generated, specify the name of the constraint.

class sqlalchemy.dialects.mssql.CHAR

The SQL CHAR type.

Class signature

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

method sqlalchemy.dialects.mssql.CHAR.__init__(length: int | None = None, collation: str | None = None)

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

Create a string-holding type.

参数:

length¶ – optional, a length for the column for use in DDL and CAST expressions. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued if a VARCHAR with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation¶ –
Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.:
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
备注

In most cases, the Unicode or UnicodeText datatypes should be used for a Column that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database.

class sqlalchemy.dialects.mssql.DATETIME2¶: Class signature

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

class sqlalchemy.dialects.mssql.DATETIMEOFFSET¶: Class signature

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

class sqlalchemy.dialects.mssql.DOUBLE_PRECISION¶: the SQL Server DOUBLE PRECISION datatype.

在 2.0.11 版本加入.

Class signature

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

class sqlalchemy.dialects.mssql.IMAGE¶

Members

__init__()

Class signature

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

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

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

Construct a LargeBinary type.

参数:: length¶ – optional, a length for the column for use in DDL statements, for those binary types that accept a length, such as the MySQL BLOB type.

class sqlalchemy.dialects.mssql.JSON¶

MSSQL JSON type.

MSSQL supports JSON-formatted data as of SQL Server 2016.

The JSON datatype at the DDL level will represent the datatype as NVARCHAR(max), but provides for JSON-level comparison functions as well as Python coercion behavior.

JSON is used automatically whenever the base JSON datatype is used against a SQL Server backend.

参见

JSON - main documentation for the generic cross-platform JSON datatype.

The JSON type supports persistence of JSON values as well as the core index operations provided by JSON datatype, by adapting the operations to render the JSON_VALUE or JSON_QUERY functions at the database level.

The SQL Server JSON type necessarily makes use of the JSON_QUERY and JSON_VALUE functions when querying for elements of a JSON object. These two functions have a major restriction in that they are mutually exclusive based on the type of object to be returned. The JSON_QUERY function only returns a JSON dictionary or list, but not an individual string, numeric, or boolean element; the JSON_VALUE function only returns an individual string, numeric, or boolean element. both functions either return NULL or raise an error if they are not used against the correct expected value.

To handle this awkward requirement, indexed access rules are as follows:

When extracting a sub element from a JSON that is itself a JSON dictionary or list, the Comparator.as_json() accessor should be used:
```
stmt = select(data_table.c.data["some key"].as_json()).where(
    data_table.c.data["some key"].as_json() == {"sub": "structure"}
)
```
When extracting a sub element from a JSON that is a plain boolean, string, integer, or float, use the appropriate method among 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 版本加入.

Members

__init__()

Class signature

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

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

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

Construct a JSON type.

参数:

none_as_null=False¶ –

if True, persist the value None as a SQL NULL value, not the JSON encoding of null. Note that when this flag is False, the null() construct can still be used to persist a NULL value, which may be passed directly as a parameter value that is specially interpreted by the JSON type as SQL NULL:

from sqlalchemy import null

conn.execute(table.insert(), {"data": null()})

备注

JSON.none_as_null does not apply to the values passed to Column.default and Column.server_default; a value of None passed for these parameters means “no default present”.

Additionally, when used in SQL comparison expressions, the Python value None continues to refer to SQL null, and not JSON NULL. The JSON.none_as_null flag refers explicitly to the persistence of the value within an INSERT or UPDATE statement. The JSON.NULL value should be used for SQL expressions that wish to compare to JSON null.

参见

JSON.NULL

class sqlalchemy.dialects.mssql.MONEY¶: Class signature

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

class sqlalchemy.dialects.mssql.NCHAR

The SQL NCHAR type.

Class signature

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

method sqlalchemy.dialects.mssql.NCHAR.__init__(length: int | None = None, collation: str | None = None)

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

Create a string-holding type.

参数:

length¶ – optional, a length for the column for use in DDL and CAST expressions. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued if a VARCHAR with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation¶ –
Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.:
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
备注

In most cases, the Unicode or UnicodeText datatypes should be used for a Column that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database.

class sqlalchemy.dialects.mssql.NTEXT¶

MSSQL NTEXT type, for variable-length unicode text up to 2^30 characters.

Members

__init__()

Class signature

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

method sqlalchemy.dialects.mssql.NTEXT.__init__(length: int | None = None, collation: str | None = None)¶

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

Create a string-holding type.

参数:

length¶ – optional, a length for the column for use in DDL and CAST expressions. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued if a VARCHAR with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation¶ –
Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.:
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
备注

In most cases, the Unicode or UnicodeText datatypes should be used for a Column that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database.

class sqlalchemy.dialects.mssql.NVARCHAR

The SQL NVARCHAR type.

Class signature

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

method sqlalchemy.dialects.mssql.NVARCHAR.__init__(length: int | None = None, collation: str | None = None)

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

Create a string-holding type.

参数:

length¶ – optional, a length for the column for use in DDL and CAST expressions. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued if a VARCHAR with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation¶ –
Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.:
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
备注

In most cases, the Unicode or UnicodeText datatypes should be used for a Column that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database.

class sqlalchemy.dialects.mssql.REAL¶: the SQL Server REAL datatype.

Class signature

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

class sqlalchemy.dialects.mssql.ROWVERSION¶

Implement the SQL Server ROWVERSION type.

The ROWVERSION datatype is a SQL Server synonym for the TIMESTAMP datatype, however current SQL Server documentation suggests using ROWVERSION for new datatypes going forward.

The ROWVERSION datatype does not reflect (e.g. introspect) from the database as itself; the returned datatype will be TIMESTAMP.

This is a read-only datatype that does not support INSERT of values.

参见

TIMESTAMP

Members

__init__()

Class signature

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

Construct a TIMESTAMP or ROWVERSION type.

参数:: convert_int¶ – if True, binary integer values will be converted to integers on read.

class sqlalchemy.dialects.mssql.SMALLDATETIME¶

Members

__init__()

Class signature

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

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

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

Construct a new DateTime.

参数:: timezone¶ – boolean. Indicates that the datetime type should enable timezone support, if available on the base date/time-holding type only. It is recommended to make use of the TIMESTAMP datatype directly when using this flag, as some databases include separate generic date/time-holding types distinct from the timezone-capable TIMESTAMP datatype, such as Oracle Database.

class sqlalchemy.dialects.mssql.SMALLMONEY¶: Class signature

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

class sqlalchemy.dialects.mssql.SQL_VARIANT¶: Class signature

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

class sqlalchemy.dialects.mssql.TEXT

The SQL TEXT type.

Class signature

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

method sqlalchemy.dialects.mssql.TEXT.__init__(length: int | None = None, collation: str | None = None)

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

Create a string-holding type.

参数:

length¶ – optional, a length for the column for use in DDL and CAST expressions. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued if a VARCHAR with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation¶ –
Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.:
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
备注

In most cases, the Unicode or UnicodeText datatypes should be used for a Column that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database.

class sqlalchemy.dialects.mssql.TIME¶: Class signature

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

class sqlalchemy.dialects.mssql.TIMESTAMP¶

Implement the SQL Server TIMESTAMP type.

Note this is completely different than the SQL Standard TIMESTAMP type, which is not supported by SQL Server. It is a read-only datatype that does not support INSERT of values.

参见

ROWVERSION

Members

__init__()

Class signature

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

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

Construct a TIMESTAMP or ROWVERSION type.

参数:: convert_int¶ – if True, binary integer values will be converted to integers on read.

class sqlalchemy.dialects.mssql.TINYINT¶: Class signature

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

class sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER¶

Members

__init__()

Class signature

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

method sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER.__init__(as_uuid: bool = True)¶

Construct a UNIQUEIDENTIFIER type.

参数:

as_uuid=True¶ –

if True, values will be interpreted as Python uuid objects, converting to/from string via the DBAPI.

在 2.0 版本发生变更: Added direct “uuid” support to the UNIQUEIDENTIFIER datatype; uuid interpretation defaults to True.

class sqlalchemy.dialects.mssql.VARBINARY

The MSSQL VARBINARY type.

This type adds additional features to the core VARBINARY type, including “deprecate_large_types” mode where either VARBINARY(max) or IMAGE is rendered, as well as the SQL Server FILESTREAM option.

参见

大型文本/二进制类型弃用

Class signature

class sqlalchemy.dialects.mssql.VARBINARY (sqlalchemy.types.VARBINARY, sqlalchemy.types.LargeBinary)

method sqlalchemy.dialects.mssql.VARBINARY.__init__(length=None, filestream=False)

Construct a VARBINARY type.

参数:

length¶ – optional, a length for the column for use in DDL statements, for those binary types that accept a length, such as the MySQL BLOB type.
filestream=False¶ –
if True, renders the FILESTREAM keyword in the table definition. In this case length must be None or 'max'.

在 1.4.31 版本加入.

class sqlalchemy.dialects.mssql.VARCHAR

The SQL VARCHAR type.

Class signature

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

method sqlalchemy.dialects.mssql.VARCHAR.__init__(length: int | None = None, collation: str | None = None)

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

Create a string-holding type.

参数:

length¶ – optional, a length for the column for use in DDL and CAST expressions. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued if a VARCHAR with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation¶ –
Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.:
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
备注

In most cases, the Unicode or UnicodeText datatypes should be used for a Column that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database.

class sqlalchemy.dialects.mssql.XML¶

MSSQL XML type.

This is a placeholder type for reflection purposes that does not include any Python-side datatype support. It also does not currently support additional arguments, such as “CONTENT”, “DOCUMENT”, “xml_schema_collection”.

Members

__init__()

Class signature

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

method sqlalchemy.dialects.mssql.XML.__init__(length: int | None = None, collation: str | None = None)¶

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

Create a string-holding type.

参数:

length¶ – optional, a length for the column for use in DDL and CAST expressions. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued if a VARCHAR with no length is included. Whether the value is interpreted as bytes or characters is database specific.
collation¶ –
Optional, a column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. E.g.:
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
备注

In most cases, the Unicode or UnicodeText datatypes should be used for a Column that expects to store non-ascii data. These datatypes will ensure that the correct types are used on the database.

pymssql¶

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

Connecting¶

Connect String:

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

中文

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

在 2.0.5 版本发生变更: pymssql 恢复到 SQLAlchemy 的持续集成测试

英文

pymssql is a Python module that provides a Python DBAPI interface around FreeTDS.

在 2.0.5 版本发生变更: pymssql was restored to SQLAlchemy’s continuous integration testing

aioodbc¶

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

DBAPI¶

Documentation and download information (if applicable) for aioodbc is available at: https://pypi.org/project/aioodbc/

Connecting¶

Connect String:

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

中文

对 SQL Server 数据库的 asyncio 风格支持，使用的是 aioodbc 驱动，该驱动本质上是对 pyodbc 的线程封装。

在 2.0.23 版本加入.

新增了 mssql+aioodbc 方言，构建于 pyodbc 和通用 aio* 方言架构之上。

通过一个特殊的 asyncio 中介层，aioodbc 方言可作为 SQLAlchemy asyncio 扩展包的后端使用。

该驱动的大多数行为和注意事项与 SQL Server 所使用的 pyodbc 方言相同；一般背景信息请参见 PyODBC。

该方言通常应仅通过 create_async_engine() 引擎创建函数使用；其连接方式与 pyodbc 部分文档中描述的方式一致:

from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(
    "mssql+aioodbc://scott:tiger@mssql2017:1433/test?"
    "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
)

英文

Support for the SQL Server database in asyncio style, using the aioodbc driver which itself is a thread-wrapper around pyodbc.

在 2.0.23 版本加入: Added the mssql+aioodbc dialect which builds on top of the pyodbc and general aio* dialect architecture.

Using a special asyncio mediation layer, the aioodbc dialect is usable as the backend for the SQLAlchemy asyncio extension package.

Most behaviors and caveats for this driver are the same as that of the pyodbc dialect used on SQL Server; see PyODBC for general background.

This dialect should normally be used only with the create_async_engine() engine creation function; connection styles are otherwise equivalent to those documented in the pyodbc section:

from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(
    "mssql+aioodbc://scott:tiger@mssql2017:1433/test?"
    "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
)

Microsoft SQL Server¶

DBAPI Support¶

外部方言¶

自动增量行为 / IDENTITY 列¶

控制“起始”和“增量”¶

将 IDENTITY 与非整数数值类型结合使用¶

INSERT 行为¶

SEQUENCE 支持¶

VARCHAR / NVARCHAR 上的 MAX¶

排序规则支持¶

LIMIT/OFFSET 支持¶

DDL 注释支持¶

事务隔离级别¶

连接池的临时表/资源重置¶

可空性¶

日期/时间处理¶

大型文本/二进制类型弃用¶

多部分架构名称¶

传统架构模式¶

聚集索引支持¶

列存储索引支持¶

MSSQL 特定索引选项¶

INCLUDE¶

筛选索引¶

索引排序¶

兼容级别¶

触发器¶

行数支持/ORM 版本控制¶

启用快照隔离¶

SQL Server SQL 构造¶

SQL Server 数据类型¶

PyODBC¶

DBAPI¶

Connecting¶

连接到 PyODBC¶

DSN 连接¶

主机名连接¶

传递精确的 Pyodbc 字符串¶

使用访问令牌连接到数据库¶

避免 Azure Synapse Analytics 上出现与事务相关的异常¶

为 Azure SQL 数据仓库 (DW) 连接启用自动提交¶

避免以 TEXT/NTEXT 格式发送大型字符串参数¶

Pyodbc 池化/连接关闭行为¶

驱动程序/Unicode 支持¶

行数支持¶

快速执行模式¶

设置输入大小支持¶

pymssql¶

Connecting¶

aioodbc¶

DBAPI¶

Connecting¶