引擎配置

引擎是任何 SQLAlchemy 应用程序的起点。它是实际数据库及其 DBAPI 的 “大本营”，通过连接池和 Dialect 交付给 SQLAlchemy 应用程序，Dialect 描述了如何与特定类型的数据库/DBAPI 组合通信。

一般结构可以说明如下：

其中，Engine 引用了 Dialect 和 Pool 一起解释 DBAPI 的模块功能以及数据库的行为。

创建引擎只是发出单个调用的问题， create_engine（） 中：

from sqlalchemy import create_engine

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost:5432/mydatabase")

上述引擎会创建一个为 PostgreSQL 量身定制的 Dialect 对象，以及一个 Pool 对象，该对象将在首次收到连接请求时在 localhost：5432 建立 DBAPI 连接。请注意，Engine 及其底层 在 Engine.connect（） 或 Engine.begin（） 之前，池不会建立第一个实际的 DBAPI 连接 方法。 这些方法中的任何一个也可以由其他 SQLAlchemy Engine 依赖对象，例如 ORM Session 对象。这样，可以说 Engine 和 Pool 具有惰性初始化行为。

Engine 一旦创建，就可以直接用于与数据库交互，也可以传递给 Session 对象以使用 ORM。本节介绍配置 Engine 的详细信息。下一节 使用引擎和连接 将详细介绍 Engine 的使用 API 和类似 API，通常用于非 ORM 应用程序。

支持的数据库

SQLAlchemy 包含许多用于各种后端的 Dialect 实现。最常见数据库的方言包含在 SQLAlchemy 中;少数其他应用程序需要额外安装单独的方言。

请参阅 Dialects 部分 以获取有关各种可用后端的信息。

数据库 URL

create_engine（） 函数生成一个 Engine 对象。URL 的格式通常遵循 RFC-1738，但有一些例外，包括在“scheme”部分接受下划线，而不是破折号或句点。URL 通常包括用户名、密码、主机名、数据库名称字段，以及用于其他配置的可选关键字参数。在某些情况下，接受文件路径，而在其他情况下，“数据源名称”将替换“主机”和“数据库”部分。数据库 URL 的典型形式是：

dialect+driver://username:password@host:port/database

方言名称包括 SQLAlchemy 方言的标识名称，该名称如 sqlite、mysql、postgresql、oracle 或 mssql。drivername 是用于使用全小写字母连接到数据库的 DBAPI 的名称。如果未指定，则将导入“默认”DBAPI（如果可用） - 此默认通常是该后端可用的最广为人知的驱动程序。

在密码中转义特殊字符，例如 @ 符号

构造要传递给 create_engine（））、特殊字符（例如可能 在用户中使用，并且密码需要进行URL编码才能正确解析.. 这包括 @ 符号。

下面是包含密码“kx@jj5/g”的 URL 示例，其中“at”符号和斜杠字符分别表示为 %40 和 %2F：

postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb

上述密码的编码可以使用 urllib.parse 中：

>>> import urllib.parse
>>> urllib.parse.quote_plus("kx@jj5/g")
'kx%40jj5%2Fg'

然后，可以将 URL 作为字符串传递给 create_engine（）：

from sqlalchemy import create_engine

engine = create_engine("postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb")

作为转义特殊字符以创建完整 URL 字符串的替代方法，传递给 create_engine（） 的对象可以是 URL 对象的实例，该实例绕过解析阶段，可以直接容纳未转义的字符串。有关示例，请参阅下一节。

在 1.4 版本发生变更： 修复了对主机名和数据库名称中 @ 符号的支持。作为此修复的副作用，必须对密码中的 @ 符号进行转义。

以编程方式创建 URL

传递给 create_engine（） 的值可以是 URL 而不是纯字符串，它绕过了使用字符串解析的需要，因此不需要提供转义的 URL 字符串。

URL 对象是使用 URL.create（） 创建的 constructor 方法，单独传递所有字段。 特殊字符 例如密码中的那些可以在不做任何修改的情况下传递：

from sqlalchemy import URL

url_object = URL.create(
    "postgresql+pg8000",
    username="dbuser",
    password="kx@jj5/g",  # plain (unescaped) text
    host="pghost10",
    database="appdb",
)

然后，构造的 URL 对象可以直接传递给 create_engine（） 代替字符串参数：

from sqlalchemy import create_engine

engine = create_engine(url_object)

另请参阅

网址

网址.create（）

后端特定的 URL

常见连接样式的示例如下。有关所有包含的方言的详细信息的完整索引以及指向第三方方言的链接，请参阅 方言。

PostgreSQL 方言使用 psycopg2 作为默认 DBAPI。其他 PostgreSQL DBAPI 包括 pg8000 和 asyncpg：

# default
engine = create_engine("postgresql://scott:tiger@localhost/mydatabase")

# psycopg2
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/mydatabase")

# pg8000
engine = create_engine("postgresql+pg8000://scott:tiger@localhost/mydatabase")

有关 PostgreSQL 中连接到 PostgreSQL 的更多说明。

MySQL 方言使用 mysqlclient 作为默认 DBAPI。还有其他可用的 MySQL DBAPI，包括 PyMySQL：

# default
engine = create_engine("mysql://scott:tiger@localhost/foo")

# mysqlclient (a maintained fork of MySQL-Python)
engine = create_engine("mysql+mysqldb://scott:tiger@localhost/foo")

# PyMySQL
engine = create_engine("mysql+pymysql://scott:tiger@localhost/foo")

有关 MySQL 和 MariaDB 中连接到 MySQL 的更多说明。

预言机

首选的 Oracle Database 方言使用 python-oracledb 驱动程序作为 DBAPI：

engine = create_engine(
    "oracle+oracledb://scott:tiger@127.0.0.1:1521/?service_name=freepdb1"
)

engine = create_engine("oracle+oracledb://scott:tiger@tnsalias")

由于历史原因，Oracle 方言使用过时的 cx_Oracle 驱动程序作为默认 DBAPI：

engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/?service_name=freepdb1")

engine = create_engine("oracle+cx_oracle://scott:tiger@tnsalias")

有关连接到 Oracle Database 的更多说明，请参阅 Oracle。

Microsoft SQL 服务器

SQL Server 方言使用 pyodbc 作为默认 DBAPI。pymssql 也可用：

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

# pymssql
engine = create_engine("mssql+pymssql://scott:tiger@hostname:port/dbname")

有关 Microsoft SQL Server 中连接到 SQL Server 的更多说明。

