SqlAlchemy 2.0 中文文档（五十二）（7）

SqlAlchemy 2.0 中文文档（五十二）（6）https://developer.aliyun.com/article/1563145

驱动程序 / Unicode 支持

PyODBC 最适合与 Microsoft ODBC 驱动程序一起使用，特别是在 Python 2 和 Python 3 上的 Unicode 支持方面。

在 Linux 或 OSX 上使用 FreeTDS ODBC 驱动程序与 PyODBC 不推荐；在这个领域，包括在  Microsoft 为 Linux 和 OSX 提供 ODBC 驱动程序之前，历史上存在许多与 Unicode 相关的问题。现在  Microsoft 为所有平台提供驱动程序，对于 PyODBC 支持，建议使用这些驱动程序。FreeTDS 对于非 ODBC 驱动程序（如  pymssql）仍然很重要，在那里它运行得非常好。

行数支持

截至 SQLAlchemy 2.0.5 版本，已解决了 Pyodbc 与 SQLAlchemy ORM 的“版本化行”功能的先前限制。请参阅行数支持 / ORM 版本控制处的说明。

快速执行多个模式

PyODBC 驱动程序包括对“快速执行多个”执行模式的支持，当使用 Microsoft ODBC 驱动程序时，对于适合内存的有限大小批次的 DBAPI executemany() 调用，可以大大减少往返次数。该功能通过在要使用 executemany 调用时在 DBAPI 游标上设置属性.fast_executemany 来启用。当仅使用Microsoft ODBC 驱动程序时，SQLAlchemy PyODBC SQL Server 方言支持通过将 fast_executemany 参数传递给 create_engine() 来支持此参数：

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

从版本 2.0.9 开始更改：- fast_executemany参数现在对于执行多个参数集的所有 INSERT 语句具有其预期效果，不包括 RETURNING。以前，SQLAlchemy 2.0 的 insertmanyvalues 功能会导致在大多数情况下即使指定了fast_executemany也不会使用。

版本 1.3 中的新功能。

另请参阅

fast executemany - 在 github 上 ### Setinputsizes 支持

从版本 2.0 开始，pyodbc 的cursor.setinputsizes()方法用于所有语句执行，除了在fast_executemany=True时不支持cursor.executemany()调用（假设 insertmanyvalues 已启用，“fastexecutemany”在任何情况下都不会对 INSERT 语句生效）。

通过向create_engine()传递use_setinputsizes=False可以禁用cursor.setinputsizes()的使用。

当use_setinputsizes保持默认值True时，传递给cursor.setinputsizes()的特定每种类型符号可以使用DialectEvents.do_setinputsizes()钩子进行程序化定制。请参阅该方法以获取用法示例。

从版本 2.0 开始更改：mssql+pyodbc 方言现在默认为所有语句执行使用use_setinputsizes=True，除了在fast_executemany=True时的 cursor.executemany()调用。可以通过向create_engine()传递use_setinputsizes=False来关闭此行为。

DBAPI

PyODBC 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/pyodbc/

连接

连接字符串：

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

连接到 PyODBC

此处的 URL 将被翻译为 PyODBC 连接字符串，详细信息请参阅ConnectionStrings。

DSN 连接

ODBC 中的 DSN 连接意味着客户端机器上配置了预先存在的 ODBC 数据源。然后，应用程序指定此数据源的名称，其中包括诸如正在使用的特定 ODBC 驱动程序以及数据库的网络地址等详细信息。假设客户端上配置了数据源，基本的基于 DSN 的连接如下所示：

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

以上内容将向 PyODBC 传递以下连接字符串：

DSN=some_dsn;UID=scott;PWD=tiger

如果省略了用户名和密码，DSN 表单还将向 ODBC 字符串添加Trusted_Connection=yes指令。

主机名连接

pyodbc 也支持基于主机名的连接。这通常比使用 DSN 更容易，并且具有以下额外的优势：可以在 URL 中本地指定要连接的特定数据库名称，而不是将其作为数据源配置的固定部分。

使用主机名连接时，还必须在 URL 的查询参数中指定驱动程序名称。由于这些名称通常包含空格，因此名称必须进行 URL 编码，这意味着使用加号代替空格：

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

driver 关键字对于 pyodbc 方言是重要的，并且必须以小写形式指定。

在查询字符串中传递的任何其他名称都将通过 pyodbc 连接字符串传递，例如 authentication、TrustServerCertificate 等。多个关键字参数必须用和号 (&) 分隔；在内部生成 pyodbc 连接字符串时，这些将被翻译为分号：

