引擎配置¶

支持的数据库¶

SQLAlchemy includes many Dialect implementations for various backends. 最常用数据库的方言包含在SQLAlchemy中；少数其他人需要另外安装一个单独的方言。

有关各种可用后端的信息，请参阅Dialects部分。

数据库网址¶

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

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

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

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

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

# mysql-python
engine = create_engine('mysql+mysqldb://scott:tiger@localhost/foo')

# MySQL-connector-python
engine = create_engine('mysql+mysqlconnector://scott:tiger@localhost/foo')

# OurSQL
engine = create_engine('mysql+oursql://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 ¶

sqlalchemy。 create_engine （ * args，** kwargs / T5> ¶ T6>

创建一个新的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 takes a wide variety of options which are routed towards their appropriate components. 参数可能特定于Engine，底层的Dialect以及Pool。特定的方言也接受该方言所独有的关键字参数。Here, we describe the parameters that are common to most create_engine() usage.

一旦建立，一旦Engine.connect()被调用，新生成的Engine将请求来自底层Pool的连接，例如Engine.execute()被调用。当接收到这个请求时，Pool反过来将建立第一个实际的DBAPI连接。The create_engine() call itself does not establish any actual DBAPI connections directly.

也可以看看

Engine Configuration

Dialects

Working with Engines and Connections

参数：

case_sensitive = True ¶ - if False, result column names will match in a case-insensitive fashion, that is, row['SomeColumn']. 在版本0.8中更改：默认情况下，结果行名称区分大小写。在版本0.7和之前的版本中，所有匹配都不区分大小写。 connect_args¶ – a dictionary of options which will be passed directly to the DBAPI’s connect() method as additional keyword arguments. 请参阅Custom DBAPI connect() arguments中的示例。 convert_unicode = False ¶ - if set to True, sets the default behavior of convert_unicode on the String type to True, regardless of a setting of False on an individual String type, thus causing all String -based columns to accommodate Python unicode objects. 当使用不支持本地支持Python unicode对象的DBAPI时，该标志可用作引擎范围的设置，并在收到一个错误时引发错误（如带有FreeTDS的pyodbc）。 有关此标志指示的更多详细信息，请参阅String。 creator ¶ - 返回DBAPI连接的可调用对象。这个创建函数将被传递到底层连接池，并将用于创建所有新的数据库连接。该函数的使用会导致URL参数中指定的连接参数被绕过。 echo=False¶ – if True, the Engine will log all statements as well as a repr() of their parameter lists to the engines logger, which defaults to sys.stdout. 可以随时修改Engine的echo属性，以打开和关闭日志记录。如果设置为字符串"debug"，结果行也会打印到标准输出。这个标志最终控制着一个Python记录器；有关如何直接配置日志记录的信息，请参阅Configuring Logging。 echo_pool=False¶ – if True, the connection pool will log all checkouts/checkins to the logging stream, which defaults to sys.stdout. 这个标志最终控制着一个Python记录器；有关如何直接配置日志记录的信息，请参阅Configuring Logging。 编码 ¶ - 默认为utf-8。This is the string encoding used by SQLAlchemy for string encode/decode operations which occur within SQLAlchemy, outside of the DBAPI.大多数现代的DBAPI都具有对Python unicode对象的一定程度的直接支持，您在Python 2中看到的形式为u'some 字符串“ T4> T2>。对于DBAPI被检测为不支持Python unicode对象的情况，此编码用于确定源/目标编码。对于DBAPI直接处理unicode的情况，未使用。 要正确配置系统以适应Python unicode对象，应该将DBAPI配置为根据需要最大程度地处理unicode - 请参阅Dialects 可能需要在DBAPI之外容纳字符串编码的领域包括零个或多个： the values passed to bound parameters, corresponding to the Unicode type or the String type when convert_unicode is True; the values returned in result set columns corresponding to the Unicode type or the String type when convert_unicode is True; 将字符串SQL语句传递给DBAPI的cursor.execute()方法； 绑定参数字典中的键的字符串名称传递给DBAPI的cursor.execute()以及cursor.setinputsizes()方法； 从DBAPI的cursor.description属性中检索的字符串列名称。 When using Python 3, the DBAPI is required to support all of the above values as Python unicode objects, which in Python 3 are just known as str. 在Python 2中，DBAPI根本没有指定unicode行为，所以SQLAlchemy必须在每个DBAPI基础上为每个上述值做出决定 - 实现在它们的行为中完全不一致。 execution_options ¶ - 将应用于所有连接的字典执行选项。请参阅execution_options() implicit_returning=True¶ – When True, a RETURNING- compatible construct, if available, will be used to fetch newly generated primary key values when a single row INSERT statement is emitted with no existing returning() clause. 这适用于那些支持RETURNING或兼容构造的后端，包括Postgresql，Firebird，Oracle，Microsoft SQL Server。将其设置为False以禁用自动使用RETURNING。 isolation_level ¶ - 此字符串参数由各种方言解释，以影响数据库连接的事务隔离级别。参数基本上接受这些字符串参数的一些子集："SERIALIZABLE"，"REPEATABLE_READ"，"READ_COMMITTED"，"READ_UNCOMMITTED"和"AUTOCOMMIT"。这里的行为因后端而异，应直接咨询个别方言。 请注意，也可以使用Connection.execution_options.isolation_level功能在每个Connection基础上设置隔离级别。 也可以看看 Connection.default_isolation_level - 查看默认级别 Connection.execution_options.isolation_level - 根据Connection设置隔离级别 SQLite Transaction Isolation Postgresql Transaction Isolation MySQL Transaction Isolation Setting Transaction Isolation Levels - for the ORM label_length=None¶ – optional integer value which limits the size of dynamically generated column labels to that many characters. 如果小于6，标签生成为“_（计数器）”。如果None，则使用dialect.max_identifier_length的值代替。 listeners¶ – A list of one or more PoolListener objects which will receive connection pool events. logging_name¶ – String identifier which will be used within the “name” field of logging records generated within the “sqlalchemy.engine” logger. 缺省为对象ID的十六进制字符串。 max_overflow=10¶ – the number of connections to allow in connection pool “overflow”, that is connections that can be opened above and beyond the pool_size setting, which defaults to five. 这仅用于QueuePool。 module=None¶ – reference to a Python module object (the module itself, not its string name). 指定引擎方言使用的备用DBAPI模块。每个子方言引用一个特定的DBAPI，它将在第一次连接之前被导入。此参数导致绕过导入，并改为使用给定的模块。可用于测试DBAPI以及将“模拟”DBAPI实现注入到Engine中。 paramstyle=None¶ – The paramstyle to use when rendering bound parameters. 此样式默认为由DBAPI本身推荐的样式，该样式从DBAPI的.paramstyle属性中检索。但是，大多数DBAPI接受多个参数样式，特别是可能希望将“已命名”参数样式更改为“定位”参数样式，反之亦然。当这个属性被传递时，它应该是"qmark"，"numeric"，"named"，"format"或"pyformat"，并且应该与已知的DBAPI支持的参数样式相对应。 pool=None¶ – an already-constructed instance of Pool, such as a QueuePool instance. 如果为非无，则此池将直接用作引擎的基础连接池，绕过URL参数中存在的任何连接参数。有关手动构建连接池的信息，请参阅Connection Pooling。 poolclass=None¶ – a Pool subclass, which will be used to create a connection pool instance using the connection parameters given in the URL. 请注意，这与pool不同，因为在这种情况下您并未真正实例化池，您只需指出要使用的池的类型。 pool_logging_name¶ – String identifier which will be used within the “name” field of logging records generated within the “sqlalchemy.pool” logger. 缺省为对象ID的十六进制字符串。 pool_size = 5 ¶ - 在连接池内保持打开的连接数。这与QueuePool以及SingletonThreadPool一起使用。对于QueuePool，pool_size设置为0表示没有限制；要禁用池化，请将poolclass设置为NullPool。 pool_recycle=-1¶ – this setting causes the pool to recycle connections after the given number of seconds has passed. 它默认为-1，或者没有超时。例如，设置为3600意味着连接将在一小时后回收。请注意，如果在连接上没有检测到任何活动8小时（尽管可以使用MySQLDB连接本身和服务器配置进行配置），MySQL尤其会自动断开连接。 pool_reset_on_return ='rollback' ¶ - 设置池的“reset on return”行为，即是否在连接返回池时调用rollback()，commit()或任何内容。在Pool中查看reset_on_return的文档字符串。 New in version 0.7.6. pool_timeout = 30 ¶ - 放弃从池中获取连接之前等待的秒数。这仅用于QueuePool。 strategy ='plain' ¶ - 选择备用引擎实现。目前可用的有： Using the Threadlocal Execution Strategy描述threadlocal策略； mock策略，它将所有语句执行分派给作为参数executor传递的函数。请参阅FAQ中的示例。 executor=None¶ – a function taking arguments (sql, *multiparams, **params), to which the mock strategy will dispatch all statement execution. 仅用于strategy='mock'。

sqlalchemy。 engine_from_config （ configuration，prefix ='sqlalchemy。'， ** kwargs T5> ） T6> ¶ T7>

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

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

对engine_from_config()感兴趣的键应加上前缀，例如“ sqlalchemy.url，sqlalchemy.echo等'prefix'参数表示要搜索的前缀。每个匹配键（在前缀被剥离后）都被视为是create_engine()调用的对应关键字参数。

唯一需要的密钥是（假设默认前缀）sqlalchemy.url，它提供database URL。

一组选定的关键字参数将根据字符串值“强制”为其预期类型。这组参数是使用engine_config_types存取器的可扩展每个方言。

参数：	configuration¶ – A dictionary (typically produced from a config file, but this is not a requirement). 键名以'prefix'开头的项目将剥离该前缀，然后传递给create_engine。 prefix¶ – Prefix to match and then strip from keys in ‘configuration’. kwargs¶ – Each keyword argument to engine_from_config() itself overrides the corresponding item taken from the ‘configuration’ dictionary. 关键字参数应该以不是为前缀。

sqlalchemy.engine.url。 T0> make_url T1> （ T2> name_or_url T3> ） T4> ¶< / T5>

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

给定的字符串根据RFC 1738规范进行分析。如果传递一个现有的URL对象，只返回该对象。

class sqlalchemy.engine.url。 URL （ drivername，=无，密码=无，主机=无，端口=无，数据库=无 ，query = None t>> ） ¶

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

该对象适合直接传递给create_engine()调用。URL的字段由make_url()函数从字符串中解析。该URL的字符串格式是RFC-1738样式的字符串。

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

参数：	驱动程序名称 ¶ - 数据库后端的名称。该名称将对应于sqlalchemy /数据库中的模块或第三方插件。 用户名 ¶ - 用户名。 密码 ¶ - 数据库密码。 tt> 主机 ¶ - 主机的名称。 端口 ¶ - 端口号。 数据库 ¶ - 数据库名称。 query¶ – A dictionary of options to be passed to the dialect and/or the DBAPI upon connect.

get_dialect T0> （ T1> ） T2> ¶ T3>

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

translate_connect_args （ names = []，** kw ） T5>

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

返回此URL（主机，数据库，用户名，密码，端口 ）作为一个普通的字典。属性名称默认用作键。从最终字典中省略未设置或错误的属性。

参数：	** kw ¶ - 可选的url属性的替代键名称。 名称 ¶ - 弃用。与基于关键字的备用名称的用途相同，但将名称与原始位置相关联。

汇集¶ T0>

当connect()或execute()方法被调用时，Engine会向连接池询问连接。默认连接池QueuePool将根据需要打开到数据库的连接。As concurrent statements are executed, QueuePool will grow its pool of connections to a default size of five, and will allow a default “overflow” of ten. 由于Engine实质上是连接池的“主基地”，因此应该为应用程序中建立的每个数据库保留一个Engine，而不是创建一个新的为每个连接。

有关连接池的更多信息，请参阅Connection Pooling。

自定义DBAPI连接()参数¶

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

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

如果SQLAlchemy的数据库连接器知道特定的查询参数，它可能会将其类型从字符串转换为适当的类型。

create_engine()还有一个参数connect_args，它是一个将传递给connect()的附加字典。这可以在需要字符串以外的参数时使用，并且SQLAlchemy的数据库连接器对该参数没有类型转换逻辑：

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的标准logging模块用于通过SQLAlchemy实现信息和调试日志输出。这允许SQLAlchemy的日志记录与其他应用程序和库以标准方式集成。The echo and echo_pool flags that are present on create_engine(), as well as the echo_uow flag used on Session, all interact with regular loggers.

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

• sqlalchemy.engine - 控制SQL回显。对于SQL查询输出设置为logging.INFO，对于查询+结果集输出设置为logging.DEBUG。
• sqlalchemy.dialects - 控制SQL方言的自定义日志记录。有关详细信息，请参阅单个方言的文档。
• sqlalchemy.pool - 控制连接池日志记录。设置为logging.INFO或更低以记录连接池检出/检入。
• sqlalchemy.orm - 控制各种ORM功能的记录。设置为logging.INFO以获取有关映射器配置的信息。

例如，要使用Python日志记录来记录SQL查询，而不是echo=True标志：

import logging

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

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

echo标志作为create_engine()等关键字参数以及Engine上的echo属性存在，当设置为True时，将首先尝试确保启用日志记录。不幸的是，logging模块没有提供确定输出是否已经配置的方法（注意我们指的是是否设置了日志配置，而不仅仅是设置日志级别）。因此，任何echo=True标志都将导致使用sys.stdout作为目标对logging.basicConfig()的调用。它还使用级别名称，时间戳和记录器名称设置默认格式。请注意，此配置具有将配置为到任何现有记录器配置的作用。Therefore, when using Python logging, ensure all echo flags are set to False at all times, to avoid getting duplicate log lines.

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