支持的数据库¶

炼金术包括很多 Dialect 各种后端的实现。最常见数据库的方言包含在sqlacalchemy中；其他一些需要额外安装一个单独的方言。

见剖面图 方言 有关各种后端的信息。

数据库URL¶

这个 create_engine() 函数会生成一个 Engine 基于URL的。这些URL如下 RFC-1738 ，通常可以包括用户名、密码、主机名、数据库名以及用于其他配置的可选关键字参数。在某些情况下，接受文件路径，而在其他情况下，“数据源名称”替换“主机”和“数据库”部分。数据库URL的典型形式为：：

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

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

由于该URL类似于任何其他URL， 需要对特殊字符(如密码中可能使用的字符)进行URL编码才能正确解析。 。以下是包含密码的URL示例 "kx%jj5/g" ，其中百分号和劈开字符表示为 %25 和 %2F ，分别为：

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

可以使用以下命令生成上述密码的编码 urllib.parse ：：

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

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

# 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')

# 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')

engine = create_engine('oracle://scott:tiger@127.0.0.1:1521/sidname')

engine = create_engine('oracle+cx_oracle://scott:tiger@tnsname')

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

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

# 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')

engine = create_engine('sqlite://')

引擎创建API¶

function sqlalchemy.create_engine(url, **kwargs)¶

创建新的 Engine 实例。

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

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

注解

请审阅 数据库URL 有关编写URL字符串的一般指导原则，请参阅。特别是，特殊字符(例如那些通常是密码一部分的字符)必须经过URL编码才能正确解析。

然后，可以在后面附加关键字参数，从而在结果中建立各种选项 Engine 它的基础 Dialect 和 Pool 结构：

