SqlAlchemy 2.0 中文文档（四十三）（5）

SqlAlchemy 2.0 中文文档（四十三）（4）https://developer.aliyun.com/article/1563062

引擎创建 API

function sqlalchemy.create_engine(url: str | _url.URL, **kwargs: Any) → Engine

创建一个新的 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 等，而 driver 是 DBAPI 的名称，例如 psycopg2、pyodbc、cx_oracle 等。另外，URL 还可以是 URL 的实例。

**kwargs 接受各种路由到其适当组件的选项。参数可能特定于 Engine、底层 Dialect，以及 Pool。特定方言还接受特定于该方言的关键字参数。在这里，我们描述了大多数 create_engine() 使用的通用参数。

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

另请参阅

引擎配置

方言

使用引擎和连接

参数：

• connect_args – 一个选项字典，将作为额外的关键字参数直接传递给 DBAPI 的 connect() 方法。请参阅自定义 DBAPI connect() 参数 / on-connect routines 的示例。
  
• creator –
  返回 DBAPI 连接的可调用对象。此创建函数将传递给底层连接池，并将用于创建所有新的数据库连接。使用此函数会使 URL 参数中指定的连接参数被绕过。
  此钩子不如较新的 DialectEvents.do_connect() 钩子灵活，后者允许完全控制在数据库中如何建立连接，给定全套 URL 参数和先前的状态。
  另请参阅
  DialectEvents.do_connect() - 事件钩子，允许完全控制 DBAPI 连接机制。
  自定义 DBAPI connect() 参数 / on-connect routines
  
• echo=False –
  如果为 True，则引擎将记录所有语句以及它们参数列表的repr()到默认的日志处理程序，默认情况下为sys.stdout输出。如果设置为字符串"debug"，则结果行也将打印到标准输出。Engine的echo属性可以随时修改以打开和关闭日志记录；也可以使用标准的 Python logging 模块直接控制日志记录。
  另请参阅
  配置日志记录 - 如何配置日志记录的更多细节。
  
• echo_pool=False –
  如果为 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()
  
• future –
  使用 2.0 风格的Engine和Connection API。
  从 SQLAlchemy 2.0 开始，此���数仅用于向后兼容，必须保持其默认值为True。
  create_engine.future参数将在随后的 2.x 版本中被弃用，并最终移除。
  1.4 版本中的新功能。
  2.0 版本中的更改：所有Engine对象都是“future”风格的引擎，不再有future=False操作模式。
  另请参阅
  SQLAlchemy 2.0 - 主要迁移指南
  
• hide_parameters –
  布尔值，当设置为 True 时，SQL 语句参数将不会显示在 INFO 日志中，也不会被格式化为StatementError对象的字符串表示。
  1.3.8 版本中的新功能。
  另请参阅
  配置日志记录 - 关于如何配置日志记录的更多详细信息。
  
• implicit_returning=True – 旧参数，只能设置为 True。在 SQLAlchemy 2.0 中，此参数不起作用。为了禁用 ORM 调用的语句的“隐式返回”，请在每个表上使用Table.implicit_returning参数进行配置。
  
• insertmanyvalues_page_size –
  在使用“insertmanyvalues”模式的语句格式化为 INSERT 语句时，插入的行数。该模式是用于许多后端的分页形式的批量插入，在使用 executemany 执行时通常与 RETURNING 一起使用。默认为 1000，但也可能受到方言特定的限制因素的影响，这些因素可能会在每个语句的基础上覆盖此值。
  自 2.0 版本起新增。
  另请参见
  “插入多个值”INSERT 语句行为
  控制批量大小
  Connection.execution_options.insertmanyvalues_page_size
  
• isolation_level –
  必要时，所有新连接上都将设置的隔离级别的可选字符串名称。隔离级别通常是基于后端的字符串名称"SERIALIZABLE"、"REPEATABLE READ"、"READ COMMITTED"、"READ UNCOMMITTED"和"AUTOCOMMIT"的某些子集。
  create_engine.isolation_level参数与Connection.execution_options.isolation_level执行选项形成对比，后者可在单个Connection上设置，以及传递给Engine.execution_options()的相同参数，在那里可以用来创建具有不同隔离级别的多个引擎，这些引擎共享一个公共连接池和方言。
  从 2.0 版本开始更改：create_engine.isolation_level参数已泛化，适用于所有支持隔离级别概念的方言，并提供作为更简洁、直接的配置开关，与执行选项形成对比，后者更像是一种临时编程选项。
  另请参见
  设置事务隔离级别，包括 DBAPI 自动提交
  