e = create_engine(
    "mssql+pyodbc://scott:tiger@mssql2017:1433/test?"
    "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
    "&authentication=ActiveDirectoryIntegrated"
)

可以使用 URL 构造等效的 URL：

from sqlalchemy.engine import URL
connection_url = URL.create(
    "mssql+pyodbc",
    username="scott",
    password="tiger",
    host="mssql2017",
    port=1433,
    database="test",
    query={
        "driver": "ODBC Driver 18 for SQL Server",
        "TrustServerCertificate": "yes",
        "authentication": "ActiveDirectoryIntegrated",
    },
)

通过准确的 Pyodbc 字符串传递

也可以直接以 pyodbc 的格式发送 PyODBC 连接字符串，如 PyODBC 文档 中所指定，使用参数 odbc_connect。URL 对象可以帮助简化这一过程：

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)

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

一些数据库服务器仅设置为仅接受访问令牌进行登录。例如，SQL Server 允许使用 Azure Active Directory 令牌连接到数据库。这需要使用 azure-identity 库创建凭据对象。有关身份验证步骤的更多信息，请参阅 Microsoft 文档。

获得引擎后，每次请求连接时都需要将凭据发送给 pyodbc.connect。一种方法是在引擎上设置事件侦听器，以将凭据令牌添加到方言的连接调用中。关于这一点，可以在 生成动态认证令牌 中进行更一般的讨论。特别对于 SQL Server，这是作为 ODBC 连接属性传递的，具有由 Microsoft 描述的数据结构。

以下代码片段将创建一个使用 Azure 凭据连接到 Azure SQL 数据库的引擎：

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}

提示

当没有用户名或密码时，SQLAlchemy pyodbc 方言当前会添加Trusted_Connection令牌。根据微软的文档，使用访问令牌时连接字符串不能包含UID、PWD、Authentication或Trusted_Connection参数，这需要删除。#### 避免 Azure Synapse Analytics 上的与事务相关的异常

Azure Synapse Analytics 在处理事务方面与普通的 SQL Server 有显着的不同；在某些情况下，Synapse 事务内的错误可能导致服务器端任意终止，这将导致 DBAPI 的.rollback()方法（以及.commit()）失败。该问题阻止了通常的 DBAPI 合同，即允许.rollback()在没有事务存在时静默通过，因为驱动程序不期望出现这种情况。此失败的症状是，在某种操作失败后尝试发出.rollback()时出现类似于‘No corresponding transaction found. (111214)’的异常消息。

可以通过以下方式通过create_engine()函数将ignore_no_transaction_on_rollback=True传递给 SQL Server 方言来处理此特定情况：

engine = create_engine(connection_url, ignore_no_transaction_on_rollback=True)

使用上述参数，方言将捕获在connection.rollback()期间引发的ProgrammingError异常，并在错误消息包含代码111214时发出警告，但不会引发异常。

新版本 1.4.40 中添加了ignore_no_transaction_on_rollback=True参数。

为 Azure SQL Data Warehouse（DW）连接启用自动提交

Azure SQL Data Warehouse 不支持事务，这可能会导致 SQLAlchemy 的“autobegin”（和隐式提交/回滚）行为出现问题。我们可以通过在 pyodbc 和引擎级别启用自动提交来避免这些问题：

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

避免将大型字符串参数发送为 TEXT/NTEXT

出于历史原因，默认情况下，Microsoft 的 SQL Server ODBC 驱动程序将长字符串参数（大于 4000 个 SBCS  字符或 2000 个 Unicode 字符）发送为 TEXT/NTEXT 值。多年来，TEXT 和 NTEXT 已经过时，并且开始与  SQL_Server/Azure 的新版本引起兼容性问题。例如，请参阅此问题。

从 ODBC 驱动程序 18 开始，我们可以通过LongAsMax=Yes连接字符串参数覆盖传统行为，并将长字符串传递为 varchar(max)/nvarchar(max)：

connection_url = sa.engine.URL.create(
    "mssql+pyodbc",
    username="scott",
    password="tiger",
    host="mssqlserver.example.com",
    database="mydb",
    query={
        "driver": "ODBC Driver 18 for SQL Server",
        "LongAsMax": "Yes",
    },
)

DSN 连接

ODBC 中的 DSN 连接意味着客户端计算机上配置了预定义的 ODBC 数据源。然后，应用程序指定此数据源的名称，其中包括诸如正在使用的特定 ODBC 驱动程序以及数据库的网络地址等详细信息。假设客户端上配置了数据源，基本的基于 DSN 的连接如下所示：

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