SQLite

SQLite 默认使用 Python 内置模块 sqlite3 连接到基于文件的数据库。

当 SQLite 连接到本地文件时，URL 格式略有不同。URL 的 “file” 部分是数据库的文件名。对于相对文件路径，这需要三个斜杠：

# sqlite://<nohostname>/<path>
# where <path> is relative:
engine = create_engine("sqlite:///foo.db")

对于绝对文件路径，三个斜杠后跟绝对路径：

# Unix/Mac - 4 initial slashes in total
engine = create_engine("sqlite:////absolute/path/to/foo.db")

# Windows
engine = create_engine("sqlite:///C:\\path\\to\\foo.db")

# Windows alternative using raw string
engine = create_engine(r"sqlite:///C:\path\to\foo.db")

要使用 SQLite ：memory： 数据库，请指定一个空 URL：

engine = create_engine("sqlite://")

有关 SQLite 上连接到 SQLite 的更多说明。

其他

请参阅 Dialects，这是所有其他 dialect 文档的顶级页面。

引擎创建 API

对象名称	描述
create_engine（url， **kwargs）	创建新的 Engine 实例。
create_mock_engine（url， executor， **kw）	创建一个用于回显 DDL 的 “mock” 引擎。
create_pool_from_url（url， **kwargs）	从给定的 URL 创建池实例。
engine_from_config（configuration[， prefix]， **kwargs）	使用配置字典创建新的 Engine 实例。
make_url（name_or_url）	给定一个字符串，生成一个新的 URL 实例。
URL	表示用于连接到数据库的 URL 的组件。

函数 sqlalchemy.create_engine（url：str_url.URL， **kwargs： Any）→ 引擎

创建新的 Engine 实例。

标准的调用形式是将 URL 作为第一个位置参数发送，通常是一个指示数据库方言和连接参数的字符串：

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")

注意

请查看数据库 URL，了解编写 URL 字符串的一般准则。特别是，特殊字符（例如通常是密码的一部分）必须进行 URL 编码才能正确解析。

然后，其他关键字参数可能紧随其后，这些参数在生成的 Engine 上建立各种选项 及其底层 Dialect 和 Pool 构建：

engine = create_engine(
    "mysql+mysqldb://scott:tiger@hostname/dbname",
    pool_recycle=3600,
    echo=True,
)

URL 的字符串形式为 dialect[+driver]://user:password@host/dbname[?key=value..] 哪里 dialect 是数据库名称，例如 mysql、oracle、 postgresql 等，并驱动 DBAPI 的名称，例如 psycopg2、pyodbc、cx_oracle 等。或者，URL 可以是 URL 的实例。

**kwargs 采用多种选项，这些选项被路由到相应的组件。参数可能特定于 Engine、底层 Dialect、 以及 池。特定方言还接受该方言独有的关键字参数。在这里，我们描述了大多数 create_engine（） 用法通用的参数。

建立连接后，新生成的 Engine 将从底层 Pool 请求一次连接 调用 Engine.connect（） 或调用依赖于它的方法，例如 Engine.execute（）。 这 收到此请求时，池将反过来建立第一个实际的 DBAPI 连接。create_engine（） 调用本身不会 直接建立任何实际的 DBAPI 连接。

另请参阅

引擎配置

方言

使用引擎和连接

参数

• 
  connect_args——一个选项字典，将作为额外的关键字参数直接传递给 DBAPI 的 connect（） 方法。请参阅自定义 DBAPI connect（） 参数/连接例程中的示例。

• 
  创建者 –

  
  返回 DBAPI 连接的可调用对象。此创建函数将传递给底层连接池，并将用于创建所有新的数据库连接。使用此函数会导致绕过 URL 参数中指定的连接参数。

  
  这个钩子不如新钩子灵活 DialectEvents.do_connect（） 钩子，它允许完全控制如何连接到数据库，事先给定完整的 URL 参数和状态集。

  
  另请参阅

  
  DialectEvents.do_connect（） - 允许完全控制 DBAPI 连接机制的事件钩子。

  
  自定义 DBAPI connect（） 参数/连接例程

• echo=False –

  
  如果为 True，则 Engine 会将所有语句及其参数列表的 repr（） 记录到默认日志处理程序中，该处理程序默认为 sys.stdout 输出。如果设置为字符串 “debug”，则结果行也将打印到标准输出中。可以随时修改 Engine 的 echo 属性以打开和关闭日志记录;也可以使用标准 Python 日志记录模块直接控制日志记录。

  
  另请参阅

  
  配置日志记录 - 有关如何配置日志记录的更多详细信息。

• 
  echo_pool=假 –

  
  如果为 True，则连接池将记录信息输出，例如连接何时失效以及何时将连接回收到默认日志处理程序，该处理程序默认为 sys.stdout 作为输出。 如果设置为字符串 “debug”，则日志记录将包括池签出和签入。 也可以使用标准 Python 直接控制日志记录 logging 模块。

  
  另请参阅

  
  配置日志记录 - 有关如何配置日志记录的更多详细信息。

• empty_in_strategy –

  
  不再使用;SQLAlchemy 现在在所有情况下都对 IN 使用“空集”行为。

  
  1.4 版后已移除： 该 create_engine.empty_in_strategy 关键字已弃用，不再具有任何效果。现在，所有 IN 表达式都使用“扩展参数”策略呈现，该策略在语句执行时呈现一组 boundexpressions，或“空集”SELECT。

• enable_from_linting –

  
  默认为 True。如果发现给定的 SELECT 语句具有未链接的 FROM 元素，这将导致笛卡尔积，则发出警告。

  
  在 1.4 版本加入.

  
  另请参阅

  
  内置的 FROM linting 将在 SELECT 语句中警告任何潜在的笛卡尔积

• 
  execution_options – 字典执行选项，它将 应用于所有连接。 看 Connection.execution_options()

• 
  未来 –

  
  使用 2.0 样式的 Engine 和 连接应用程序接口。

  
  从 SQLAlchemy 2.0 开始，此参数仅用于向后兼容，并且必须保持其默认值 True。

  
  create_engine.future 参数将在后续的 2.x 版本中弃用，并最终被删除。

  
  在 1.4 版本加入.

  
  在 2.0 版更改： 所有 Engine 对象都是 “future” 样式的引擎，并且不再有 future=False 作模式。

  
  另请参阅

  
  SQLAlchemy 2.0 - 主要迁移指南