• json_deserializer –
  对于支持JSON数据类型的方言，这是一个 Python 可调用对象，它将 JSON 字符串转换为 Python 对象。默认情况下，使用 Python 的json.loads函数。
  从 1.3.7 版本开始更改：SQLite 方言将其从_json_deserializer改名为此。
  
• json_serializer –
  对于支持 JSON 数据类型的方言，这是一个 Python 可调用函数，它将给定对象呈现为 JSON。默认情况下，使用 Python 的 json.dumps 函数。
  从版本 1.3.7 开始更改：SQLite 方言将其从 _json_serializer 重命名为 _json_serializer。
  
• label_length=None -
  可选整数值，将动态生成的列标签的大小限制为该数目的字符数。如果小于 6，则标签将生成为“_(计数器)”。如果为 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 -
  整数；覆盖由方言确定的 max_identifier_length。如果为 None 或零，则无效。这是数据库配置的最大字符数，可用于 SQL 标识符（如表名、列名或标签名）。所有方言都会自动确定此值，但是在新数据库版本中，此值已更改但未调整 SQLAlchemy 方言的情况下，可以将值传递到此处。
  从版本 1.3.9 新增。
  另请参阅
  create_engine.label_length
  
• max_overflow=10 - 允许在连接池 “溢出” 中打开的连接数，即可以超过 pool_size 设置的连接数，后者默认为五。仅在 QueuePool 中使用。
  
• module=None – 指向 Python 模块对象的引用（模块本身，而不是其字符串名称）。指定引擎方言要使用的备用 DBAPI 模块。每个子方言引用一个特定的 DBAPI，该 DBAPI 将在第一次连接之前导入。此参数导致跳过导入，并改用给定的模块。不仅可用于 DBAPI 的测试，还可用于将“模拟”DBAPI 实现注入到Engine中。
  
• paramstyle=None – 渲染绑定参数时使用的paramstyle。此样式默认为 DBAPI 本身推荐的样式，该样式从 DBAPI 的.paramstyle属性中获取。然而，大多数 DBAPI 都接受多种 paramstyle，特别是将“命名”paramstyle 转换为“位置”paramstyle，或者反之，可能是可取的。当传递此属性时，它应该是以下值之一："qmark"、"numeric"、"named"、"format"或"pyformat"，并且应该对应于所使用的 DBAPI 已知支持的参数样式。
  
• pool=None – Pool的一个已构造实例，例如QueuePool实例。如果非 None，则此池将直接用作引擎的底层连接池，跳过 URL 参数中存在的任何连接参数。有关手动构造连接池的信息，请参阅连接池。
  
• poolclass=None – 一个Pool子类，将使用 URL 中给定的连接参数来创建连接池实例。请注意，这与pool不同，因为在这种情况下，您实际上并不实例化池，而是指示要使用何种类型的池。
  
• pool_logging_name –
  将在“sqlalchemy.pool”记录器中生成的日志记录的“name”字段内使用的字符串标识符。默认为对象 id 的十六进制字符串。
  另请参阅
  配置日志记录 - 关于如何配置日志记录的更多详细信息。
  
• pool_pre_ping –
  如果为 True，则启用连接池“预检”功能，该功能在每次检出时测试连接的活动性。
  自版本 1.2 起新增。
  另请参阅
  断开处理 - 悲观
  
• pool_size=5 – 在连接池中保持打开的连接数。与 QueuePool 以及 SingletonThreadPool 一起使用。对于 QueuePool，pool_size 设置为 0 表示没有限制；要禁用池化，请将 poolclass 设置为 NullPool。
  
• pool_recycle=-1 –
  此设置会导致池在经过给定的秒数后重新利用连接。默认值为-1，或者没有超时。例如，将其设置为 3600 意味着连接将在一小时后重新利用。请注意，特别是 MySQL 会在连接上检测不到任何活动时自动断开连接，时间为八小时（尽管可以通过 MySQLDB 连接本身和服务器配置进行配置）。
  另请参阅
  设置池回收
  
• pool_reset_on_return='rollback' –
  设置底层 Pool 对象的 Pool.reset_on_return 参数，该参数可以设置为值 "rollback"、"commit" 或 None。
  另请参阅
  返回时重置
  
