引擎配置¶

这个 Engine 是任何SQLAlchemy应用程序的起点。它是实际数据库及其 DBAPI ,通过连接池和 Dialect 它描述了如何与特定类型的数据库/DBAPI组合对话。

总体结构如下:

../_images/sqla_engine_arch.png

在上面,一个 Engine 参考两者a Dialect 和A Pool 它们一起解释DBAPI的模块函数以及数据库的行为。

创建引擎只需发出一个调用, create_engine() ::

from sqlalchemy import create_engine
engine = create_engine('postgresql://scott:tiger@localhost:5432/mydatabase')

上面的引擎创建一个 Dialect 针对PostgreSQL定制的对象,以及 Pool 将在以下位置建立DBAPI连接的对象 localhost:5432 当第一次收到连接请求时。请注意 Engine 它的基础 Poolnot 建立第一个实际DBAPI连接,直到 Engine.connect() 方法,或依赖于此方法的操作,例如 Engine.execute() 被调用。这样, EnginePool 可以说有一个 延迟初始化 行为。

这个 Engine 创建后,既可以直接用于与数据库交互,也可以传递给 Session 对象以使用ORM。本节介绍配置 Engine . 下一节, 使用引擎和接头 ,将详细说明 Engine 类似的,通常用于非ORM应用程序。

支持的数据库

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

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

数据库URL

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

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

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

由于该URL与任何其他URL类似,因此密码中可能使用的特殊字符需要进行URL编码。下面是一个包含密码的URL示例 "kx%jj5/g" ::

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

上述密码的编码可以使用 urllib ::

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

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

《PostgreSQL》

PostgreSQL方言使用psycopg2作为默认dbapi。PG8000也可作为纯python替代品提供:

# 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方言使用mysql python作为默认dbapi。mysql dbapis有很多,包括mysql connector python和oursql::

# 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 .

甲骨文公司

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的更多说明,请访问 甲骨文公司 .

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

有关在上连接到SQL Server的详细说明 Microsoft SQL服务器 .

SQLite

sqlite使用python内置模块连接到基于文件的数据库 sqlite3 默认情况下。

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

# 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 .

其他

方言 ,所有其他方言文档的顶级页面。

引擎创建API

sqlalchemy.create_engine(*args, **kwargs)

创建新的 Engine 实例。

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

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

然后,可以在后面附加关键字参数,从而在结果中建立各种选项 Engine 它的基础 DialectPool 结构:

engine = create_engine("mysql://scott:tiger@hostname/dbname",
                            encoding='latin1', echo=True)

URL的字符串形式为 dialect[+driver]://user:password@host/dbname[?key=value..] 在哪里 dialect 是数据库名称,例如 mysqloraclepostgresql 等,以及 driver DBAPI的名称,例如 psycopg2pyodbccx_oracle 或者,URL可以是 URL .

**kwargs 采用了各种各样的选项,这些选项被路由到它们相应的组件。参数可能特定于 Engine ,基础 Dialect 以及 Pool . 特定方言还接受该方言特有的关键字参数。在这里,我们描述了最常见的参数 create_engine() 用法。

一旦建立,新的结果 Engine 将从底层请求连接 Pool 一旦 Engine.connect() 调用,或依赖它的方法,例如 Engine.execute() 被调用。这个 Pool 当收到这个请求时,反过来将建立第一个实际的DBAPI连接。这个 create_engine() 调用本身会 not 直接建立任何实际的DBAPI连接。