• hide_parameters –

  
  Boolean，当设置为 True 时，SQL 语句参数将不会显示在 INFO 日志记录中，也不会被格式化为 StatementError 对象的字符串表示形式。

  
  在 1.3.8 版本加入.

  
  另请参阅

  
  配置日志记录 - 有关如何配置日志记录的更多详细信息。

• 
  implicit_returning=True – 只能设置的遗留参数 设置为 True。在 SQLAlchemy 2.0 中，此参数不执行任何作。为了 对 ORM 调用的语句禁用 “implicit returning”， 使用 Table.implicit_returning 参数。

• insertmanyvalues_page_size –

  
  要格式化为 INSERT 语句，当语句使用 “insertmanyvalues” 模式时，即 批量插入的分页形式，在使用 executemany 执行通常与 RETURNING 结合使用。默认为 1000，但也可能受特定于方言的限制因素的影响，这些限制因素可能会在每个语句的基础上覆盖此值。

  
  2.0 版的新Function。

  
  另请参阅

  
  INSERT 语句的 “Insert Many Values” 行为

  
  控制批次大小

  Connection.execution_options.insertmanyvalues_page_size

• isolation_level –

  
  隔离级别的可选字符串名称 这将无条件地在所有新连接上设置。 隔离级别通常是字符串名称的某个子集 “可序列化”、“可重复读取”、 “READ COMMITTED”、“READ UNCOMMITTED” 和 “AUTOCOMMIT” 基于 backend 的

  
  create_engine.isolation_level 参数为 与 Connection.execution_options.isolation_level 执行选项，该选项可以在单个 Connection 以及传递给 Engine.execution_options（） 中，它可用于创建具有不同隔离级别的多个引擎，这些引擎共享一个公共连接池和方言。

  
  在 2.0 版更改： 这 create_engine.isolation_level 参数已推广到适用于所有支持 隔离级别的概念，并作为更简洁的 与执行选项相反的 up front configuration switch 这更像是一个临时的编程选项。

  
  另请参阅

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

• json_deserializer –

  
  对于支持 JSON 格式 datatype 中，这是一个 Python 可调用对象，它将转换 JSON 字符串 转换为 Python 对象。 默认情况下，使用 Python json.loads 函数。

  
  在 1.3.7 版本发生变更： SQLite 方言将此 _json_deserializer。

• json_serializer –

  
  对于支持 JSON 的方言 datatype 中，这是一个 Python 可调用对象，它将呈现给定的对象 作为 JSON。 默认情况下，使用 Python json.dumps 函数。

  
  在 1.3.7 版本发生变更： SQLite 方言将此 _json_serializer。

• 
  label_length=无 –

  
  可选的 Integer 值，用于将动态生成的列标签的大小限制为该数量的字符。如果小于 6，则标签将生成为 “_（counter）”。如果为 None，则 dialect.max_identifier_length 的 create_engine.max_identifier_length 参数 。 的值 create_engine.label_length 不得大于 create_engine.max_identfier_length 。

  
  另请参阅

  create_engine.max_identifier_length

• logging_name –

  
  字符串标识符，将在 “sqlalchemy.engine” 记录器中生成的日志记录的 “name” 字段中使用。默认为对象 id 的十六进制字符串。

  
  另请参阅

  
  配置日志记录 - 有关如何配置日志记录的更多详细信息。

  Connection.execution_options.logging_token

• max_identifier_length –

  
  整数;覆盖由 dialect 确定的 max_identifier_length。如果为 None 或 0，则无效。这是数据库配置的最大字符数，可用于 SQL 标识符，例如表名、列名或标签名。所有方言都会自动确定此值，但是，如果新的数据库版本已更改此值，但 SQLAlchemy 的方言尚未调整，则可以在此处传递该值。

  
  在 1.3.9 版本加入.

  
  另请参阅

  create_engine.label_length

• 
  max_overflow=10 – 连接池 “overflow” 中允许的连接数，即可以在pool_size设置之上打开的连接，默认为 5。这仅用于 QueuePool。

• 
  module=None—— 对 Python 模块对象的引用（模块本身，不是它的字符串名称）。指定引擎的方言要使用的备用 DBAPI 模块。每个子方言都引用一个特定的 DBAPI，该 DBAPI 将在首次连接之前导入。此参数会导致绕过导入，并使用给定的模块。可用于测试 DBAPI 以及将“模拟”DBAPI 实现注入引擎。

• 
  paramstyle=None– paramstyle 在渲染绑定参数时使用。 此样式默认为 一个由 DBAPI 本身推荐的，可从 .paramstyle 属性。 但是，大多数 DBAPI 都接受 多个 paramstyle，特别是它可能是可取的 将 “named” 参数样式更改为 “positional” 参数样式，反之亦然。 传递此属性时，它应该是 “qmark”、“numeric”、“named”、“format” 或 “pyformat”，并且应该对应于正在使用的 DBAPI 已知的支持参数样式。

• 
  pool=None—— 一个已经构建的 池，例如 QueuePool 实例。如果为非 None，则此池将直接用作引擎的底层连接池，绕过 URL 参数中存在的任何连接参数。有关手动构建连接池的信息，请参阅连接池。

• 
  poolclass=None – 一个 Pool 子类，该类将用于创建连接池 实例。注意 这与 pool 的不同之处在于，在这种情况下，您实际上并不实例化 pool，您只是指示要使用的 pool 类型。

• pool_logging_name –

  
  字符串标识符，将在 “sqlalchemy.pool” 记录器中生成的日志记录的 “name” 字段中使用。默认为对象 id 的十六进制字符串。

  
  另请参阅

  
  配置日志记录 - 有关如何配置日志记录的更多详细信息。

• pool_pre_ping –

  
  boolean，如果为 True，则启用连接池 “pre-ping” 功能，在每次签出时测试连接的活跃度。

  
  在 1.2 版本加入.

  
  另请参阅

  
  断开连接处理 - 悲观

• 
  pool_size=5 – 保持打开状态的连接数 在连接池内。这与 QueuePool 以及 SingletonThreadPool 的 QueuePool 进行匹配。 跟 QueuePool，pool_size设置为 0 表示没有限制;要禁用池化，请将 poolClass 设置为 NullPool 的 NullPool 进行转换。

• pool_recycle=-1 –

  
  此设置会导致池在给定的秒数过后回收连接。它默认为 -1 或无超时。例如，设置为 3600 表示连接将在一小时后回收。请注意，如果 8 小时内在连接上未检测到任何活动，则 MySQL 将自动断开连接（尽管这可以通过 MySQLDB 连接本身和服务器配置进行配置）。

  
  另请参阅

  
  设置 Pool Recycle