• pool_timeout=30 –
  从池中获取连接之前等待的秒数。仅与 QueuePool 一起使用。这可以是一个浮点数，但受 Python 时间函数的限制，可能不可靠在十几毫秒的范围内。
  
• pool_use_lifo=False –
  当从 QueuePool 检索连接时使用 LIFO（后进先出）而不是 FIFO（先进先出）。使用 LIFO，服务器端的超时方案可以在非高峰使用期间减少使用的连接数。在规划服务器端超时时，请确保使用回收或预先 ping 策略以优雅地处理陈旧的连接。

版本 1.3 中的新功能。

另请参阅

使用 FIFO vs. LIFO

处理断开连接

• plugins –
  要加载的插件名称的字符串列表。有关背景，请参阅 CreateEnginePlugin。
  版本 1.2.3 中的新功能。
  
• query_cache_size –
  用于缓存查询的 SQL 字符串形式的缓存大小。将其设置为零以禁用缓存。
  当缓存大小达到 N * 1.5 时，最近最少使用的项目将被清理。默认为 500，意味着缓存填满时始终至少存储 500 条 SQL 语句，并且会增长到 750 个项目，然后通过删除最近最少使用的 250 个项目将其减少到 500。
  缓存是在每个语句的基础上完成的，方法是生成一个表示语句结构的缓存键，然后仅当该键不在缓存中时才为当前方言生成字符串 SQL。所有语句都支持缓存，但是一些特性，如具有大量参数的 INSERT，将有意绕过缓存。SQL 日志将指示每个语句的统计信息，无论是否从缓存中拉取。
  注意
  一些与工作单元持久性相关的 ORM 函数以及一些属性加载策略将使用主缓存之外的每个映射器缓存。
  另请参阅
  SQL 编译缓存
  版本 1.4 中的新功能。
  
• use_insertmanyvalues –
  默认为 True，对于 INSERT…RETURNING 语句，默认使用“insertmanyvalues”执行样式。
  版本 2.0 中的新功能。
  另请参阅
  INSERT 语句的“插入多个值”行为
  

function sqlalchemy.engine_from_config(configuration: Dict[str, Any], prefix: str = 'sqlalchemy.', **kwargs: Any) → Engine

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

该字典通常由配置文件生成。

对于 engine_from_config() 感兴趣的键应该有前缀，例如 sqlalchemy.url，sqlalchemy.echo 等。‘prefix’参数指示要搜索的前缀。每个匹配键（前缀被剥离后）都被视为对 create_engine() 调用的相应关键字参数。

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

一组选择的关键字参数将根据字符串值“强制转换”为其预期类型。使用 engine_config_types 访问器可针对每个方言扩展参数集。

参数：

• configuration – 一个字典（通常由配置文件生成，但这不是必需的）。键以“prefix”值开头的项目将删除该前缀，然后传递给 create_engine()。
  
• prefix – 用于在“configuration”中匹配并剥离键的前缀。
  
• kwargs – 传递给 engine_from_config() 的每个关键字参数本身都会覆盖从“configuration”字典中获取的相应项目。关键字参数不应有前缀。
  

function sqlalchemy.create_mock_engine(url: str | URL, executor: Any, **kw: Any) → MockConnection

创建用于回显 DDL 的“模拟”引擎。

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

该函数接受一个 URL 参数，仅用于确定要使用的方言类型，以及一个“执行器”可调用函数，该函数将接收一个 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() 函数取代了以前与 create_engine() 一起使用的“模拟”引擎策略。

另请参阅

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

function sqlalchemy.engine.make_url(name_or_url: str | URL) → URL

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

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

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

另请参阅

数据库 URL

function sqlalchemy.create_pool_from_url(url: str | URL, **kwargs: Any) → Pool

从给定的 URL 创建一个池实例。

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

传递给 create_pool_from_url() 的参数与传递给 create_engine() 函数的池参数相同。

从版本 2.0.10 开始新增。

class sqlalchemy.engine.URL

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

URL 通常是从完全格式化的 URL 字符串构建的，其中 make_url() 函数在内部由 create_engine() 函数使用，以将 URL 字符串解析为其各个组件，然后用于构造一个新的 URL 对象。在解析格式化的 URL 字符串时，解析格式通常遵循 RFC-1738，但也有一些例外情况。