engine = create_engine("mysql://scott:tiger@hostname/dbname",
                            encoding='latin1', 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 将从底层请求连接 Pool 一旦 Engine.connect() 调用，或依赖它的方法，例如 Engine.execute() 被调用。这个 Pool 当收到这个请求时，反过来将建立第一个实际的DBAPI连接。这个 create_engine() 调用本身会 not 直接建立任何实际的DBAPI连接。

参见

引擎配置

方言

使用引擎和接头

参数

• case_sensitive¶ -- 如果为false，则结果列名称将以不区分大小写的方式匹配，即， row['SomeColumn'] . .. 已弃用：：1.4 create_engine.case_sensitive 参数已弃用，将在将来的版本中删除。应用程序应该以区分大小写的方式处理结果列名。

• connect_args¶ -- 将直接传递给DBAPI的选项字典。 connect() 方法作为其他关键字参数。参见中的示例 自定义DBAPI connect（）参数/on connect例程 .

• convert_unicode=False¶ -- 如果设置为true，则会导致 String 数据类型的作用就像 String.convert_unicode 标志已设置为 True ，无论设置为 False 在个人身上 String 类型。这会导致 String -基于列来直接容纳python unicode对象，就像数据类型是 Unicode 类型。…已弃用：：1.3 create_engine.convert_unicode 参数已弃用，将在将来的版本中删除。所有现代DBAPI现在都直接支持PythonUnicode，而这个参数是不必要的。

• creator¶ -- 返回DBAPI连接的可调用文件。此创建函数将传递到基础连接池，并将用于创建所有新的数据库连接。使用此函数会导致绕过URL参数中指定的连接参数。这个钩子没有新钩子灵活 DialectEvents.do_connect() 钩子允许完全控制连接到数据库的方式，给定一组完整的URL参数和预先设置的状态。。另请参见： DialectEvents.do_connect() -允许完全控制DBAPI连接机制的事件钩子。 自定义DBAPI connect（）参数/on connect例程

• echo=False¶ -- 如果为真，引擎将记录所有语句以及 repr() 其参数列表的默认日志处理程序，默认为 sys.stdout 用于输出。如果设置为字符串 "debug" ，结果行也将打印到标准输出。这个 echo 属性 Engine 可以随时修改以打开和关闭日志记录；也可以使用标准的python直接控制日志记录。 logging 模块。…参阅： 配置日志记录 -有关如何配置日志的详细信息。

• echo_pool=False¶ -- 如果为true，则连接池将记录信息输出，例如连接失效以及连接回收到默认日志处理程序（默认为 sys.stdout 用于输出。如果设置为字符串 "debug" 日志记录将包括池签出和签入。使用标准的python还可以直接控制日志记录。 logging 模块。…参阅： 配置日志记录 -有关如何配置日志的详细信息。

• empty_in_strategy¶ -- 不再使用；SQLAlchemy现在在所有情况下都使用“空集”行为。。已弃用：：1.4 create_engine.empty_in_strategy 关键字已弃用，不再有任何效果。All IN表达式现在使用“expanding parameter”策略呈现，该策略在语句执行时呈现一组boundexpressions或“空集”SELECT。

• enable_from_linting¶ -- 默认为True。如果发现给定的SELECT语句与将导致笛卡尔积的元素取消链接，则将发出警告。。版本添加：：1.4。。另请参见： 从linting内置将在SELECT语句中警告任何潜在的笛卡尔积

• encoding¶ -- 仅旧式Python2值，其中它仅适用于特定的DBAPI，不会在Python3中用于任何现代DBAPI驱动程序。有关客户端编码行为，请参阅各个方言文档。 缺省为字符串值 utf-8 。此值表示 only 对象发送或接收数据时使用的字符编码。 DBAPI 不支持Python Unicode和 仅在Python 2下使用 ，仅适用于某些DBAPI驱动程序，并且仅在某些情况下。 Python3用户请忽略此参数，并参考正在使用的特定方言的文档以配置字符编码行为。 。。注：： encoding 参数仅处理普遍存在的内部Python编码问题 仅限某些DBAPIS 在……下面 仅Python 2 。在Python3下，任何现代方言都不使用它。对于需要客户端编码配置的DBAPI(大多数是SQLite之外的DBAPI)，请参阅具体的 dialect documentation 有关详细信息，请参阅。所有在Python3中工作的现代DBAPI都必须具有对Python Unicode字符串的直接支持。在Python2中，情况并不总是如此。对于检测到DBAPI不支持Python的情况 unicode 对象，此编码用于确定源/目标编码。它是 未使用 适用于DBAPI直接处理Unicode的情况。要正确配置系统以容纳Python，请执行以下操作 unicode 对象时，应该将dbapi配置为在适当的情况下最大程度地处理unicode-请参阅与正在使用的特定目标数据库有关的unicode说明，请参阅 方言 。可能需要在DBAPI之外进行字符串编码的区域，几乎总是在 仅Python 2 ，包括零个或多个： * the values passed to bound parameters, corresponding to the Unicode type or the String type when convert_unicode is True; * 方法对应的结果集列中返回的值 Unicode 类型或 String 键入When When convert_unicode 是 True ； * the string SQL statement passed to the DBAPI's cursor.execute() method; * 传递给DBAPI的绑定参数字典中键的字符串名称 cursor.execute() 以及 cursor.setinputsizes() 方法；*从DBAPI的检索到的字符串列名称 cursor.description 属性。使用Python 3时，DBAPI需要支持以上所有值作为Python unicode 对象，在Python3中仅称为 str 。在Python2中，DBAPI根本没有指定Unicode行为，因此SQLAlChemy必须在每个DBAPI的基础上为上述每个值做出决定-实现的行为完全不一致。

• execution_options¶ -- 将应用于所有连接的字典执行选项。见 Connection.execution_options()

• future¶ -- 使用2.0样式 Engine 和 Connection API。。版本添加：：1.4。。另请参见： 迁移到Alchemy

• hide_parameters¶ -- 布尔值，当设置为True时，SQL语句参数将不会显示在信息日志中，也不会格式化为 StatementError 对象。。版本添加：：1.3.8。。另请参见： 配置日志记录 -有关如何配置日志的详细信息。

• implicit_returning=True¶ -- 设置为时的传统标志 False 将禁用使用 RETURNING 在支持后端上，它通常用于获取新生成的单行INSERT语句的主键值，而单行INSERT语句没有另外指定RETURNING子句。此行为主要适用于PostgreSQL、Oracle、SQL Server后端。。。警告：：此标志最初允许将“隐式返回”功能 已启用 回到它非常新的时候，没有完善的数据库支持。在现代SQLAlChemy中，此标志应该 始终设置为True 。如果将此标志设置为，则某些SQLAlChemy功能将无法正常运行 False 。

• isolation_level¶ --

  为了影响数据库连接的事务隔离级别，该字符串参数由各种方言解释。参数基本上接受这些字符串参数的一些子集： "SERIALIZABLE" ， "REPEATABLE READ" ， "READ COMMITTED" ， "READ UNCOMMITTED" 和 "AUTOCOMMIT" . 这里的行为因后端而异，应该直接咨询各个方言。

  请注意，隔离级别也可以设置在 -Connection 同时，使用 Connection.execution_options.isolation_level 特征。

  参见

  Connection.default_isolation_level -查看默认级别

  Connection.execution_options.isolation_level -设置 Connection 隔离级别

  SQLite Transaction Isolation

  PostgreSQL Transaction Isolation

  MySQL Transaction Isolation

  设置事务隔离级别/DBAPI AUTOCOMMIT -为ORM

• json_deserializer¶ -- 支持 JSON 数据类型，这是一个Python可调用函数，它将JSON字符串转换为Python对象。默认情况下，Python json.loads 函数被使用。。versionchanged:：1.3.7 SQLite方言将其重命名为 _json_deserializer .

• json_serializer¶ -- 支持 JSON 数据类型，这是一个Python可调用函数，它将把给定的对象呈现为JSON。默认情况下，Python json.dumps 函数被使用。。versionchanged:：1.3.7 SQLite方言将其重命名为 _json_serializer .

• label_length=None¶ -- 可选的整数值，将动态生成的列标签的大小限制为多个字符。如果小于6，标签将生成为“u（计数器）”。如果 None 的价值 dialect.max_identifier_length ，可能会通过 create_engine.max_identifier_length 改为使用参数。价值 create_engine.label_length 可能不大于 create_engine.max_identfier_length . …参阅： create_engine.max_identifier_length

• listeners¶ -- 一个或多个列表 PoolListener 将接收连接池事件的对象。

• logging_name¶ -- 将在“sqlalChemy.engine”记录器中生成的日志记录的“name”字段中使用的字符串标识符。默认为对象ID的十六进制字符串。。。另请参阅：： 配置日志记录 -关于如何配置日志记录的更多详细信息。 Connection.execution_options.logging_token

• max_identifier_length¶ -- 整数；重写方言确定的最大标识符长度。如果 None 或者零，没有效果。这是数据库配置的SQL标识符（如表名、列名或标签名）中可以使用的最大字符数。所有方言都会自动确定这个值，但是如果是一个新的数据库版本，这个值已经改变了，但是SQLAlchemy的方言没有被调整，那么这个值可以在这里传递。。版本添加：：1.3.9。。另请参见： create_engine.label_length

• max_overflow=10¶ -- 允许在连接池中“溢出”的连接数，即可以在池大小设置（默认为5）之上或之外打开的连接数。这只和 QueuePool .

• module=None¶ -- 对python模块对象的引用（模块本身，而不是其字符串名称）。指定要由引擎方言使用的备用DBAPI模块。每个子方言引用一个特定的DBAPI，该DBAPI将在第一次连接之前导入。此参数导致忽略导入，而使用给定的模块。可以用于测试DBAPI，也可以将“模拟”的DBAPI实现注入到 Engine .

• paramstyle=None¶ -- 这个 paramstyle 在呈现绑定参数时使用。此样式默认为DBAPI本身推荐的样式，该样式是从 .paramstyle DBAPI的属性。但是，大多数DBAPI接受多个参数样式，特别是可能需要将“命名的”参数样式更改为“位置”参数样式，反之亦然。传递此属性时，它应该是以下值之一 "qmark" ， "numeric" ， "named" ， "format" 或 "pyformat" ，并且应该对应于已知受正在使用的DBAPI支持的参数样式。

• pool=None¶ -- 已构造的实例 Pool ，比如 QueuePool 实例。如果非“无”，则此池将直接用作引擎的基础连接池，忽略URL参数中存在的任何连接参数。有关手动构造连接池的信息，请参阅 连接池 .

• poolclass=None¶ -- 一 Pool 子类，将用于使用URL中给定的连接参数创建连接池实例。注意这与 pool 在这种情况下，您不会实际实例化池，您只需指示要使用的池类型。

• pool_logging_name¶ -- 字符串标识符，将在sqlalchemy.pool“记录器。默认为对象id的十六进制字符串。。另请参见： 配置日志记录 -有关如何配置日志的详细信息。

• pool_pre_ping¶ -- 如果为真，则布尔值将启用连接池的“预ping”功能，该功能在每次签出时测试连接的活动性。…版本已添加：：1.2..参阅： 断开操作-悲观

• pool_size=5¶ -- 在连接池中保持打开的连接数。用于此 QueuePool 以及 SingletonThreadPool . 用 QueuePool ，A pool_size 设置为0表示没有限制；要禁用池，请设置 poolclass 到 NullPool 相反。

• pool_recycle=-1¶ -- 此设置使池在经过给定秒数后回收连接。它默认为-1，或者没有超时。例如，设置为3600意味着连接将在一小时后循环使用。请注意，如果在8小时内未检测到任何活动，则mysql将自动断开连接（尽管这可以通过mysqldb连接本身和服务器配置进行配置）。…参阅： 设置池回收

• pool_reset_on_return='rollback'¶ -- 设置 Pool.reset_on_return 基础的参数 Pool 对象，可以设置为值 "rollback" ， "commit" 或 None . …参阅： Pool.reset_on_return

• pool_timeout=30¶ -- 放弃从池中获取连接之前等待的秒数。此选项仅用于 QueuePool 。这可以是浮点数，但受Python时间函数的限制，在几十毫秒内可能不可靠。。。注意：不要使用上面的30.0，它似乎与：param标记断开

• pool_use_lifo=False¶ --

  从中检索连接时使用后进先出 QueuePool 而不是先进先出（先进先出）。使用LIFO，服务器端超时方案可以减少非高峰时段使用的连接数。在计划服务器端超时时，请确保使用回收或预Ping策略来优雅地处理过时的连接。

  1.3 新版功能.

  参见

  使用先进先出法与后进先出法

  处理断开连接

• 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

function sqlalchemy.engine_from_config(configuration, prefix='sqlalchemy.', **kwargs)¶

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

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

关键在于 engine_from_config() 应加前缀，例如 sqlalchemy.url ， sqlalchemy.echo 等。“prefix”参数指示要搜索的前缀。每个匹配的键（除去前缀后）都被视为 create_engine() 打电话。

唯一需要的键是（假定为默认前缀） sqlalchemy.url ，它提供了 database URL .

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

参数

• configuration¶ -- 字典（通常由配置文件生成，但这不是必需的）。键以“prefix”值开头的项将去掉该前缀，然后将其传递给 create_engine() .

• prefix¶ -- 要匹配的前缀，然后从“configuration”中的键中删除。

• kwargs¶ -- 每个关键字参数 engine_from_config() 本身重写从“配置”字典中获取的相应项。关键字参数应该 not 前缀。

function sqlalchemy.create_mock_engine(url, executor, **kw)¶

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

这是一个实用函数，用于调试或存储 MetaData.create_all() 以及相关方法。

该函数接受一个仅用于确定要使用的方言类型的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://', dump)
metadata.create_all(engine, checkfirst=False)

参数

• url¶ -- 通常只需要包含数据库后端名称的字符串URL。

• executor¶ -- 接收参数的可调用函数 sql ， *multiparams 和 **params . 这个 sql 参数通常是 DDLElement ，然后可以使用 DDLElement.compile() .

1.4 新版功能: - the create_mock_engine() function replaces the previous "mock" engine strategy used with create_engine().

参见

如何以字符串形式获取创建表/删除表输出？

function sqlalchemy.engine.make_url(name_or_url)¶

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

根据RFC1738规范解析给定的字符串。如果传递了现有的URL对象，只返回该对象。

class sqlalchemy.engine.URL(*arg, **kw)¶

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

此对象适合直接传递到 create_engine() 打电话。URL的字段由 make_url() 功能。URL的字符串格式是RFC-1738样式的字符串。

创建新的 URL 对象，使用 make_url() 功能。构造 URL 以编程方式使用 URL.create() 建造师。

在 1.4 版更改: 这个 URL 对象现在是一个不可变的对象。要创建URL，请使用 make_url() 或 URL.create() 功能/方法。修改 URL ，使用如下方法 URL.set() 和 URL.update_query_dict() 返回新的 URL 修改后的对象。有关此更改，请参见 URL对象现在是不可变的 .

URL 包含以下属性：

• URL.drivername: database backend and driver name, such as postgresql+psycopg2

• URL.username ：用户名字符串

• URL.password ：密码字符串或包含 __str__() 生成密码的方法。

  注解

  密码生成对象将仅被字符串化为字符串 once 每 Engine 对象。有关每次连接生成动态口令的信息，请参见 生成动态身份验证令牌 。

• URL.host ：String主机名

• URL.port ：整数端口号

• URL.database ：String数据库名称

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

类签名

class sqlalchemy.engine.URL (sqlalchemy.engine.URL)

attribute sqlalchemy.engine.URL.drivername str¶

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

attribute sqlalchemy.engine.URL.username str¶

用户名字符串

attribute sqlalchemy.engine.URL.password str¶

密码，通常是字符串，但也可以是任何具有 __str__() 方法。

attribute sqlalchemy.engine.URL.host str¶

字符串主机名

attribute sqlalchemy.engine.URL.port int¶

整数端口号

attribute sqlalchemy.engine.URL.database str¶

字符串数据库名称

attribute sqlalchemy.engine.URL.query Mapping[str, Union[str, Sequence[str]]]¶

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

   >>> from sqlalchemy.engine import make_url
   >>> url = make_url("postgresql://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 sqlalchemy.engine.URL.classmethod create(drivername, username=None, password=None, host=None, port=None, database=None, query={})¶

创建新的 URL 对象。

参数

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

• username¶ -- 用户名。

• password¶ -- 数据库密码。通常是字符串，但也可以是可以用 str() 。。。注意：：密码生成对象将仅被字符串化为字符串 once 每 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() 方法。

method sqlalchemy.engine.URL.difference_update_query(names)¶

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

method sqlalchemy.engine.URL.get_backend_name()¶

返回后端名称。

这是与正在使用的数据库后端相对应的名称，是 URL.drivername 在加号的左边。

method sqlalchemy.engine.URL.get_dialect()¶

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

method sqlalchemy.engine.URL.get_driver_name()¶

返回后端名称。

这是与正在使用的DBAPI驱动程序相对应的名称，是 URL.drivername 在加号的右边。

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

attribute sqlalchemy.engine.URL.normalized_query¶

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

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

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://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',)})

method sqlalchemy.engine.URL.render_as_string(hide_password=True)¶

呈现这个 URL 对象作为字符串。

当 __str__() 或 __repr__() 使用方法。该方法直接包含其他选项。

参数

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

method sqlalchemy.engine.URL.set(drivername=None, username=None, password=None, host=None, port=None, database=None, query=None)¶

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

如果值非“无”，则使用这些值。将值设置为 None 显式地使用 URL._replace() 方法改编自 namedtuple .

参数

• drivername¶ -- 新驾驶员姓名

• username¶ -- 新用户名

• password¶ -- 新密码

• host¶ -- 新主机名

• port¶ -- 新港口

• query¶ -- 新的查询参数，传递了一个引用字符串或字符串值序列的字符串键dict。完全替换以前的参数列表。

返回

新的 URL 对象。

1.4 新版功能.

参见

URL.update_query_dict()

method sqlalchemy.engine.URL.translate_connect_args(names=None, **kw)¶

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

返回此URL的属性 (host ， database ， username ， password ， port ）作为一本普通的字典。默认情况下，属性名用作键。未设置或错误的属性将从最终字典中省略。

参数

• **kw¶ -- 可选，URL属性的备用键名。

• names¶ -- 不赞成的与基于关键字的备用名称的用途相同，但将名称与原始位置相关联。

method sqlalchemy.engine.URL.update_query_dict(query_parameters, append=False)¶

返回一个新的 URL 对象与 URL.query 由给定字典更新的参数字典。

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

例如。：：

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://user:pass@host/dbname")
>>> url = url.update_query_dict({"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"})
>>> str(url)
'postgresql://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 sqlalchemy.engine.URL.update_query_pairs(key_value_pairs, append=False)¶

返回一个新的 URL 对象与 URL.query 由给定的键/值对序列更新的参数字典

例如。：：

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://user:pass@host/dbname")
>>> url = url.update_query_pairs([("alt_host", "host1"), ("alt_host", "host2"), ("ssl_cipher", "/path/to/crt")])
>>> str(url)
'postgresql://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 sqlalchemy.engine.URL.update_query_string(query_string, append=False)¶

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

例如。：：

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql://user:pass@host/dbname")
>>> url = url.update_query_string("alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
>>> str(url)
'postgresql://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()

池化¶

这个 Engine 当 connect() 或 execute() 方法被调用。默认连接池， QueuePool ，将根据需要打开与数据库的连接。当执行并发语句时， QueuePool 将其连接池扩大到默认大小5，并允许默认“溢出”10。自从 Engine 基本上是连接池的“home base”，因此应该保留一个 Engine 在应用程序中建立的每个数据库，而不是为每个连接创建一个新的数据库。

有关连接池的详细信息，请参阅 连接池 .

自定义DBAPI connect（）参数/on connect例程¶

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

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

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

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

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

from sqlalchemy import event

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

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

from sqlalchemy import event

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

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

from sqlalchemy import event

engine = create_engine(
    "postgresql://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()

from sqlalchemy import event

engine = create_engine(
    "postgresql://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)

配置日志记录¶

Python标准 logging 模块用于通过SQLAlChemy实现信息性日志输出和调试日志输出。这允许SQLAlChemy的日志记录以标准方式与其他应用程序和库集成。还有两个参数 create_engine.echo 和 create_engine.echo_pool 出席时间 create_engine() 它们允许立即记录到 sys.stdout 出于本地开发的目的，这些参数最终与下面描述的常规Python记录器交互。

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

• sqlalchemy.engine -控制SQL回显。设置为 logging.INFO 对于SQL查询输出， logging.DEBUG 用于查询+结果集输出。这些设置相当于 echo=True 和 echo="debug" 在 create_engine.echo ，分别。

• sqlalchemy.pool -控制连接池日志记录。设置为 logging.INFO 记录连接失效和回收事件；设置为 logging.DEBUG 另外记录所有池签入和签出。这些设置相当于 pool_echo=True 和 pool_echo="debug" 在 create_engine.echo_pool ，分别。

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

• sqlalchemy.orm -控制各种ORM函数的日志记录，使日志记录在ORM中使用，这通常是最小的。设置为 logging.INFO 记录一些映射器配置的顶级信息。

例如，使用python日志记录而不是 echo=True 旗帜：

import logging

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

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

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

>>> from sqlalchemy import create_engine
>>> from sqlalchemy import text
>>> e = create_engine("sqlite://", echo=True, 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 ()

>>> from sqlalchemy import create_engine
>>> e = create_engine("sqlite://", echo="debug")
>>> with e.connect().execution_options(logging_token="track1") as conn:
...     conn.execute("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,)

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

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