参数
  • case_sensitive=True -- 如果为false,则结果列名称将以不区分大小写的方式匹配,即, row['SomeColumn'] .

  • connect_args -- 将直接传递给DBAPI的选项字典。 connect() 方法作为其他关键字参数。参见中的示例 自定义dbapi 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参数中指定的连接参数。

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

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

  • empty_in_strategy -- 呈现In或Not In表达式时要使用的SQL编译策略 ColumnOperators.in_() 右手边是空的。这是一个字符串值,可以是 staticdynamicdynamic_warn . 这个 static 策略是默认的,与空集比较会生成一个简单的错误表达式“1!= 1”。这个 dynamic 策略的行为类似于SQLAlchemy 1.1和更早版本,发出形式为“expr!”的错误表达式。=expr”,在使用空表达式的情况下,它的作用是计算为空。 dynamic_warn 是一样的 dynamic 但是,当遇到空集时也会发出警告;这是因为"动态"比较在大多数数据库上通常表现不佳。…版本添加::1.2添加了 empty_in_strategy 在与静态布尔表达式的比较中设置并另外默认空集的行为。

  • encoding -- 默认为 utf-8 . 这是sqlAlchemy用于在sqlAlchemy中发生的字符串编码/解码操作的字符串编码, 在DBAPI之外。 大多数现代DBAPI都具有某种程度上对Python的直接支持。 unicode 对象,您在python 2中看到的是表单的字符串 u'some string' . 对于检测到DBAPI不支持Python的情况 unicode 对象,此编码用于确定源/目标编码。它是 不使用 对于DBAPI直接处理Unicode的情况。正确配置系统以适应python unicode 对象,dbapi应配置为在适当的情况下最大程度地处理unicode-请参阅unicode上与在处使用的特定目标数据库相关的说明。 方言 . 需要在DBAPI之外容纳字符串编码的区域包括以下零个或多个: * the values passed to bound parameters, corresponding to the Unicode type or the String type when convert_unicode is True; * 结果集列中返回的值与 Unicode 类型或 String 当类型 convert_unicodeTrue ; * the string SQL statement passed to the DBAPI's cursor.execute() method; * 传递给DBAPI的绑定参数字典中键的字符串名称 cursor.execute() 以及 cursor.setinputsizes() 方法; * the string column names retrieved from the DBAPI's cursor.description attribute. When using Python 3, the DBAPI is required to support * 以上所有值*均为python unicode 对象,在python 3中称为 str . 在python 2中,dbapi根本没有指定unicode行为,因此sqlAlchemy必须根据每个dbapi为上述每个值做出决策-实现的行为完全不一致。

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

  • implicit_returning=True -- 什么时候? True ,如果没有返回()子句发出单行insert语句,则将使用返回兼容的构造(如果可用)来获取新生成的主键值。这适用于支持返回或兼容构造的后端,包括PostgreSQL、Firebird、Oracle、Microsoft SQL Server。设置为 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 设置事务隔离级别 -为ORM

  • label_length=None -- 可选的整数值,将动态生成的列标签的大小限制为多个字符。如果小于6,标签将生成为“u(计数器)”。如果 None 的价值 dialect.max_identifier_length 而是使用。

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

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

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

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

  • paramstyle=None -- 这个 paramstyle 在呈现绑定参数时使用。此样式默认为DBAPI本身推荐的样式,从 .paramstyle DBAPI的属性。然而,大多数DBAPI接受多个paramStyle,尤其是将“命名的”paramStyle更改为“位置的”paramStyle可能是可取的,反之亦然。传递此属性时,它应该是其中一个值 "qmark""numeric""named""format""pyformat" ,并且应该对应于使用中的DBAPI所支持的参数样式。

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

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

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

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

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

  • 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 .

  • pool_use_lifo=False -- 从中检索连接时使用后进先出 QueuePool 而不是先进先出(先进先出)。使用LIFO,服务器端超时方案可以减少非高峰时段使用的连接数。在计划服务器端超时时,请确保使用回收或预Ping策略来优雅地处理过时的连接。…添加的版本:1.3..参阅: 使用先进先出法与后进先出法 处理断开连接

  • plugins -- 要加载的插件名称的字符串列表。见 CreateEnginePlugin 作为背景。…添加的版本:1.2.3

  • strategy='plain' -- 选择备用引擎实现。目前可用的有: * the threadlocal strategy, which is described in 使用线程本地执行策略; * 这个 mock 策略,将所有语句执行分派给作为参数传递的函数 executor . 见 example in the FAQ .

  • executor=None -- 接受参数的函数 (sql, *multiparams, **params) , to which the mock 策略将调度所有语句执行。仅用于 strategy='mock' .

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

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

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