一个 URL 对象也可以直接生成，可以使用具有完整形式的 URL 字符串的 make_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+psycopg2
  
• URL.username: 用户名字符串
  
• URL.password: 密码字符串
  
• URL.host: 主机名字符串
  
• URL.port: 整数端口号
  
• URL.database: 数据库名称字符串
  
• URL.query: 一个表示查询字符串的不可变映射。包含键的字符串和值的字符串或字符串元组。
  

成员

create(), database, 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(), username

类签名

类sqlalchemy.engine.URL (builtins.tuple)

classmethod create(drivername: str, username: str | None = None, password: str | None = None, host: str | None = None, port: int | None = None, database: str | None = None, query: Mapping[str, Sequence[str] | str] = {}) → URL

创建一个新的URL对象。

另请参阅

数据库 URL

参数：

• drivername – 数据库后端的名称。该名称将对应于 sqlalchemy/databases 中的一个模块或第三方插件。
  
• username – 用户名。
  
• password –
  数据库密码。通常为字符串，但也可以是可以使用str()进行字符串化的对象。
  注意
  当作为参数传递给URL.create()时，密码字符串不应进行 URL 编码；该字符串应该包含与键入的密码字符完全相同。
  注意
  对于每个Engine对象，一个生成密码的对象只会被字符串化一次。对于每次连接的动态密码生成，请参阅生成动态认证令牌。
  
• host – 主机名。
  
• port – 端口号。
  
• database – 数据库名称。
  
• query – 一个字符串键到字符串值的字典，将在连接时传递给方言和/或 DBAPI。要直接指定 Python DBAPI 的非字符串参数，请使用create_engine.connect_args参数来调用create_engine()。另请参阅URL.normalized_query，用于一个一致的字符串->字符串列表字典。
  

返回：

新的URL对象。

从版本 1.4 开始：URL对象现在是一个不可变的命名元组。此外，query字典也是不可变的。要创建 URL，请使用make_url()或URL.create()函数/方法。要修改URL，请使用URL.set()和URL.update_query()方法。

attribute database: str | None

数据库名称

method 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()

URL.set()

attribute drivername: str

数据库后端和驱动程序名称，如postgresql+psycopg2

method get_backend_name() → str

返回后端名称。

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

method get_dialect(_is_async: bool = False) → Type[Dialect]

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

method get_driver_name() → str

返回后端名称。

这是与正在使用的 DBAPI 驱动程序相对应的名称，并且是URL.drivername右侧的部分。

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

attribute host: str | None

主机名或 IP 地址。对于某些驱动程序，也可以是数据源名称。

attribute 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',)})

attribute password: str | None

密码，通常是一个字符串，但也可能是具有__str__()方法的任何对象。

attribute port: int | None

整数端口号

attribute query: 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()

method render_as_string(hide_password: bool = True) → str

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

当使用__str__()或__repr__()方法时使用此方法。该方法直接包括附加选项。

参数：

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

method set(drivername: str | None = None, username: str | None = None, password: str | None = None, host: str | None = None, port: int | None = None, database: str | None = None, query: Mapping[str, Sequence[str] | str] | None = None) → URL

返回一个带有修改的URL对象。

如果值为非 None，则使用该值。要将值显式设置为None，请使用从namedtuple调整的URL._replace()方法。

参数：

• drivername – 新的驱动程序名称
  
• username – 新用户名
  
• password – 新密码
  
• host – 新主机名
  
• port – 新端口
  
• query – 新的查询参数，传递一个字符串键的字典，指向字符串或字符串值序列。完全替换了以前的参数列表。
  

返回：

新的URL对象。

版本 1.4 中的新功能。

另请参阅

URL.update_query_dict()

method translate_connect_args(names: List[str] | None = None, **kw: Any) → Dict[str, Any]

将 url 属性翻译为连接参数的字典。

将此 url 的属性（主机、数据库、用户名、密码、端口）作为普通字典返回。默认情况下，属性名称用作键。未设置或为 false 的属性将从最终字典中省略。

参数：

• **kw – 可选，url 属性的替代键名。
  
• names – 已弃用。与基于关键字的替代名称具有相同目的，但将名称与原始位置相关联。
  

method update_query_dict(query_parameters: Mapping[str, str | List[str]], append: bool = False) → URL

返回一个由给定字典更新的URL对象的新对象。

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

例如：

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

URL.set()