• 
  pool_reset_on_return='回滚' –

  
  将 Pool.reset_on_return 个参数 Pool 对象，该对象可设置为值 “rollback”、“commit” 或 None。

  
  另请参阅

  
  返回时重置

• pool_timeout=30 –

  
  在放弃从池中获取连接之前等待的秒数。这仅用于 QueuePool。这可以是浮点数，但受 Python 时间函数的限制，在几十毫秒内可能不可靠。

• 
  pool_use_lifo=假 –

  
  从 QueuePool 检索连接时使用 LIFO （后进先出） 而不是 FIFO （先进先出）。使用 LIFO，服务器端超时方案可以减少非高峰使用期间使用的连接数。在规划服务器端超时时，请确保使用回收或 pre-ping 策略来正常处理过时的连接。

  
  在 1.3 版本加入.

  
  另请参阅

  
  使用 FIFO 与 LIFO

  
  处理断开连接

• 
  插件–

  
  要加载的插件名称的 string 列表。 看 CreateEnginePlugin 作为背景。

  
  在 1.2.3 版本加入.

• query_cache_size –

  
  用于缓存 SQL 字符串形式的查询的缓存大小。设置为 0 可禁用缓存。

  
  当缓存的大小达到 N * 1.5 时，缓存将修剪最近最少使用的项目。默认为 500，这意味着缓存在填充时将始终存储至少 500 个 SQL 语句，并且将增长到 750 个项目，此时通过删除 250 个最近最少使用的项目，将其修剪回 500 个。

  
  缓存是在每个语句的基础上完成的，方法是生成一个表示语句结构的缓存键，然后仅当缓存中不存在该键时才为当前方言生成字符串 SQL。所有语句都支持缓存，但某些功能（例如具有大量参数的 INSERT）会有意绕过缓存。SQL 日志记录将指示每个语句的统计信息，无论它是否是从缓存中提取的。

  
  注意

  
  一些与工作单元持久性相关的 ORM 函数以及一些属性加载策略将使用主缓存之外的单个每个映射器缓存。

  
  另请参阅

  
  SQL 编译缓存

  
  在 1.4 版本加入.

• use_insertmanyvalues –

  
  默认情况下为 True，则对 INSERT.. 使用 “insertmanyvalues” 执行样式。RETURNING 语句。

  
  2.0 版的新Function。

  
  另请参阅

  
  INSERT 语句的 “Insert Many Values” 行为

函数 sqlalchemy.engine_from_config（configuration： Dict[str， Any]， prefix： str = 'sqlalchemy.'， **kwargs： Any）→ 引擎

使用配置字典创建新的 Engine 实例。

字典通常是从配置文件生成的。

engine_from_config（） 感兴趣的键应该带有前缀，例如 sqlalchemy.url、sqlalchemy.echo 等。'prefix' 参数指示要搜索的前缀。每个匹配的键（在去除前缀后）都被视为 create_engine（） 调用的相应关键字参数。

唯一需要的键是（假设默认前缀）sqlalchemy.url，它提供数据库 URL。

一组选定的关键字参数将根据字符串值被“强制”为其预期类型。参数集可以使用 engine_config_types 访问器按方言进行扩展。

参数

• 
  configuration– 一个字典（通常由配置文件生成， 但这不是要求）。 键以值 of 'prefix' 将去除该前缀，然后传递给 create_engine（） 中。

• 
  prefix– 要匹配的前缀，然后从 'configuration' 中的 key 中去除。

• 
  kwargs– engine_from_config（） 本身的每个关键字参数都会覆盖从 'configuration' 字典中获取的相应项目。关键字参数不应带有前缀。

函数 sqlalchemy.create_mock_engine（url：strURL， executor： Any， **kw： Any）→ MockConnection

创建一个用于回显 DDL 的 “mock” 引擎。

这是一个实用函数，用于调试或存储由 MetaData.create_all（） 生成的 DDL 序列的输出 和相关方法。

该函数接受一个仅用于确定要使用的方言类型的 URL，以及一个“executor”可调用函数，该函数将接收 SQL 表达式对象和参数，然后可以回显或以其他方式打印。执行程序的返回值不会被处理，引擎也不允许调用常规字符串语句，因此仅对发送到数据库而没有收到任何结果的 DDL 有用。

例如：

from sqlalchemy import create_mock_engine


def dump(sql, *multiparams, **params):
    print(sql.compile(dialect=engine.dialect))


engine = create_mock_engine("postgresql+psycopg2://", dump)
metadata.create_all(engine, checkfirst=False)

参数

• 
  url– 一个字符串 URL，通常只需要包含数据库后端名称。

• 
  executor—— 接收参数 sql、 multiparams 和 **params.sql 参数通常是 ExecutableDDLElement 的实例，然后可以使用 ExecutableDDLElement.compile() .

1.4 版本的新功能： - create_mock_engine（） 函数替换了 之前的 “mock” 引擎策略与 create_engine（） 中。

另请参阅

如何将 CREATE TABLE/ DROP TABLE 输出作为字符串获取？

函数 sqlalchemy.engine。make_url（name_or_url：strURL）→ URL

给定一个字符串，生成一个新的 URL 实例。

URL 的格式通常遵循 RFC-1738，但有一些例外，包括在“方案”部分接受下划线，而不是破折号或句点。

如果传递了 URL 对象，则按原样返回该对象。

另请参阅

数据库 URL

函数 sqlalchemy.create_pool_from_url（url：strURL， **kwargs： Any）→ 矿池

从给定的 URL 创建池实例。

如果未提供 poolclass，则使用 URL 中指定的方言选择使用的池类。

传递给 create_pool_from_url（） 的参数与传递给 create_engine（） 的 pool 参数相同 功能。

在 2.0.10 版本加入.

类 sqlalchemy.engine 中。网址

表示用于连接到数据库的 URL 的组件。

URL 通常由完全格式化的 URL 字符串构成，其中 make_url（） 函数由 create_engine（） 函数将 URL 字符串解析为 它的各个组件，然后用于构建一个新的 URL 对象。从格式化的 URL 字符串进行解析时，解析 格式通常遵循 RFC-1738，但有一些例外。

URL 对象也可以直接生成，方法是使用 make_url（） 函数和完全格式的 URL 字符串，或者通过使用 URL.create（） 构造函数来构造以编程方式给定的单个字段的 URL。生成的 URL 对象可以直接传递给 create_engine（） 代替字符串参数，这将绕过引擎创建过程中 make_url（） 的使用。