以上内容将传递以下连接字符串给 PyODBC：

DSN=some_dsn;UID=scott;PWD=tiger

如果省略了用户名和密码，则 DSN 表单还将在 ODBC 字符串中添加 Trusted_Connection=yes 指令。

主机名连接

基于主机名的连接也受 pyodbc 支持。这些通常比 DSN 更容易使用，并且具有其他优点，即可以在 URL 中本地指定要连接的特定数据库名称，而不是作为数据源配置的一部分固定下来。

当使用主机名连接时，驱动程序名称也必须在 URL 的查询参数中指定。由于这些名称通常包含空格，因此名称必须进行 URL 编码，这意味着用加号代替空格：

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

driver 关键字对于 pyodbc 方言至关重要，必须以小写指定。

查询字符串中传递的任何其他名称都将通过 pyodbc 连接字符串传递，例如authentication、TrustServerCertificate等。多个关键字参数必须用 ampersand (&) 分隔；在生成内部 pyodbc 连接字符串时，这些将被翻译为分号：

e = create_engine(
    "mssql+pyodbc://scott:tiger@mssql2017:1433/test?"
    "driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
    "&authentication=ActiveDirectoryIntegrated"
)

可以使用 URL 构造等效的 URL：

from sqlalchemy.engine import URL
connection_url = URL.create(
    "mssql+pyodbc",
    username="scott",
    password="tiger",
    host="mssql2017",
    port=1433,
    database="test",
    query={
        "driver": "ODBC Driver 18 for SQL Server",
        "TrustServerCertificate": "yes",
        "authentication": "ActiveDirectoryIntegrated",
    },
)

经过准确的 Pyodbc 字符串

PyODBC 连接字符串也可以直接以 pyodbc 格式发送，如 PyODBC 文档 中所述，使用参数 odbc_connect。URL 对象可以帮助简化此过程：

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)

使用访问令牌连接数据库

某些数据库服务器设置为仅接受访问令牌进行登录。例如，SQL Server 允许使用 Azure Active Directory 令牌连接到数据库。这需要使用 azure-identity 库创建凭据对象。有关身份验证步骤的更多信息，请参阅 微软文档。

获得引擎后，每次请求连接都需要将凭据发送到 pyodbc.connect。一种方法是在引擎上设置一个事件侦听器，该事件侦听器将凭据令牌添加到方言的连接调用中。这在 生成动态认证令牌 中更一般地讨论过。特别对于 SQL Server，这是作为 ODBC 连接属性传递的，其数据结构由 Microsoft 描述。

以下代码片段将创建一个引擎，该引擎使用 Azure 凭据连接到 Azure SQL 数据库：

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}

提示

当没有用户名或密码时，SQLAlchemy pyodbc 方言当前会添加 Trusted_Connection 令牌。根据 Microsoft 的 Azure 访问令牌文档，当使用访问令牌时，连接字符串不得包含 UID、PWD、Authentication 或 Trusted_Connection 参数，因此需要删除此参数。

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

Azure Synapse Analytics 在事务处理方面与普通 SQL Server 有显着差异；在某些情况下，Synapse 事务中的错误可能导致服务器端任意终止，这会导致 DBAPI 的 .rollback() 方法（以及 .commit()）失败。该问题阻止了通常的 DBAPI 契约，即允许 .rollback() 在没有事务存在时悄无声息地传递，因为驱动程序不期望出现这种情况。此失败的症状是在尝试在某种操作失败后发出 .rollback() 时出现类似于 ‘No corresponding transaction found. (111214)’ 的消息的异常。

通过以下方式将 ignore_no_transaction_on_rollback=True 传递给 SQL Server 方言，可以处理这种特殊情况，通过 create_engine() 函数：

engine = create_engine(connection_url, ignore_no_transaction_on_rollback=True)

使用上述参数，方言将捕获 connection.rollback() 期间引发的 ProgrammingError 异常，并在错误消息中包含代码 111214 时发出警告，但不会引发异常。

新版本 1.4.40 中新增了 ignore_no_transaction_on_rollback=True 参数。

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

Azure SQL 数据仓库不支持事务，这可能会导致 SQLAlchemy 的 “自动开始” (以及隐式提交/回滚) 行为出现问题。我们可以通过在 pyodbc 和引擎级别启用自动提交来避免这些问题：

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

避免将大型字符串参数发送为 TEXT/NTEXT

出于历史原因，默认情况下，Microsoft 的 ODBC 驱动程序会将长字符串参数（大于 4000 个 SBCS 字符或 2000 个  Unicode 字符）发送为 TEXT/NTEXT 值。多年来，TEXT 和 NTEXT 已经被弃用，并且开始在新版本的  SQL_Server/Azure 中引起兼容性问题。例如，请参阅此问题。