method update_query_pairs(key_value_pairs: Iterable[Tuple[str, str | List[str]]], append: bool = False) → URL

返回一个新的 URL 对象，其参数字典由给定的键/值对序列更新。

例如：

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

URL.set()

method update_query_string(query_string: str, append: bool = False) → URL

返回一个新的 URL 对象，其参数字典由给定的查询字符串更新。

例如：

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

attribute username: str | None

用户名 字符串

池化

当调用 connect() 或 execute() 方法时，Engine 将向连接池请求连接。默认连接池 QueuePool 将根据需要打开与数据库的连接。随着并发语句的执行，QueuePool 将增加其连接池的大小至默认大小为五，并允许默认的“溢出”为十。由于 Engine 本质上是连接池的“基地”，因此在应用程序中，应该保持单个 Engine 与数据库建立连接，而不是为每个连接创建新的。

注意

默认情况下，SQLite 引擎不使用 QueuePool。有关 SQLite 连接池使用的详细信息，请参阅 SQLite。

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

自定义 DBAPI connect() 参数 / 连接时例程

对于需要特殊连接方法的情况，在绝大多数情况下，最适合的方法是使用 create_engine() 层级中的一些钩子来自定义此过程。这些在以下子章节中描述。

传递给 dbapi.connect() 的特殊关键字参数

所有 Python DBAPI 都接受除连接基础之外的附加参数。常见的参数包括用于指定字符集编码和超时值的参数；更复杂的数据包括特殊的 DBAPI 常量和对象以及 SSL 子参数。有两种基本的方式可以在不复杂的情况下传递这些参数。

将参数添加到 URL 查询字符串

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

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

使用查询字符串的优点是可以在配置文件中指定附加的 DBAPI 选项，以便与 URL 中指定的 DBAPI 兼容。在这个级别传递的具体参数因 SQLAlchemy 方言而异。一些方言将所有参数都作为字符串传递，而另一些方言将解析特定的数据类型并将参数移到不同的位置，比如驱动程序级别的 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) 传递给 DBAPI。

使用 connect_args 字典参数

一个更一般的系统，用于将任何参数传递给 dbapi.connect() 函数，保证始终传递所有参数，是 create_engine.connect_args 字典参数。这可用于否则未在查询字符串中处理的参数，以及在必须将特殊子结构或对象传递给 DBAPI 时。有时，只需将特定标志作为 True 符号发送，而 SQLAlchemy 方言并不知道如何从 URL 中的字符串形式强制转换此关键字参数。下面示例说明了使用 psycopg2 “连接工厂” 替换连接的基础实现：

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() 事件挂钩进一步定制 DBAPI connect() 函数本身的调用方式。此挂钩传递了方言将发送给 connect() 的完整 *args, **kwargs。然后，这些集合可以就地修改以更改它们的使用方式：

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() 也是动态插入认证令牌的理想方式，该令牌可能在 Engine 的生命周期内发生变化。例如，如果令牌由 get_authentication_token() 生成并在 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中并非如此。

传递给dbapi.connect()的特殊关键字参数

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

将参数添加到 URL 查询字符串中

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

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

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

提示

一种显示给定 URL 的 DBAPI 所传递的精确参数的一般技术可以直接使用 Dialect.create_connect_args() 方法，如下所示：

>>> 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) 传递给 DBAPI。

使用 connect_args 字典参数

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

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 中具有特殊意义。

向 URL 查询字符串添加参数

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

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

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

提示

一种显示给定 URL 的 DBAPI 所传递的精确参数的一般技术可以直接使用 Dialect.create_connect_args() 方法，如下所示：

>>> 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) 传递给 DBAPI。

使用 connect_args 字典参数

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

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()事件钩子进一步自定义 DBAPI connect() 函数本身的调用方式。此钩子传递了方言将发送给 connect() 的完整的 *args, **kwargs。然后可以修改这些集合以更改它们的使用方式：

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()也是一种理想的方法，可以动态插入可能会随着Engine寿命而变化的认证令牌。例如，如果令牌由get_authentication_token()生成并在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 #### 生成动态认证令牌

DialectEvents.do_connect()也是一种理想的方法，可以动态插入可能会随着Engine寿命而变化的认证令牌。例如，如果令牌由get_authentication_token()生成并在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 的例子

SqlAlchemy 2.0 中文文档（四十三）（6）https://developer.aliyun.com/article/1563065