在 1.4 版本发生变更： URL 对象现在是不可变对象。要创建 URL，请使用 make_url（） 或 URL.create（） 函数/方法。要修改 URL，请使用 URL.set（） 和 URL.update_query_dict（） 返回一个新的 URL 对象。有关此更改的说明，请参阅 URL 对象现在是不可变的。

另请参阅

数据库 URL

URL 包含以下属性：

• 
  URL.drivername：数据库后端和驱动程序名称，例如 PostgreSQL + 灵能 2

• 
  URL.username：用户名字符串

• 
  URL.password： 密码字符串

• 
  URL.host：字符串主机名

• 
  URL.port：整数端口号

• 
  URL.database：字符串数据库名称

• 
  URL.query：表示查询字符串的不可变映射。包含键的字符串和值的字符串或字符串元组。

成员

create（）， 数据库， difference_update_query（）， drivername， get_backend_name（）， get_dialect（）， get_driver_name（）， host， normalized_query， password， port， query， render_as_string（）， set（）、translate_connect_args（）、update_query_dict（）、update_query_pairs（）、update_query_string（）、用户名

类签名

类 sqlalchemy.engine.URL （builtins.tuple）

类方法 sqlalchemy.engine.URL 中。create（drivername： str， username：strNone=None， password：strNone=None， host：strNone=None， port：intNone=None， database：strNone=None， query：Mapping[str，Sequence[str]str]={}）→ URL

创建新的 URL 对象。

另请参阅

数据库 URL

参数

• 
  drivername – 数据库后端的名称。此名称将对应于 sqlalchemy/databases 中的模块或第三方插件。

• 
  username- 用户名。

• 
  密码 –

  
  数据库密码。通常是一个字符串，但也可能是可以用 str（） 字符串化的对象。

  
  注意

  
  当作为参数传递给 URL.create（） 时，密码字符串不应进行 URL 编码;该字符串应包含与键入的密码字符完全相同的密码字符。

  
  注意

  
  生成密码的对象将仅被字符串化 每个 Engine 对象一次。有关每个连接的动态密码生成，请参阅生成动态身份验证令牌。

• 
  host– 主机的名称。

• 
  port— 端口号。

• 
  database– 数据库名称。

• 
  query– 字符串键到要传递的字符串值的字典 连接到方言和/或 DBAPI。 指定非字符串 参数直接添加到 Python DBAPI 中，请使用 create_engine.connect_args 参数设置为 create_engine（） 中。 另请参阅 URL.normalized_query 对于始终为 string-->list of string 的字典。

结果

new URL 对象。

1.4 版本中的新功能： URL 对象现在是名为 元组。此外，查询字典也是不可变的。要创建 URL，请使用 make_url（） 或 URL.create（） 函数/方法。 要修改 URL 中，使用 URL.set（） 和 URL.update_query（） 方法。

属性 sqlalchemy.engine.URL 的 URL 中。database：strNone

数据库名称

方法 sqlalchemy.engine.URL 中。difference_update_query（names： Iterable[str]）→ URL

从 URL.query 字典中删除给定的名称，返回新的 URL。

例如：

url = url.difference_update_query(["foo", "bar"])

等效于使用 URL.set（），如下所示：

url = url.set(
    query={
        key: url.query[key]
        for key in set(url.query).difference(["foo", "bar"])
    }
)

在 1.4 版本加入.

另请参阅

URL.query 查询

URL.update_query_dict（）

网址.set（）

属性 sqlalchemy.engine.URL 的 URL 中。drivername： str（驱动程序名称：str

数据库后端和驱动程序名称，例如 PostgreSQL + 灵能 2

方法 sqlalchemy.engine.URL 中。get_backend_name（）→ str

返回后端名称。

这是与正在使用的数据库后端相对应的名称，并且是 URL.drivername 的一部分 即加号的左侧。

方法 sqlalchemy.engine.URL 中。get_dialect（_is_async： bool = false）→ 类型[方言]

返回与此 URL 的驱动程序名称对应的 SQLAlchemy Dialect 类。

方法 sqlalchemy.engine.URL 中。get_driver_name（）→ str

返回后端名称。

这是与正在使用的 DBAPI 驱动程序对应的名称，是 URL.drivername 的一部分 即加号的右侧。

如果 URL.drivername 不包含加号，则此 URL 的默认方言 以获取驱动程序名称。

属性 sqlalchemy.engine.URL 的 URL 中。host：strNone

主机名或 IP 号。也可能是某些驱动程序的数据源名称。

属性 sqlalchemy.engine.URL 的 URL 中。normalized_query

返回 URL.query 字典，其值规范化为序列。

由于 URL.query 字典可能包含字符串值或字符串值序列，以区分在查询字符串中多次指定的参数，因此需要通常处理多个参数的代码将希望使用此属性，以便存在的所有参数都显示为序列。灵感来自 Python 的urllib.parse.parse_qs 功能。 例如：

>>> from sqlalchemy.engine import make_url
>>> url = make_url(
...     "postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt"
... )
>>> url.query
immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})
>>> url.normalized_query
immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': ('/path/to/crt',)})

属性 sqlalchemy.engine.URL 的 URL 中。password：strNone

password，它通常是一个字符串，但也可以是具有 __str__（） 方法的任何对象。

属性 sqlalchemy.engine.URL 的 URL 中。port：intNone

整数端口号

属性 sqlalchemy.engine.URL 的 URL 中。查询：immutabledict[str，Tuple[str,...]str]

表示查询字符串的不可变映射。包含键的字符串和值的字符串或字符串元组，例如：

   >>> from sqlalchemy.engine import make_url
   >>> url = make_url(
   ...     "postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt"
   ... )
   >>> url.query
   immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})

To create a mutable copy of this mapping, use the ``dict`` constructor::

   mutable_query_opts = dict(url.query)

另请参阅

URL.normalized_query - 将所有值标准化为序列以实现一致的处理

更改 URL.query 内容的方法：

URL.update_query_dict（）

URL.update_query_string（）

URL.update_query_pairs（）

URL.difference_update_query（）

方法 sqlalchemy.engine.URL 中。render_as_string（hide_password： bool = True）→ str

将此 URL 对象呈现为字符串。

当 __str__（） 或 __repr__（） 时，使用此方法 方法。 该方法直接包含其他选项。

参数

hide_password – 默认为 True。除非将其设置为 False，否则密码不会显示在字符串中。