关键在于 engine_from_config() 应加前缀,例如 sqlalchemy.urlsqlalchemy.echo 等。“prefix”参数指示要搜索的前缀。每个匹配的键(除去前缀后)都被视为 create_engine() 调用。

唯一需要的键是(假定为默认前缀) sqlalchemy.url ,它提供了 database URL .

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

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

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

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

sqlalchemy.engine.url.make_url(name_or_url)

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

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

class sqlalchemy.engine.url.URL(drivername, username=None, password=None, host=None, port=None, database=None, query=None)

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

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

所有初始化参数都可用作公共属性。

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

  • username -- 用户名。

  • password -- 数据库密码。

  • host -- 主机的名称。

  • port -- 端口号。

  • database -- 数据库名称。

  • query -- 连接时要传递给方言和/或DBAPI的选项字典。

get_dialect()

返回与此URL的驱动程序名相对应的sqlAlchemy数据库方言类。

translate_connect_args(names=[], **kw)

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

返回此URL的属性 (hostdatabaseusernamepasswordport )作为一本普通的字典。默认情况下,属性名用作键。未设置或错误的属性将从最终字典中省略。

参数
  • **kw -- 可选,URL属性的备用键名。

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

池化

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

注解

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

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

自定义dbapi connect()参数

发布时使用的自定义参数 connect() 对底层DBAPI的调用可以通过三种不同的方式发出。基于字符串的参数可以作为查询参数直接从URL字符串传递:

db = create_engine('postgresql://scott:tiger@localhost/test?argument1=foo&argument2=bar')

如果SQLAlchemy的数据库连接器知道某个特定的查询参数,则它可以将其类型从字符串转换为正确的类型。

create_engine() 也接受一个论点 connect_args 这是将传递给 connect() . 当需要非字符串类型的参数,并且sqlachemy的数据库连接器没有该参数的类型转换逻辑时,可以使用此选项:

db = create_engine('postgresql://scott:tiger@localhost/test', connect_args = {'argument1':17, 'argument2':'bar'})

最可定制的连接方法是 creator 参数,指定返回DBAPI连接的可调用文件:

def connect():
    return psycopg.connect(user='scott', host='localhost')

db = create_engine('postgresql://', creator=connect)

配置日志记录

Python's standard logging module is used to implement informational and debug log output with SQLAlchemy. This allows SQLAlchemy's logging to integrate in a standard way with other applications and libraries. There are also two parameters create_engine.echo and create_engine.echo_pool present on create_engine() which allow immediate logging to sys.stdout for the purposes of local development; these parameters ultimately interact with the regular Python loggers described below.

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

例如,使用python日志记录而不是 echo=True 标志:

import logging

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

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

这个 echo 作为关键字参数出现的标志 create_engine() 以及其他 echo 属性对 Engine ,当设置为 True 将首先尝试确保启用日志记录。不幸的是, logging 模块无法确定是否已配置输出(注意,我们指的是是否已设置日志配置,而不仅仅是设置了日志级别)。因此,任何 echo=True 标志将导致调用 logging.basicConfig() 使用sys.stdout作为目标。它还使用级别名称、时间戳和记录器名称设置默认格式。请注意,此配置会影响正在配置的 此外 到任何现有的记录器配置。因此, 使用python日志记录时,请确保始终将所有echo标志设置为false。 ,以避免得到重复的日志行。

实例的记录器名称,如 EnginePool 默认为使用截断的十六进制标识符字符串。要将其设置为特定名称,请使用“logging_name”和“pool_logging_name”关键字参数 sqlalchemy.create_engine() .

注解

圣卢西亚 Engine 当当前日志级别被检测为 logging.INFOlogging.DEBUG . 它只在从连接池获取新连接时检查此级别。因此,当更改已经运行的应用程序的日志配置时, Connection 当前处于活动状态,或者更常见的是 Session 对象在事务中处于活动状态,在新的 Connection 采购(在 Session ,这是在当前事务结束并且新事务开始之后)。