从 ODBC Driver 18 for SQL Server 开始，我们可以通过LongAsMax=Yes连接字符串参数覆盖传递长字符串作为 varchar(max)/nvarchar(max)的传统行为：

connection_url = sa.engine.URL.create(
    "mssql+pyodbc",
    username="scott",
    password="tiger",
    host="mssqlserver.example.com",
    database="mydb",
    query={
        "driver": "ODBC Driver 18 for SQL Server",
        "LongAsMax": "Yes",
    },
)

Pyodbc 连接池/连接关闭行为

PyODBC 默认使用内部连接池，这意味着连接的生命周期将比在 SQLAlchemy 内部更长。由于 SQLAlchemy 具有自己的连接池行为，通常最好禁用此行为。此行为只能在创建任何连接之前在 PyODBC 模块级别全局禁用：

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

如果将此变量保留在其默认值True，应用程序将继续保持活动数据库连接，即使 SQLAlchemy 引擎本身完全丢弃连接或引擎被处理。

另请参见

连接池 - 在 PyODBC 文档中。

驱动程序/Unicode 支持

PyODBC 最适合与 Microsoft ODBC 驱动程序一起使用，特别是在 Python 2 和 Python 3 的 Unicode 支持领域。

在 Linux 或 OSX 上使用 FreeTDS ODBC 驱动与 PyODBC 不推荐；在这个领域历史上存在许多与  Unicode 相关的问题，包括在 Microsoft 为 Linux 和 OSX 提供 ODBC 驱动之前。现在 Microsoft  为所有平台提供驱动程序，对于 PyODBC 支持，这些是推荐的。FreeTDS 仍然适用于非 ODBC 驱动程序，如  pymssql，在这里它运行得非常好。

行数支持

截至 SQLAlchemy 2.0.5 版本，已解决了 Pyodbc 与 SQLAlchemy ORM 的“版本化行”功能的先前限制。请参阅 Rowcount Support / ORM Versioning 中的说明。

快速 Executemany 模式

PyODBC 驱动程序包括对“快速 executemany”执行模式的支持，当使用 Microsoft ODBC 驱动程序时，对于适合内存的有限大小批次的 DBAPI executemany()调用大大减少了往返次数。当要使用 executemany 调用时，在 DBAPI 游标上设置属性.fast_executemany即可启用此功能。SQLAlchemy PyODBC SQL Server 方言通过将fast_executemany参数传递给create_engine()来支持此参数，仅使用Microsoft ODBC 驱动程序：

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

2.0.9 版本更改：- fast_executemany 参数现在对具有多个参数集的所有 INSERT 语句产生了预期的效果，这些参数集不包括 RETURNING。在以前的情况下，即使指定了，SQLAlchemy 2.0 的 insertmanyvalues 特性也会导致在大多数情况下不使用 fast_executemany。

新功能版本 1.3。

另请参阅

快速执行多次 - 在 github 上

Setinputsizes 支持

从版本 2.0 开始，pyodbc 的 cursor.setinputsizes() 方法用于所有语句执行，除了 cursor.executemany() 调用 fast_executemany=True 的情况下不支持（假设保持 insertmanyvalues 已启用，“fastexecutemany” 将不会对任何情况下的 INSERT 语句产生作用）。

通过将 use_setinputsizes=False 传递给 create_engine() 可以禁用 cursor.setinputsizes() 的使用。

当 use_setinputsizes 保持默认值 True 时，传递给 cursor.setinputsizes() 的具体每种类型的符号可以使用 DialectEvents.do_setinputsizes() 钩子进行程序化定制。查看该方法以获取用法示例。

2.0 版本更改：mssql+pyodbc 方言现在默认为所有语句执行使用 use_setinputsizes=True，除了 cursor.executemany() 调用 fast_executemany=True 时的情况。可以通过将 use_setinputsizes=False 传递给 create_engine() 来关闭此行为。

pymssql

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

连接

连接字符串：

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

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

2.0.5 版本更改：pymssql 已恢复到 SQLAlchemy 的持续集成测试中。

连接

连接字符串：

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

aioodbc

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

DBAPI

aioodbc 的文档和下载信息（如适用）可在此处获取：pypi.org/project/aioodbc/

连接

连接字符串：

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

通过 aioodbc 驱动程序以 asyncio 风格支持 SQL Server 数据库，该驱动程序本身是围绕 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"
)

DBAPI