方法 sqlalchemy.engine.URL 中。set（drivername：strNone=无， username：strNone=无， password：strNone=无， host：strNone=无， port：intNone=无， database：strNone=无， query：Mapping[str，Sequence[str]str]None=无）→ URL

返回一个经过修改的新 URL 对象。

如果值为非 None，则使用它们。将值设置为 None 显式地使用改编自 NamedTuple 的 URL._replace（） 方法。

参数

• 
  drivername – 新 drivername

• 
  username – 新用户名

• 
  password– 新密码

• 
  host – 新主机名

• 
  port – 新端口

• 
  query – 新的查询参数，传递引用字符串的字符串键字典或字符串值序列。完全替换前面的参数列表。

结果

new URL 对象。

在 1.4 版本加入.

另请参阅

URL.update_query_dict（）

方法 sqlalchemy.engine.URL 中。translate_connect_args（names：List[str]None=None， **kw： Any）→ Dict[str， Any]

将 url 属性转换为连接参数字典。

返回此 url 的属性（host、database、username、 password， port） 作为普通字典。默认情况下，属性名称用作键。unset 或 false 属性在最终字典中被省略。

参数

• 
  **kw— url 属性的可选备用键名称。

• 
  names– 已弃用。与基于关键字的备用名称的用途相同，但将名称与原始名称位置相关联。

方法 sqlalchemy.engine.URL 中。update_query_dict（query_parameters：Mapping[str，strList[str]]， append： bool = False）→ URL

返回一个新的 URL 对象，其中包含 URL.query 参数字典。

字典通常包含字符串键和字符串值。为了表示多次表达的查询参数，请传递一系列字符串值。

例如：

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
>>> url = url.update_query_dict(
...     {"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"}
... )
>>> str(url)
'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'

参数

• 
  query_parameters– 带有字符串键和值的字典，这些键和值可以是字符串，也可以是字符串序列。

• 
  append—— 如果为 True，则不会删除现有查询字符串中的参数;除了现有的参数之外，还将添加新参数。如果保留为默认值 False，则给定查询参数中存在的键将替换现有查询字符串的键。

在 1.4 版本加入.

另请参阅

URL.query 查询

URL.update_query_string（）

URL.update_query_pairs（）

URL.difference_update_query（）

网址.set（）

方法 sqlalchemy.engine.URL 中。update_query_pairs（key_value_pairs：Iterable[Tuple[str，strList[str]]]， append： bool = False）→ URL

返回一个新的 URL 对象，其中包含 URL.query 查询 由给定的键/值对序列更新的参数字典

例如：

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
>>> url = url.update_query_pairs(
...     [
...         ("alt_host", "host1"),
...         ("alt_host", "host2"),
...         ("ssl_cipher", "/path/to/crt"),
...     ]
... )
>>> str(url)
'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'

参数

• 
  key_value_pairs– 一个元组序列，每个元组包含两个字符串。

• 
  append—— 如果为 True，则不会删除现有查询字符串中的参数;除了现有的参数之外，还将添加新参数。如果保留为默认值 False，则给定查询参数中存在的键将替换现有查询字符串的键。

在 1.4 版本加入.

另请参阅

URL.query 查询

URL.difference_update_query（）

网址.set（）

方法 sqlalchemy.engine.URL 中。update_query_string（query_string： str， append： bool = False）→ 网址

返回带有 URL.query 的新 URL 对象 由给定查询字符串更新的 parameter dictionary。

例如：

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
>>> url = url.update_query_string(
...     "alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt"
... )
>>> str(url)
'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'

参数

• 
  query_string – 一个 URL 转义的查询字符串，不包括问号。

• 
  append—— 如果为 True，则不会删除现有查询字符串中的参数;除了现有的参数之外，还将添加新参数。如果保留为默认值 False，则给定查询参数中存在的键将替换现有查询字符串的键。

在 1.4 版本加入.

另请参阅

URL.query 查询

URL.update_query_dict（）

属性 sqlalchemy.engine.URL 的 URL 中。username：strNone

用户名字符串

矿池

当调用 connect（） 或 execute（） 方法时，Engine 将向连接池请求连接。默认连接池 QueuePool 将打开与 数据库。执行并发语句时， QueuePool 会将其连接池增加到 默认大小为 5，并允许默认的 “overflow” 为 10。由于 Engine 本质上是 连接池，因此您应该保留一个 Engine ，而不是为每个连接创建一个新数据库。

注意

默认情况下，QueuePool 不用于 SQLite 引擎。 看 SQLite 了解有关 SQLite 连接池使用情况的详细信息。

有关连接池的更多信息，请参阅连接池。

自定义 DBAPI connect（） 参数 / 连接例程

对于需要特殊连接方法的情况，在绝大多数情况下 的情况下，在 create_engine（） 级别来自定义此过程。这些将在以下小节中介绍。

传递给 dbapi.connect（） 的特殊关键字参数

所有 Python DBAPI 都接受除基本连接之外的其他参数。常用参数包括用于指定字符集编码和超时值的参数;更复杂的数据包括特殊的 DBAPI 常量和对象以及 SSL 子参数。有两种基本方法可以传递这些参数而不复杂。

向 URL 查询字符串添加参数

简单的字符串值，以及一些数值和布尔标志，通常可以直接在 URL 的查询字符串中指定。一个常见的示例是接受字符编码的参数编码的 DBAPI，例如大多数 MySQL DBAPI：

engine = create_engine("mysql+pymysql://user:pass@host/test?charset=utf8mb4")

使用查询字符串的优点是，可以在配置文件中以可移植到 URL 中指定的 DBAPI 的方式指定其他 DBAPI 选项。在此级别传递的具体参数因 SQLAlchemy 方言而异。一些 dialect 将所有参数作为字符串传递，而另一些 dialect 将解析特定数据类型并将参数移动到不同位置，例如驱动程序级 DSN 和连接字符串。由于此区域中每种方言的行为当前各不相同，因此应查阅方言文档以了解正在使用的特定方言，以查看此级别是否支持特定参数。

提示

使用 Dialect.create_connect_args（） 来显示传递给给定 URL 的 DBAPI 的确切参数的通用技术 方法直接如下：

>>> from sqlalchemy import create_engine
>>> engine = create_engine(
...     "mysql+pymysql://some_user:some_pass@some_host/test?charset=utf8mb4"
... )
>>> args, kwargs = engine.dialect.create_connect_args(engine.url)
>>> args, kwargs
([], {'host': 'some_host', 'database': 'test', 'user': 'some_user', 'password': 'some_pass', 'charset': 'utf8mb4', 'client_flag': 2})

