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

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

支持的数据库

SQLAlchemy 包含许多不同后端的 Dialect 实现。SQLAlchemy 包含最常见数据库的方言；另外一些需要额外安装单独的方言。

参见 方言 部分了解各种可用后端的信息。## 数据库 URL

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

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

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

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

构建一个完整的 URL 字符串以传递给 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.create() 构造方法创建 URL 对象，通过逐个传递所有字段。密码中的特殊字符可以不做任何修改地传递：

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)

另见

URL

URL.create()

后端特定的 URLs

下面是常见连接样式的示例。要获取所有包含的方言的详细信息以及第三方方言的链接，请参阅 Dialects。

PostgreSQL

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

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 的更多注意事项请参考 MySQL 和 MariaDB。

Oracle

Oracle 方言使用 cx_oracle 作为默认的 DBAPI：

engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/sidname")
engine = create_engine("oracle+cx_oracle://scott:tiger@tnsname")

连接到 Oracle 的更多注意事项请参考 Oracle。

Microsoft SQL Server

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

连接到 SQL Server 的更多注意事项请参考 Microsoft 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。

其他

请查看方言，其中包含所有额外方言文档的顶级页面。## Engine Creation 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 例程中的示例。
  
• creator –
  一个可调用的函数，返回一个 DBAPI 连接。此创建函数将传递给底层连接池，并将用于创建所有新的数据库连接。使用此函数会绕过 URL 参数中指定的连接参数。
  这个钩子不像较新的DialectEvents.do_connect()钩子那样灵活，后者允许完全控制如何连接到数据库，考虑到之前的 URL 参数和状态。
  另请参阅
  DialectEvents.do_connect() - 允许完全控制 DBAPI 连接机制的事件钩子。
  自定义 DBAPI connect()参数 / on-connect 例程
  
• echo=False –
  如果为 True，则 Engine 将记录所有语句以及它们参数列表的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 表达式现在都使用“扩展参数”策略进行渲染，该策略在语句执行时会渲染一组绑定的表达式，或者一个“空集合”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=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数据类型的方言，这是一个将 JSON 字符串转换为 Python 对象的 Python 可调用函数。默认情况下，使用 Python 的json.loads函数。
  从版本 1.3.7 开始更改：SQLite 方言将其从_json_deserializer改名为。
  
• json_serializer –
  对支持JSON数据类型的方言来说，这是一个 Python 可调用函数，用于将给定对象呈现为 JSON。默认情况下，使用 Python 的json.dumps函数。
  在 1.3.7 版本中更改：SQLite 方言将其从_json_serializer重命名为其他内容。
  
• label_length=None –
  可选整数值，限制动态生成的列标签的大小到该字符数。如果小于 6，则标签生成为“_(counter)”。如果为None，则使用create_engine.max_identifier_length参数受影响的dialect.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 – 允许在连接池“溢出”中打开的连接数，即在池大小设置之上可以打开的连接数，默认为五。仅与QueuePool一起使用。
  
• module=None – Python 模块对象的引用（模块本身，而不是其字符串名称）。指定引擎方言要使用的替代 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 语句的“Insert Many Values”行为
  

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，仅用于确定要使用的方言类型，以及一个“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()函数替换了以前与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，请使用从 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 的属性（主机、数据库、用户名、密码、端口）作为普通字典返回。默认情况下，属性名称用作键。未设置或为假的属性将从最终字典中省略。

参数：

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

method update_query_dict(query_parameters: Mapping[str, str | List[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()

URL.set()

method update_query_pairs(key_value_pairs: Iterable[Tuple[str, str | List[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()

URL.set()

method update_query_string(query_string: 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_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

用户名 字符串

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