文档和下载信息（如果适用）可在以下网址找到：pypi.org/project/aioodbc/

连接中

连接字符串：

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

c",
 username=“scott”,
 password=“tiger”,
 host=“mssqlserver.example.com”,
 database=“mydb”,
 query={
 “driver”: “ODBC Driver 18 for SQL Server”,
 “LongAsMax”: “Yes”,
 },
 )

### Pyodbc 连接池/连接关闭行为
PyODBC 默认使用内部[连接池](https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pooling)，这意味着连接的生命周期将比在 SQLAlchemy 内部更长。由于 SQLAlchemy 具有自己的连接池行为，通常最好禁用此行为。此行为只能在创建任何连接之前在 PyODBC 模块级别全局禁用：
```py
import pyodbc
pyodbc.pooling = False
# don't use the engine before pooling is set to False
engine = create_engine("mssql+pyodbc://user:pass@dsn")

如果将此变量保留在其默认值True，应用程序将继续保持活动数据库连接，即使 SQLAlchemy 引擎本身完全丢弃连接或引擎被处理。

另请参见

连接池 - 在 PyODBC 文档中。

驱动程序/Unicode 支持

PyODBC 最适合与 Microsoft ODBC 驱动程序一起使用，特别是在 Python 2 和 Python 3 的 Unicode 支持领域。

在 Linux 或 OSX 上使用 FreeTDS ODBC 驱动与 PyODBC 不推荐；在这个领域历史上存在许多与  Unicode 相关的问题，包括在 Microsoft 为 Linux 和 OSX 提供 ODBC 驱动之前。现在 Microsoft  为所有平台提供驱动程序，对于 PyODBC 支持，这些是推荐的。FreeTDS 仍然适用于非 ODBC 驱动程序，如  pymssql，在这里它运行得非常好。

行数支持

截至 SQLAlchemy 2.0.5 版本，已解决了 Pyodbc 与 SQLAlchemy ORM 的“版本化行”功能的先前限制。请参阅 Rowcount Support / ORM Versioning 中的说明。

快速 Executemany 模式

PyODBC 驱动程序包括对“快速 executemany”执行模式的支持，当使用 Microsoft ODBC 驱动程序时，对于适合内存的有限大小批次的 DBAPI executemany()调用大大减少了往返次数。当要使用 executemany 调用时，在 DBAPI 游标上设置属性.fast_executemany即可启用此功能。SQLAlchemy PyODBC SQL Server 方言通过将fast_executemany参数传递给create_engine()来支持此参数，仅使用Microsoft ODBC 驱动程序：

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

2.0.9 版本更改：- fast_executemany 参数现在对具有多个参数集的所有 INSERT 语句产生了预期的效果，这些参数集不包括 RETURNING。在以前的情况下，即使指定了，SQLAlchemy 2.0 的 insertmanyvalues 特性也会导致在大多数情况下不使用 fast_executemany。

新功能版本 1.3。

另请参阅

快速执行多次 - 在 github 上

Setinputsizes 支持

从版本 2.0 开始，pyodbc 的 cursor.setinputsizes() 方法用于所有语句执行，除了 cursor.executemany() 调用 fast_executemany=True 的情况下不支持（假设保持 insertmanyvalues 已启用，“fastexecutemany” 将不会对任何情况下的 INSERT 语句产生作用）。

通过将 use_setinputsizes=False 传递给 create_engine() 可以禁用 cursor.setinputsizes() 的使用。

当 use_setinputsizes 保持默认值 True 时，传递给 cursor.setinputsizes() 的具体每种类型的符号可以使用 DialectEvents.do_setinputsizes() 钩子进行程序化定制。查看该方法以获取用法示例。

2.0 版本更改：mssql+pyodbc 方言现在默认为所有语句执行使用 use_setinputsizes=True，除了 cursor.executemany() 调用 fast_executemany=True 时的情况。可以通过将 use_setinputsizes=False 传递给 create_engine() 来关闭此行为。

pymssql

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

连接

连接字符串：

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

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

2.0.5 版本更改：pymssql 已恢复到 SQLAlchemy 的持续集成测试中。

连接

连接字符串：

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

aioodbc

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

DBAPI

aioodbc 的文档和下载信息（如适用）可在此处获取：pypi.org/project/aioodbc/

连接

连接字符串：

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

通过 aioodbc 驱动程序以 asyncio 风格支持 SQL Server 数据库，该驱动程序本身是围绕 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"
)

DBAPI

文档和下载信息（如果适用）可在以下网址找到：pypi.org/project/aioodbc/

连接中

连接字符串：

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