上述 args、kwargs 对通常作为 dbapi.connect(*args, **kwargs) .

使用 connect_args dictionary 参数

将任何参数传递给 dbapi.connect（） 的更通用系统 保证始终传递所有参数的函数是 create_engine.connect_args 字典参数。这可用于在添加到查询字符串时方言不处理的参数，以及必须将特殊子结构或对象传递给 DBAPI 时。有时，只是必须将特定标志作为 True 符号发送，而 SQLAlchemy 方言不知道此关键字参数以强制其从 URL 中显示的字符串形式中发出。下面说明了 psycopg2 “连接工厂” 的使用，它替换了 connection 的底层实现：

engine = create_engine(
    "postgresql+psycopg2://user:pass@hostname/dbname",
    connect_args={"connection_factory": MyConnectionFactory},
)

另一个示例是 pyodbc “timeout” 参数：

engine = create_engine(
    "mssql+pyodbc://user:pass@sqlsrvr?driver=ODBC+Driver+13+for+SQL+Server",
    connect_args={"timeout": 30},
)

上面的示例还说明了 URL“查询字符串”参数以及 create_engine.connect_args 可以同时使用;对于 PyODBC，“driver” 关键字在 URL 中具有特殊含义。

控制如何将参数传递给 DBAPI connect（） 函数

除了作传递给 connect（） 的参数之外，我们还可以使用 DialectEvents.do_connect（） 事件钩子。这个钩子将完整的 *args， **kwargs，方言将发送到 connect（）。然后，可以就地修改这些集合以更改它们的使用方式：

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user:pass@hostname/dbname")


@event.listens_for(engine, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    cparams["connection_factory"] = MyConnectionFactory

生成动态身份验证令牌

DialectEvents.do_connect（） 也是动态 插入一个身份验证令牌，该令牌可能会在 发动机。例如，如果令牌由 get_authentication_token（） 并在令牌中传递给 DBAPI 参数，这可以实现为：

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user@hostname/dbname")


@event.listens_for(engine, "do_connect")
def provide_token(dialect, conn_rec, cargs, cparams):
    cparams["token"] = get_authentication_token()

另请参阅

使用访问令牌连接到数据库 - 涉及 SQL Server 的更具体示例

连接后修改 DBAPI 连接，或在连接后运行命令

对于 SQLAlchemy 创建的 DBAPI 连接没有问题，但是我们 想在实际使用之前修改已完成的连接，例如 至于设置特殊标志或运行某些命令， PoolEvents.connect（） 事件钩子是最合适的钩子。在 SQLAlchemy 使用之前，每个创建的新连接都会调用此钩子：

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user:pass@hostname/dbname")


@event.listens_for(engine, "connect")
def connect(dbapi_connection, connection_record):
    cursor_obj = dbapi_connection.cursor()
    cursor_obj.execute("SET some session variables")
    cursor_obj.close()

完全替换 DBAPI connect（） 函数

最后，DialectEvents.do_connect（） 事件钩子还可以允许我们通过建立连接并返回它来完全接管连接过程：

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user:pass@hostname/dbname")


@event.listens_for(engine, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    # return the new DBAPI connection with whatever we'd like to
    # do
    return psycopg2.connect(*cargs, **cparams)

DialectEvents.do_connect（） 钩子取代了之前的 create_engine.creator 钩子，该钩子仍然可用。 DialectEvents.do_connect（） 具有明显的优势，即从 URL 解析的完整参数也会传递给用户定义的函数，而 create_engine.creator 则不是这种情况。

配置日志

Python 的标准日志记录模块用于 使用 SQLAlchemy 实现信息和调试日志输出。这允许 SQLAlchemy 的日志记录，以标准方式与其他应用程序集成 和图书馆。 还有两个参数 create_engine.echo 和 create_engine.echo_pool 存在于 create_engine（） 上，允许立即记录到 sys.stdout 为了地方发展;这些参数最终会相互作用 替换为下面描述的常规 Python 记录器。

本节假定您熟悉上述链接的日志记录模块。SQLAlchemy 执行的所有日志记录都存在于 sqlalchemy 下 namespace 中，如 logging.getLogger('sqlalchemy') .配置日志记录后（例如通过 logging.basicConfig（）），可以打开的 SA logger 的通用命名空间如下：

• 
  sqlalchemy.engine - 控制 SQL 回显。对于 SQL 查询输出、日志记录，设置为 logging.INFO。DEBUG 用于查询 + 结果集输出。这些设置等效于 echo=True 和 echo=“debug” on create_engine.echo 中。

• 
  sqlalchemy.pool - 控制连接池日志记录。 设置为 logging.INFO 记录连接失效和回收事件;设置为 伐木。DEBUG 来额外记录所有池签入和签出。这些设置等效于 pool_echo=True 和 pool_echo=“debug” 分别在 create_engine.echo_pool 上。

• 
  sqlalchemy.dialects - 控制 SQL 方言的自定义日志记录，只要在特定方言中使用日志记录，这通常是最小的。

• 
  sqlalchemy.orm - 在一定程度上控制各种 ORM 函数的日志记录 该日志记录在 ORM 中使用，这通常是最小的。 设置为 logging.INFO 记录有关 mapper 配置的一些顶级信息。

例如，要使用 Python 日志记录而不是 echo=True 标志：

import logging

logging.basicConfig()
logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)

默认情况下，日志级别设置为 logging。WARN 中 sqlalchemy 命名空间，这样就不会发生日志作，即使在启用了日志记录的应用程序中也是如此。

注意

SQLAlchemy 引擎仅在检测到当前日志记录级别为 logging.INFO 或 logging时发出 log 语句，从而节省 Python 函数调用开销。DEBUG的 DEBUG 中。它仅在从连接池中获取新连接时检查此级别。因此，在更改已运行的应用程序的日志记录配置时，当前处于活动状态的任何 Connection 或更常见的 Session 对象在事务中处于活动状态，则不会 根据新配置记录任何 SQL，直到新的 已购买连接（在 Session，这是在当前事务结束并且新事务开始之后）。

更多关于 Echo 标志

如前所述，create_engine.echo 和 create_engine.echo_pool parameters 是立即记录到 sys.stdout 的快捷方式：

>>> from sqlalchemy import create_engine, text
>>> e = create_engine("sqlite://", echo=True, echo_pool="debug")
>>> with e.connect() as conn:
...     print(conn.scalar(text("select 'hi'")))
2020-10-24 12:54:57,701 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Created new connection <sqlite3.Connection object at 0x7f287819ac60>
2020-10-24 12:54:57,701 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Connection <sqlite3.Connection object at 0x7f287819ac60> checked out from pool
2020-10-24 12:54:57,702 INFO sqlalchemy.engine.Engine select 'hi'
2020-10-24 12:54:57,702 INFO sqlalchemy.engine.Engine ()
hi
2020-10-24 12:54:57,703 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Connection <sqlite3.Connection object at 0x7f287819ac60> being returned to pool
2020-10-24 12:54:57,704 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Connection <sqlite3.Connection object at 0x7f287819ac60> rollback-on-return

使用这些标志大致相当于：

import logging

logging.basicConfig()
logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)
logging.getLogger("sqlalchemy.pool").setLevel(logging.DEBUG)

