版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

引擎配置

引擎是任何SQLAlchemy应用程序的基础。它是实际数据库及其DBAPI的“主基”,通过连接池和Dialect传递给SQLAlchemy应用程序,它描述了如何与特定种类的数据库/ DBAPI组合。

一般结构如下:

http://sqlalchemy.readthedocs.io/en/latest/_images/sqla_engine_arch.png

上面,Engine引用了DialectPool,它们共同解释了DBAPI的模块功能以及数据库的行为。

只用一个调用就可以创建引擎,create_engine()

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

The above engine creates a Dialect object tailored towards PostgreSQL, as well as a Pool object which will establish a DBAPI connection at localhost:5432 when a connection request is first received.Note that the Engine and its underlying Pool do not establish the first actual DBAPI connection until the Engine.connect() method is called, or an operation which is dependent on this method such as Engine.execute() is invoked. In this way, Engine and Pool can be said to have a lazy initialization behavior.

一旦创建了Engine,可以直接用于与数据库进行交互,也可以将其传递给Session对象以使用ORM。本节将介绍配置Engine的详细信息。接下来的部分Working with Engines and Connections将详细介绍Engine的使用API​​和类似的API,通常用于非ORM应用程序。

支持的数据库

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方言的标识名,诸如sqlitemysqlpostgresqloracle ,或mssqldrivername是用于使用全部小写字母连接到数据库的DBAPI的名称。如果未指定,则将导入“默认”DBAPI(如果可用) - 此默认值通常是该后端可用的最广泛的驱动程序。

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

的PostgreSQL ¶ T0>

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

More notes on connecting to Postgresql at PostgreSQL.

MySQL的¶ T0>

MySQL方言使用mysql-python作为默认的DBAPI。有许多可用的MySQL DBAPI,包括MySQL连接器-python和OurSQL:

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

有关在MySQL连接到MySQL的更多注意事项。

甲骨文¶ T0>

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

有关在Microsoft SQL Server连接到SQL Server的更多注意事项。

SQLite的¶ T0>

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的更多注意事项。

其他¶ T0>

参见Dialects,这是所有其他方言文档的顶层页面。

引擎创建API

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

创建一个新的Engine实例。

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

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

其他的关键字参数可以跟随它,在结果Engine及其底层的DialectPool结构上建立各种选项:

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

The string form of the URL is dialect[+driver]://user:password@host/dbname[?key=value..], where dialect is a database name such as mysql, oracle, postgresql, etc., and driver the name of a DBAPI, such as psycopg2, pyodbc, cx_oracle, etc. 或者,该URL可以是URL的实例。

**kwargs takes a wide variety of options which are routed towards their appropriate components. 参数可能特定于EngineDialect以及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.

参数:
  • 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. 可以随时修改Engineecho属性以打开和关闭日志记录。如果设置为字符串"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-8This 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属性检索到的字符串列名称。

    当使用Python 3时,DBAPI需要支持上述所有值作为Python unicode对象,这在Python 3中被称为str在Python 2中,DBAPI根本不指定unicode行为,所以SQLAlchemy必须在每个DBAPI基础上为每个上述值做出决定 - 实现在行为上完全不一致。

  • execution_options – Dictionary execution options which will be applied to all connections. 请参阅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的基础上设置,使用Connection.execution_options.isolation_level功能。

  • 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. 如果是非None,则此池将直接用作引擎的基础连接池,绕过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以及SingletonThreadPoolQueuePoolpool_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表示连接将在一小时后回收。请注意,如果在连接上没有检测到任何活动八个小时(尽管这可以通过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' -

    选择备用的引擎实现。目前可用的有:

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

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

字典通常是从配置文件生成的。

The keys of interest to engine_from_config() should be prefixed, e.g. sqlalchemy.url, sqlalchemy.echo, etc. 'prefix'参数表示要搜索的前缀。Each matching key (after the prefix is stripped) is treated as though it were the corresponding keyword argument to a create_engine() call.

唯一所需的密钥是(假定默认前缀)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. 关键字参数应该以not为前缀。
sqlalchemy.engine.url。 T0> make_url T1> ( T2> name_or_url T3> ) T4>

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

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

class sqlalchemy.engine.url。 URL drivername=无密码=无主机=无端口=无数据库=无query = None

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

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

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

参数:
  • drivername – the name of the database backend. 该名称将对应于sqlalchemy /数据库中的模块或第三方插件。
  • 用户名 - 用户名。
  • 密码 - 数据库密码。
  • tt> host - 主机的名称。
  • 端口 - 端口号。
  • 数据库 - 数据库名称。
  • 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 tt> names = [** kw T5>

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

返回此网址的属性(host数据库用户名密码端口 )作为一个普通的字典。属性名称默认用作键。从最终字典中省略了未设置或错误的属性。

参数:
  • ** 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,而不是创建一个新的为每个连接。

注意

QueuePool is not used by default for SQLite engines. 有关SQLite连接池用法的详细信息,请参阅SQLite

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

自定义DBAPI connect()参数

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

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

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

create_engine() also takes an argument connect_args which is an additional dictionary that will be passed to 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执行的日志都存在于logging.getLogger('sqlalchemy')所使用的sqlalchemy命名空间下。当日志记录被配置时(例如,通过logging.basicConfig()),可以打开的SA记录器的通用命名空间如下:

  • sqlalchemy.engine - 控制SQL回显。为SQL查询输出设置为logging.INFO,为查询+结果集输出设置为logging.DEBUG
  • sqlalchemy.dialects - controls custom logging for SQL dialects. 有关详细信息,请参阅单个方言的文档。
  • sqlalchemy.pool - 控制连接池日志记录。设置为logging.INFO或更低以记录连接池检出/检入。
  • sqlalchemy.orm - controls logging of various ORM functions. 设置为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.

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

注意

SQLAlchemy Engine通过在当前日志记录级别被检测为logging.INFOlogging.DEBUG时仅发出日志语句来节省Python函数调用开销。它只在从连接池购买新连接时才检查此级别。因此,在更改已经运行的应用程序的日志记录配置时,任何当前处于活动状态的Connection,或者更常见的是在事务中处于活动状态的Session对象都不会记录SQL根据新的配置直到获得新的Connection(在Session的情况下,这是在当前事务结束并且新的开始之后)。