这个 Engine
是任何SQLAlchemy应用程序的起点。它是实际数据库及其 DBAPI ,通过连接池和 Dialect
它描述了如何与特定类型的数据库/DBAPI组合对话。
总体结构如下:
在上面,一个 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
它的基础 Pool
做 not 建立第一个实际DBAPI连接,直到 Engine.connect()
方法,或依赖于此方法的操作,例如 Engine.execute()
被调用。这样, Engine
和 Pool
可以说有一个 延迟初始化 行为。
这个 Engine
创建后,既可以直接用于与数据库交互,也可以传递给 Session
对象以使用ORM。本节介绍配置 Engine
. 下一节, 使用引擎和接头 ,将详细说明 Engine
类似的,通常用于非ORM应用程序。
SQLAlchemy包括很多 Dialect
各种后端的实现。最常见数据库的方言包含在SQLAlchemy中;其他一些需要额外安装一个单独的方言。
见剖面图 方言 有关各种后端的信息。
这个 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"
::
postgresql+pg8000://dbuser:kx%25jj5%2Fg@pghost10/appdb
上述密码的编码可以使用 urllib
::
>>> import urllib.parse
>>> urllib.parse.quote_plus("kx%jj5/g")
'kx%25jj5%2Fg'
下面是常见连接样式的示例。有关所有包含方言的详细信息以及到第三方方言的链接的完整索引,请参见 方言 .
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 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的更多说明,请访问 甲骨文公司 .
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使用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 .
sqlalchemy.
create_engine
(*args, **kwargs)¶创建新的 Engine
实例。
标准的调用形式是将URL作为第一个位置参数发送,通常是一个指示数据库方言和连接参数的字符串:
engine = create_engine("postgresql://scott:tiger@localhost/test")
然后,可以在后面附加关键字参数,从而在结果中建立各种选项 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=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_()
右手边是空的。这是一个字符串值,可以是 static
, dynamic
或 dynamic_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_unicode
是 True
; * 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表示没有限制;要禁用池,请设置 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_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.url
, sqlalchemy.echo
等。“prefix”参数指示要搜索的前缀。每个匹配的键(除去前缀后)都被视为 create_engine()
调用。
唯一需要的键是(假定为默认前缀) sqlalchemy.url
,它提供了 database URL .
一组关键字参数将根据字符串值“强制”为其预期类型。参数集可根据方言扩展,使用 engine_config_types
访问器。
sqlalchemy.engine.url.
make_url
(name_or_url)¶给定一个字符串或Unicode实例,生成一个新的URL实例。
根据RFC1738规范解析给定的字符串。如果传递了现有的URL对象,只返回该对象。
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样式的字符串。
所有初始化参数都可用作公共属性。
get_dialect
()¶返回与此URL的驱动程序名相对应的sqlAlchemy数据库方言类。
这个 Engine
当 connect()
或 execute()
方法被调用。默认连接池, QueuePool
,将根据需要打开与数据库的连接。当执行并发语句时, QueuePool
将其连接池扩大到默认大小5,并允许默认“溢出”10。自从 Engine
基本上是连接池的“home base”,因此应该保留一个 Engine
在应用程序中建立的每个数据库,而不是为每个连接创建一个新的数据库。
有关连接池的详细信息,请参阅 连接池 .
发布时使用的自定义参数 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记录器的通用命名空间如下:
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
命名空间,这样即使在启用了日志记录的应用程序中也不会发生日志操作。
这个 echo
作为关键字参数出现的标志 create_engine()
以及其他 echo
属性对 Engine
,当设置为 True
将首先尝试确保启用日志记录。不幸的是, logging
模块无法确定是否已配置输出(注意,我们指的是是否已设置日志配置,而不仅仅是设置了日志级别)。因此,任何 echo=True
标志将导致调用 logging.basicConfig()
使用sys.stdout作为目标。它还使用级别名称、时间戳和记录器名称设置默认格式。请注意,此配置会影响正在配置的 此外 到任何现有的记录器配置。因此, 使用python日志记录时,请确保始终将所有echo标志设置为false。 ,以避免得到重复的日志行。
实例的记录器名称,如 Engine
或 Pool
默认为使用截断的十六进制标识符字符串。要将其设置为特定名称,请使用“logging_name”和“pool_logging_name”关键字参数 sqlalchemy.create_engine()
.
注解
圣卢西亚 Engine
当当前日志级别被检测为 logging.INFO
或 logging.DEBUG
. 它只在从连接池获取新连接时检查此级别。因此,当更改已经运行的应用程序的日志配置时, Connection
当前处于活动状态,或者更常见的是 Session
对象在事务中处于活动状态,在新的 Connection
采购(在 Session
,这是在当前事务结束并且新事务开始之后)。