需要注意的是，这两个标志独立于任何现有的日志记录配置工作，并且将使用 logging.basicConfig（） 絕對。 除了任何现有的 Logger 配置之外，它还具有配置的效果。因此，在配置日志记录时 显式地，确保所有 echo 标志始终设置为 False，以避免获得重复的日志行。

设置日志名称

实例的记录器名称，例如 Engine 或 Pool 默认使用截断的十六进制标识符 字符串。要将其设置为特定名称，请使用 create_engine.logging_name 和 create_engine.pool_logging_name 跟 sqlalchemy.create_engine（）;该名称将附加到日志记录名称中 sqlalchemy.engine.Engine 的

>>> import logging
>>> from sqlalchemy import create_engine
>>> from sqlalchemy import text
>>> logging.basicConfig()
>>> logging.getLogger("sqlalchemy.engine.Engine.myengine").setLevel(logging.INFO)
>>> e = create_engine("sqlite://", logging_name="myengine")
>>> with e.connect() as conn:
...     conn.execute(text("select 'hi'"))
2020-10-24 12:47:04,291 INFO sqlalchemy.engine.Engine.myengine select 'hi'
2020-10-24 12:47:04,292 INFO sqlalchemy.engine.Engine.myengine ()

提示

create_engine.logging_name 和 create_engine.pool_logging_name parameters 也可以与 create_engine.echo 和 create_engine.echo_pool 中。但是，如果创建其他引擎时将 echo 标志设置为 True 且没有日志记录名称，则会出现不可避免的双重日志记录情况。这是因为将自动为 sqlalchemy.engine.Engine 添加一个处理程序，该处理程序将记录无名称引擎以及具有日志记录名称的引擎的消息。例如：

from sqlalchemy import create_engine, text

e1 = create_engine("sqlite://", echo=True, logging_name="myname")
with e1.begin() as conn:
    conn.execute(text("SELECT 1"))

e2 = create_engine("sqlite://", echo=True)
with e2.begin() as conn:
    conn.execute(text("SELECT 2"))

with e1.begin() as conn:
    conn.execute(text("SELECT 3"))

上述情况将重复对数 SELECT 3。要解决此问题，请确保所有引擎都设置了 logging_name，或者使用显式 logger / 处理程序设置，而不使用 create_engine.echo 和 create_engine.echo_pool 中。

设置每个连接 / 子引擎令牌

1.4.0b2 版本的新Function。

虽然日志记录名称适合在 Engine 对象，则它不够灵活，无法容纳任意大的名称列表，用于跟踪日志消息中的单个连接和/或事务。

对于此使用案例，由 Connection 和 Result 对象可以使用其他标记（如事务或请求标识符）进行扩充。该 Connection.execution_options.logging_token 参数接受一个字符串参数，该参数可用于建立每个连接跟踪令牌：

>>> from sqlalchemy import create_engine
>>> e = create_engine("sqlite://", echo="debug")
>>> with e.connect().execution_options(logging_token="track1") as conn:
...     conn.execute(text("select 1")).all()
2021-02-03 11:48:45,754 INFO sqlalchemy.engine.Engine [track1] select 1
2021-02-03 11:48:45,754 INFO sqlalchemy.engine.Engine [track1] [raw sql] ()
2021-02-03 11:48:45,754 DEBUG sqlalchemy.engine.Engine [track1] Col ('1',)
2021-02-03 11:48:45,755 DEBUG sqlalchemy.engine.Engine [track1] Row (1,)

参数 Connection.execution_options.logging_token 也可以在 engines 或 sub engines 上通过 create_engine.execution_options 或 Engine.execution_options（） 的这对于将不同的日志记录令牌应用于应用程序的不同组件而不创建新引擎可能很有用：

>>> from sqlalchemy import create_engine
>>> e = create_engine("sqlite://", echo="debug")
>>> e1 = e.execution_options(logging_token="track1")
>>> e2 = e.execution_options(logging_token="track2")
>>> with e1.connect() as conn:
...     conn.execute(text("select 1")).all()
2021-02-03 11:51:08,960 INFO sqlalchemy.engine.Engine [track1] select 1
2021-02-03 11:51:08,960 INFO sqlalchemy.engine.Engine [track1] [raw sql] ()
2021-02-03 11:51:08,960 DEBUG sqlalchemy.engine.Engine [track1] Col ('1',)
2021-02-03 11:51:08,961 DEBUG sqlalchemy.engine.Engine [track1] Row (1,)

>>> with e2.connect() as conn:
...     conn.execute(text("select 2")).all()
2021-02-03 11:52:05,518 INFO sqlalchemy.engine.Engine [track2] Select 1
2021-02-03 11:52:05,519 INFO sqlalchemy.engine.Engine [track2] [raw sql] ()
2021-02-03 11:52:05,520 DEBUG sqlalchemy.engine.Engine [track2] Col ('1',)
2021-02-03 11:52:05,520 DEBUG sqlalchemy.engine.Engine [track2] Row (1,)

隐藏参数

Engine 发出的日志记录还指示一段摘录 的特定语句存在的 SQL 参数。 为了防止 这些参数不会出于隐私目的而被记录下来，因此会启用 create_engine.hide_parameters 标志：

>>> e = create_engine("sqlite://", echo=True, hide_parameters=True)
>>> with e.connect() as conn:
...     conn.execute(text("select :some_private_name"), {"some_private_name": "pii"})
2020-10-24 12:48:32,808 INFO sqlalchemy.engine.Engine select ?
2020-10-24 12:48:32,808 INFO sqlalchemy.engine.Engine [SQL parameters hidden due to hide_parameters=True]