连接池

连接池是一种标准技术，用于在内存中维护长时间运行的连接，以便有效地重用，并为应用程序可能同时使用的连接总数提供管理。

特别是对于服务器端Web应用程序，连接池是在内存中维护活动数据库连接“池”的标准方法，这些活动数据库连接在请求之间重复使用。

sqlAlchemy包括几个连接池实现，这些实现与 Engine . 它们还可以直接用于希望向其他普通DBAPI方法添加池的应用程序。

连接池配置

这个 Engine 返回的 create_engine() 在大多数情况下，函数具有 QueuePool 集成，预先配置了合理的池默认值。如果您阅读本节只是为了学习如何启用池-恭喜！你已经做完了。

最常见 QueuePool 优化参数可以直接传递到 create_engine() 作为关键字参数： pool_size ， max_overflow ， pool_recycle 和 pool_timeout . 例如：：

engine = create_engine('postgresql://me@localhost/mydb',
                       pool_size=20, max_overflow=0)

在sqlite的情况下， SingletonThreadPool 或 NullPool 被方言选择以提供与sqlite线程和锁定模型的更大兼容性，并为sqlite“内存”数据库提供合理的默认行为，这些数据库将其整个数据集维护在单个连接的范围内。

所有的sqlAlchemy池实现都有一个共同点，即它们都没有“预创建”连接——所有的实现都要等到第一次使用后才能创建连接。此时，如果没有对更多连接发出额外的并发签出请求，则不会创建额外的连接。这就是为什么它对 create_engine() 默认为使用 QueuePool 大小为5，不考虑应用程序是否真的需要排队5个连接-只有当应用程序同时使用5个连接时，池才会增长到该大小，在这种情况下，使用小池是完全合适的默认行为。

切换池实现

使用不同类型游泳池的常用方法 create_engine() 是使用 poolclass 争论。此参数接受从 sqlalchemy.pool 模块，并为您处理构建池的详细信息。常用选项包括指定 QueuePool SQLite：：

from sqlalchemy.pool import QueuePool
engine = create_engine('sqlite:///file.db', poolclass=QueuePool)

禁用池使用 NullPool ：：

from sqlalchemy.pool import NullPool
engine = create_engine(
          'postgresql+psycopg2://scott:tiger@localhost/test',
          poolclass=NullPool)

使用自定义连接函数

见剖面图 自定义DBAPI connect（）参数/on connect例程 对于各种连接自定义例程的详细说明。

建造游泳池

使用A Pool 就其本身而言， creator 函数是唯一必需的参数，它首先传递，然后再传递任何其他选项：

import sqlalchemy.pool as pool
import psycopg2

def getconn():
    c = psycopg2.connect(user='ed', host='127.0.0.1', dbname='test')
    return c

mypool = pool.QueuePool(getconn, max_overflow=10, pool_size=5)

然后，可以使用以下命令从池中获取DBAPI连接 Pool.connect() 功能。此方法的返回值是包含在透明代理中的DBAPI连接：：

# get a connection
conn = mypool.connect()

# use it
cursor_obj = conn.cursor()
cursor_obj.execute("select foo")

透明代理的目的是截取 close() 调用，使其返回池，而不是关闭DBAPI连接：

# "close" the connection.  Returns
# it to the pool.
conn.close()

代理还会在垃圾收集时将其包含的DBAPI连接返回到池，尽管在Python中不能确定这是否会立即发生(尽管这在cPython中很常见)。但是，不建议使用这种用法，特别是异步DBAPI驱动程序不支持这种用法。

返回时重置

该池还包括a“返回时重置”功能，该功能将调用 rollback() 连接返回到池时DBAPI连接的方法。这是为了删除连接上的任何现有事务，不仅确保下次使用时不会保留任何现有状态，而且还可以释放表锁和行锁，以及删除任何隔离的数据快照。这 rollback() 在大多数情况下都会发生，即使在使用 Engine 对象，除非在以下情况下 Connection 可以保证一个 rollback() 已在连接返回到池之前立即调用。

对于大多数DBAPI，调用 rollback() 非常便宜，如果DBAPI已经完成了事务，则该方法应该是无操作的。但是，对于出现性能问题的DBAPI， rollback() 即使连接上没有状态，也可以使用 reset_on_return 选项： Pool 。在以下情况下，可以安全地禁用该行为：

• 如果数据库根本不支持事务，例如将MySQL与MyISAM引擎一起使用，或者DBAPI仅在自动提交模式下使用，则可以禁用该行为。

• 如果池本身在签入后不保持连接，例如在使用 NullPool ，则可以禁用该行为。

• 否则，必须确保：

  • 该应用程序确保所有 Connection 使用上下文管理器显式关闭对象(即 with 挡路)或 try/finally 挡路造型

  • 在显式关闭连接之前，决不允许对其进行垃圾回收。

  • DBAPI连接本身，例如 connection.connection 不直接使用，或者应用程序确保 .rollback() 在将其释放回连接池之前，在此连接上调用。

“返回时重置”步骤可以使用 logging.DEBUG 日志级别以及 sqlalchemy.pool 记录器，或通过设置 echo_pool='debug' 使用 create_engine() 。

池事件

连接池支持一个事件接口，允许钩子在第一次连接、每个新连接以及连接的签出和签入时执行。见 PoolEvents 有关详细信息。

处理断开连接

连接池能够刷新单个连接及其整个连接集，将以前的池连接设置为“无效”。一个常见的用例是，当数据库服务器重新启动时，允许连接池正常恢复，并且所有以前建立的连接都不再正常工作。有两种方法可以解决这个问题。

断开操作-悲观

悲观的方法是在每个连接池签出开始时对SQL连接发出测试语句，以测试数据库连接是否仍然可行。通常，这是一个类似“select 1”的简单语句，但也可以使用一些DBAPI特定的方法来测试连接的活跃性。

这种方法给连接签出过程增加了一点开销，但在其他方面，它是完全消除由于过时的池连接导致的数据库错误的最简单和可靠的方法。调用应用程序不需要关心如何组织操作，以便能够从池中签出的过时连接中恢复。

需要注意的是，预ping方法 不适用于在事务或其他SQL操作中丢弃的连接 . 如果在事务处理过程中数据库不可用，则事务将丢失并引发数据库错误。而 Connection 当连接断开时，会再次出现连接断开连接的情况。如果引擎是使用DBAPI级别的自动提交连接配置的，如中所述 设置事务隔离级别，包括DBAPI Autocommit ，一个连接 may 在操作过程中使用事件透明地重新连接。参见章节 如何自动“重试”语句执行？ 举个例子。

通过使用 Pool.pre_ping 参数，可从 create_engine() 通过 create_engine.pool_pre_ping 论点：

engine = create_engine("mysql+pymysql://user:pw@host/db", pool_pre_ping=True)

每次从池中签出连接时，“pre-ping”功能通常会发出相当于“select 1”的SQL；如果出现检测为“disconnect”情况的错误，则该连接将立即被回收，并且所有其他比当前时间早的池连接都将失效，以便下次它们处于丢弃后，也会在使用前回收利用。

如果“预Ping”运行时数据库仍然不可用，则初始连接将失败，并且连接失败的错误将正常传播。在数据库可用于连接但无法响应“ping”的罕见情况下，“pre-ping”将在放弃前尝试最多三次，传播上次收到的数据库错误。

注解

“pre-ping”发出的“select 1”在连接池/方言的范围内调用，使用非常短的代码路径将python延迟降至最低。因此，本声明是 未记录在SQL Echo输出中 ，并且不会显示在SQLAlchemy的引擎日志中。

1.2 新版功能: 增加了“预Ping”功能 Pool 班级。

自定义/传统悲观ping

之前 create_engine.pool_pre_ping 添加了“预Ping”方法，历史上使用 ConnectionEvents.engine_connect() 引擎事件。最常见的方法如下，以供参考，以防应用程序已经在使用此类方法，或者需要特殊行为：

from sqlalchemy import exc
from sqlalchemy import event
from sqlalchemy import select

some_engine = create_engine(...)

@event.listens_for(some_engine, "engine_connect")
def ping_connection(connection, branch):
    if branch:
        # "branch" refers to a sub-connection of a connection,
        # we don't want to bother pinging on these.
        return

    # turn off "close with result".  This flag is only used with
    # "connectionless" execution, otherwise will be False in any case
    save_should_close_with_result = connection.should_close_with_result
    connection.should_close_with_result = False

    try:
        # run a SELECT 1.   use a core select() so that
        # the SELECT of a scalar value without a table is
        # appropriately formatted for the backend
        connection.scalar(select(1))
    except exc.DBAPIError as err:
        # catch SQLAlchemy's DBAPIError, which is a wrapper
        # for the DBAPI's exception.  It includes a .connection_invalidated
        # attribute which specifies if this connection is a "disconnect"
        # condition, which is based on inspection of the original exception
        # by the dialect in use.
        if err.connection_invalidated:
            # run the same SELECT again - the connection will re-validate
            # itself and establish a new connection.  The disconnect detection
            # here also causes the whole connection pool to be invalidated
            # so that all stale connections are discarded.
            connection.scalar(select(1))
        else:
            raise
    finally:
        # restore "close with result"
        connection.should_close_with_result = save_should_close_with_result

上面的方法的优点是，我们正在使用sqlAlchemy的工具来检测那些已知表示“断开”情况的dbapi异常，以及 Engine 对象在发生此情况时正确使当前连接池无效并允许当前连接池 Connection 重新验证新的DBAPI连接。

断开操作-乐观

当不使用悲观处理时，以及当数据库在事务中的连接使用期间关闭和/或重新启动时，处理陈旧/关闭连接的另一种方法是让SQLAlchemy在发生连接时处理断开连接，此时池中的所有连接都将失效，Me假定它们已过时，并将在下次签出时刷新。此行为假定 Pool 与 Engine . 这个 Engine 具有可以检测断开连接事件并自动刷新池的逻辑。

当 Connection 尝试使用DBAPI连接，并引发与“disconnect”事件对应的异常，该连接将失效。这个 Connection 然后调用 Pool.recreate() 方法，有效地使当前未签出的所有连接失效，以便下次签出时用新连接替换这些连接。下面的代码示例说明了此流程：

from sqlalchemy import create_engine, exc
e = create_engine(...)
c = e.connect()

try:
    # suppose the database has been restarted.
    c.execute(text("SELECT * FROM table"))
    c.close()
except exc.DBAPIError, e:
    # an exception is raised, Connection is invalidated.
    if e.connection_invalidated:
        print("Connection was invalidated!")

# after the invalidate event, a new connection
# starts with a new Pool
c = e.connect()
c.execute(text("SELECT * FROM table"))

上面的示例说明刷新池不需要特殊干预，在检测到断开事件后，池将正常继续。但是，在发生数据库不可用事件时，每个正在使用的连接都会引发一个数据库异常。在使用ORM会话的典型Web应用程序中，上述条件将对应于一个失败并出现500个错误的单个请求，然后Web应用程序将继续正常运行。因此，这种方法是“乐观的”，因为不期望频繁的数据库重启。

设置池回收

另一个可以增强“乐观”方法的设置是设置池回收参数。此参数防止池使用已超过某个时间段的特定连接，并适用于数据库后端，如mysql，该数据库后端在特定时间段后自动关闭已过时的连接：

from sqlalchemy import create_engine
e = create_engine("mysql://scott:tiger@localhost/test", pool_recycle=3600)

在上面，任何打开超过一小时的DBAPI连接在下次签出时都将失效并被替换。注意无效声明 only 在签出期间发生-不在处于签出状态的任何连接上发生。 pool_recycle 是的函数 Pool 本身，独立于 Engine 正在使用中。

关于无效的更多信息

这个 Pool 提供“连接无效化”服务，该服务允许连接的显式无效化以及响应确定的导致连接不可用的条件的自动无效化。

“无效”是指从池中删除并丢弃特定DBAPI连接。这个 .close() 如果不清楚连接本身是否可能未关闭，则在此连接上调用方法，但是如果此方法失败，则会记录异常，但操作仍在继续。

当使用 Engine , the Connection.invalidate() 方法是显式失效的常见入口点。DBAPI连接可能失效的其他条件包括：

• DBAPI异常，如 OperationalError ，在类似 connection.execute() 被调用，被检测为指示所谓的“断开”状态。由于python dbapi不提供用于确定异常性质的标准系统，因此所有的sqlAlchemy方言都包括一个名为 is_disconnect() 它将检查异常对象的内容，包括字符串消息及其包含的任何潜在错误代码，以确定此异常是否指示连接不再可用。如果是这样的话， _ConnectionFairy.invalidate() 方法，然后放弃DBAPI连接。

• 当连接返回池并调用 connection.rollback() 或 connection.commit() 方法根据池的“返回时重置”行为指定，引发异常。最后一次尝试呼叫 .close() 将在连接上进行，然后将其丢弃。

• 当侦听器实现 PoolEvents.checkout() 扬起 DisconnectionError 异常，指示连接将不可用，需要进行新的连接尝试。

发生的所有无效将调用 PoolEvents.invalidate() 事件。

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

这个 QueuePool 类具有一个名为 QueuePool.use_lifo ，也可以从 create_engine() 通过旗帜 create_engine.pool_use_lifo . 将此标志设置为 True 使池的“队列”行为改为“堆栈”行为，例如，返回池的最后一个连接是在下一个请求中使用的第一个连接。与池中长期存在的先进先出（first-in-first-out）行为不同，后进先出（first-in-first-out）会产生一种循环循环效应，即串联使用池中的每个连接，后进先出（lifo）模式允许多余的连接在池中保持空闲，从而允许服务器端超时方案关闭这些连接。FIFO和LIFO之间的区别主要在于池是否需要保持一组完整的连接，即使在空闲期间也可以保持连接：

engine = create_engine(
    "postgreql://", pool_use_lifo=True, pool_pre_ping=True)

上面，我们还利用了 create_engine.pool_pre_ping 标记以使从服务器端关闭的连接由连接池正常处理并替换为新连接。

请注意，该标志仅适用于 QueuePool 使用。

1.3 新版功能.

参见

处理断开连接

将连接池用于多处理或os.fork操作系统()

使用连接池和使用 Engine 创建通过 create_engine() ，集合连接 不与分叉进程共享 . TCP连接表示为文件描述符，通常跨进程边界工作，这意味着这将导致代表两个或更多完全独立的Python解释器状态并发访问文件描述符。

根据驱动程序和操作系统的具体情况，这里出现的问题从非工作连接到多个进程并发使用的套接字连接，导致消息传递中断（后一种情况通常最常见）。

圣卢西亚 Engine 对象引用现有数据库连接的连接池。因此，当将此对象复制到子进程时，目标是确保不传递任何数据库连接。对此，有三种一般方法：

1. 禁用池使用 NullPool . 这是最简单的一次系统，可以防止 Engine 禁止多次使用任何连接：

   from sqlalchemy.pool import NullPool
   engine = create_engine("mysql://user:pass@host/dbname", poolclass=NullPool)

2. 呼叫 Engine.dispose() 在任何给定的 Engine 一旦进入新的过程。在Python多处理中，构造 multiprocessing.Pool 包括“初始值设定项”挂钩，该挂钩是可以执行此操作的位置；否则在其中的顶部 os.fork() 或者在哪里 Process 对象开始子分叉，对 Engine.dispose() 将确保冲洗所有剩余的连接。 这是推荐的方法 ：：

   engine = create_engine("mysql://user:pass@host/dbname")
   
   def run_in_process():
       # process starts.  ensure engine.dispose() is called just once
       # at the beginning
       engine.dispose()
   
       with engine.connect() as conn:
           conn.execute(text("..."))
   
   p = Process(target=run_in_process)
   p.start()

3. 事件处理程序可以应用于连接池，该连接池测试跨进程边界共享的连接，并使其无效。这种方法， 与上面提到的dispose（）显式调用结合使用时 ，应涵盖所有情况：

   from sqlalchemy import event
   from sqlalchemy import exc
   import os
   
   engine = create_engine("...")
   
   @event.listens_for(engine, "connect")
   def connect(dbapi_connection, connection_record):
       connection_record.info['pid'] = os.getpid()
   
   @event.listens_for(engine, "checkout")
   def checkout(dbapi_connection, connection_record, connection_proxy):
       pid = os.getpid()
       if connection_record.info['pid'] != pid:
           connection_record.dbapi_connection = connection_proxy.dbapi_connection = None
           raise exc.DisconnectionError(
                   "Connection record belongs to pid %s, "
                   "attempting to check out in pid %s" %
                   (connection_record.info['pid'], pid)
           )

   上面，我们使用类似于 断开操作-悲观 若要将源自不同父进程的DBAPI连接视为“无效”连接，请强制池回收连接记录以建立新连接。

   使用上述配方时， ensure the dispose approach from #2 is also used ，就好像在发生fork时父进程中的连接池耗尽一样，一个空的池将被复制到子进程中，然后子进程将挂起，因为它没有连接。

上述策略将适应 Engine 在进程之间共享。但是，对于活动事务的情况 Session 或 Connection 由于是共享的，因此没有自动修复；应用程序需要确保新的子进程只启动新的 Connection 对象和事务以及ORM Session 物体。对于一个 Session 对象，从技术上讲，仅当会话当前是事务绑定的，而单个 Session 在任何情况下都要保持在单个调用堆栈中（例如，不是全局对象，不在进程或线程之间共享）。

API文档-可用池实现

class sqlalchemy.pool.Pool(creator, recycle=- 1, echo=None, logging_name=None, reset_on_return=True, events=None, dialect=None, pre_ping=False, _dispatch=None)¶

连接池的抽象基类。

类签名

class sqlalchemy.pool.Pool (sqlalchemy.log.Identified)

method sqlalchemy.pool.Pool.__init__(creator, recycle=- 1, echo=None, logging_name=None, reset_on_return=True, events=None, dialect=None, pre_ping=False, _dispatch=None)¶

建造一个游泳池。

参数

• creator¶ -- 返回DB-API连接对象的可调用函数。将使用参数调用函数。

• recycle¶ -- 如果设置为-1以外的值，则连接回收之间的秒数，这意味着在签出时，如果超时，则连接将关闭并替换为新打开的连接。默认值为-1。

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

• echo¶ -- 如果为true，则连接池将记录信息输出，例如连接失效以及连接回收到默认日志处理程序（默认为 sys.stdout 用于输出。如果设置为字符串 "debug" 日志记录将包括池签出和签入。这个 Pool.echo 参数也可以从 create_engine() 通过使用 create_engine.echo_pool 参数。…参阅： 配置日志记录 -有关如何配置日志的详细信息。

• reset_on_return¶ -- 确定在连接返回池时要采取的步骤，否则这些连接不会由 Connection 。RESET_ON_RETURN可以具有以下任意值： * "rollback" - call rollback() on the connection, to release locks and transaction resources. This is the default value. The vast majority of use cases should leave this value set. * True -与‘回滚’相同，这里是为了向后兼容。 * "commit" - call commit() on the connection, to release locks and transaction resources. A commit here may be desirable for databases that cache query plans if a commit is emitted, such as Microsoft SQL Server. However, this value is more dangerous than 'rollback' because any data changes present on the transaction are committed unconditionally. * None -不要在连接上做任何事情。仅当数据库/DBAPI始终在纯“自动提交”模式下工作，或者应用程序使用 Engine 具有一致的连接模式。请参阅部分 返回时重置 了解更多详细信息。* False -与无相同，这是为了向后兼容。。。另请参阅：： 返回时重置

• events¶ -- 两个元组的列表，每种形式 (callable, target) 将传递给 listen() 施工时。此处提供，以便事件侦听器可以通过 create_engine() 在应用方言级别的侦听器之前。

• dialect¶ -- 一 Dialect 它将处理在DBAPI连接上调用rollback（）、close（）或commit（）的任务。如果省略，则使用内置的“存根”方言。利用 create_engine() 不应使用此参数，因为它由引擎创建策略处理。…添加的版本：1.1- dialect 现在是的公共参数 Pool .

• pre_ping¶ -- 如果为true，则池将在签出时在连接上发出“ping”（通常为“select 1”，但特定于方言），以测试连接是否处于活动状态。如果没有，连接将被透明地重新连接，并且一旦成功，在该时间戳之前建立的所有其他池连接都将失效。要求同时传递方言以解释断开连接错误。…添加的版本：1.2

method sqlalchemy.pool.Pool.connect()¶

从池返回DBAPI连接。

对连接进行检测，以便 close() 方法，连接将返回到池。

method sqlalchemy.pool.Pool.dispose()¶

处理这个池子。

此方法使签出的连接保持打开状态的可能性，因为它只影响池中空闲的连接。

参见

Pool.recreate()

method sqlalchemy.pool.Pool.recreate()¶

返回一个新的 Pool ，属于与此类相同的类，并且配置了相同的创建参数。

此方法与 dispose() 关闭整个 Pool 在它的位置上创建一个新的。

class sqlalchemy.pool.QueuePool(creator, pool_size=5, max_overflow=10, timeout=30.0, use_lifo=False, **kw)¶

A Pool 这就限制了开放连接的数量。

QueuePool 默认的池实现是否用于所有 Engine 对象，除非使用sqlite方言。

类签名

class sqlalchemy.pool.QueuePool (sqlalchemy.pool.base.Pool)

method sqlalchemy.pool.QueuePool.__init__(creator, pool_size=5, max_overflow=10, timeout=30.0, use_lifo=False, **kw)¶

构建队列池。

参数

• creator¶ -- 返回db-api连接对象的可调用函数，与 Pool.creator .

• pool_size¶ -- 要维护的池的大小，默认为5。这是将永久保留在池中的最大连接数。请注意，池开始时没有连接；一旦请求了这个数量的连接，那么连接的数量将保持不变。 pool_size 可以设置为0表示没有大小限制；要禁用池，请使用 NullPool 相反。

• max_overflow¶ -- 池的最大溢出大小。当签出的连接数达到池大小中设置的大小时，其他连接将返回到此限制。当这些额外的连接返回池时，它们将被断开并丢弃。随后，池允许的同时连接总数为池大小+ max_overflow ，池允许的“休眠”连接总数为池大小。 max_overflow 可以设置为-1以指示没有溢出限制；不会对并发连接的总数设置限制。默认值为10。

• timeout¶ -- 在放弃返回连接之前等待的秒数。默认为30.0。这可以是一个float，但是受到Python时间函数的限制，在几十毫秒内可能不可靠。

• use_lifo¶ --

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

  1.3 新版功能.

  参见

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

  处理断开连接

• **kw¶ -- 其他关键字参数包括 Pool.recycle ， Pool.echo ， Pool.reset_on_return 其他人被传给 Pool 建造师。

method sqlalchemy.pool.QueuePool.connect()¶

inherited from the Pool.connect() method of Pool

从池返回DBAPI连接。

对连接进行检测，以便 close() 方法，连接将返回到池。

class sqlalchemy.pool.SingletonThreadPool(creator, pool_size=5, **kw)¶

每个线程保持一个连接的池。

为每个线程维护一个连接，不要将连接移动到创建它的线程以外的其他线程。

警告

这个 SingletonThreadPool 将呼叫 .close() 在存在于超出大小设置的任意连接上 pool_size ，例如，如果更独特 线程标识 比什么 pool_size 使用状态。此清理是不确定的，对链接到这些线程标识的连接当前是否正在使用不敏感。

SingletonThreadPool 可能在将来的版本中得到改进，但是在当前状态下，它通常只用于使用sqlite的测试场景。 :memory: 数据库，不建议用于生产。

选项与 Pool 以及：

参数

pool_size¶ -- 一次维护连接的线程数。默认值为5。

SingletonThreadPool 当使用基于内存的数据库时，由sqlite方言自动使用。见 SQLite .

类签名

class sqlalchemy.pool.SingletonThreadPool (sqlalchemy.pool.base.Pool)

method sqlalchemy.pool.SingletonThreadPool.__init__(creator, pool_size=5, **kw)¶

建造一个游泳池。

参数

• creator¶ -- 返回DB-API连接对象的可调用函数。将使用参数调用函数。

• recycle¶ -- 如果设置为-1以外的值，则连接回收之间的秒数，这意味着在签出时，如果超时，则连接将关闭并替换为新打开的连接。默认值为-1。

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

• echo¶ -- 如果为true，则连接池将记录信息输出，例如连接失效以及连接回收到默认日志处理程序（默认为 sys.stdout 用于输出。如果设置为字符串 "debug" 日志记录将包括池签出和签入。这个 Pool.echo 参数也可以从 create_engine() 通过使用 create_engine.echo_pool 参数。…参阅： 配置日志记录 -有关如何配置日志的详细信息。

• reset_on_return¶ -- 确定在连接返回池时要采取的步骤，否则这些连接不会由 Connection 。RESET_ON_RETURN可以具有以下任意值： * "rollback" - call rollback() on the connection, to release locks and transaction resources. This is the default value. The vast majority of use cases should leave this value set. * True -与‘回滚’相同，这里是为了向后兼容。 * "commit" - call commit() on the connection, to release locks and transaction resources. A commit here may be desirable for databases that cache query plans if a commit is emitted, such as Microsoft SQL Server. However, this value is more dangerous than 'rollback' because any data changes present on the transaction are committed unconditionally. * None -不要在连接上做任何事情。仅当数据库/DBAPI始终在纯“自动提交”模式下工作，或者应用程序使用 Engine 具有一致的连接模式。请参阅部分 返回时重置 了解更多详细信息。* False -与无相同，这是为了向后兼容。。。另请参阅：： 返回时重置

• events¶ -- 两个元组的列表，每种形式 (callable, target) 将传递给 listen() 施工时。此处提供，以便事件侦听器可以通过 create_engine() 在应用方言级别的侦听器之前。

• dialect¶ -- 一 Dialect 它将处理在DBAPI连接上调用rollback（）、close（）或commit（）的任务。如果省略，则使用内置的“存根”方言。利用 create_engine() 不应使用此参数，因为它由引擎创建策略处理。…添加的版本：1.1- dialect 现在是的公共参数 Pool .

• pre_ping¶ -- 如果为true，则池将在签出时在连接上发出“ping”（通常为“select 1”，但特定于方言），以测试连接是否处于活动状态。如果没有，连接将被透明地重新连接，并且一旦成功，在该时间戳之前建立的所有其他池连接都将失效。要求同时传递方言以解释断开连接错误。…添加的版本：1.2

class sqlalchemy.pool.AssertionPool(*args, **kw)¶

A Pool 在任何给定时间最多允许一个签出连接。

如果一次签出多个连接，这将引发异常。对于调试使用的连接数超过预期的代码很有用。

类签名

class sqlalchemy.pool.AssertionPool (sqlalchemy.pool.base.Pool)

class sqlalchemy.pool.NullPool(creator, recycle=- 1, echo=None, logging_name=None, reset_on_return=True, events=None, dialect=None, pre_ping=False, _dispatch=None)¶

不池连接的池。

相反，它按照打开/关闭每个连接的方式打开和关闭底层的DB-API连接。

重新连接相关功能，如 recycle 此池实现不支持连接失效，因为没有持续保持任何连接。

类签名

class sqlalchemy.pool.NullPool (sqlalchemy.pool.base.Pool)

class sqlalchemy.pool.StaticPool(creator, recycle=- 1, echo=None, logging_name=None, reset_on_return=True, events=None, dialect=None, pre_ping=False, _dispatch=None)¶

只有一个连接的池，用于所有请求。

与重新连接相关的功能，如 recycle 和连接失效(也用于支持自动重新连接)目前只有部分支持，可能不会产生好的结果。

类签名

class sqlalchemy.pool.StaticPool (sqlalchemy.pool.base.Pool)

class sqlalchemy.pool._ConnectionFairy(dbapi_connection, connection_record, echo)¶

代理DBAPI连接并提供取消引用支持的返回。

这是由 Pool 实现，以向由它提供的DBAPI连接提供上下文管理 Pool .

“仙女”这个名字的灵感来源于 _ConnectionFairy 对象的寿命是短暂的，因为它只持续从池中签出的特定DBAPI连接的长度，而且作为透明代理，它大部分是不可见的。

参见

_ConnectionRecord

attribute sqlalchemy.pool._ConnectionFairy._connection_record = None¶

参考 _ConnectionRecord 与DBAPI连接关联的对象。

这是一个内部访问器，可能会更改。

attribute sqlalchemy.pool._ConnectionFairy.connection¶

的别名 _ConnectionFairy.dbapi_connection 。

此别名已弃用，请使用新名称。

1.4.24 版后已移除.

method sqlalchemy.pool._ConnectionFairy.cursor(*args, **kwargs)¶

为基础连接返回新的DBAPI指针。

此方法是 connection.cursor() DAPI方法。

attribute sqlalchemy.pool._ConnectionFairy.dbapi_connection = None¶

对被跟踪的实际DBAPI连接的引用。

1.4.24 新版功能.

参见

_ConnectionFairy.driver_connection

_ConnectionRecord.dbapi_connection

使用引擎时，如何获得原始DBAPI连接？

method sqlalchemy.pool._ConnectionFairy.detach()¶

将此连接与其池分离。

这意味着当连接关闭时，连接将不再返回池，而是实际关闭。包含的connectionrecord与db-api连接分开，下次使用时将创建新连接。

请注意，分离后可能会违反池实现所施加的任何总体连接限制约束，因为分离的连接将从池的知识和控制中移除。

attribute sqlalchemy.pool._ConnectionFairy.driver_connection¶

驱动程序在连接后返回的连接对象。

1.4.24 新版功能.

参见

_ConnectionFairy.dbapi_connection

_ConnectionRecord.driver_connection

使用引擎时，如何获得原始DBAPI连接？

attribute sqlalchemy.pool._ConnectionFairy.info¶

与此引用的基础DBAPI连接关联的信息字典 ConnectionFairy ，允许用户定义的数据与连接关联。

这里的数据将与DBAPI连接一起使用，包括在它返回到连接池并在随后的实例中再次使用之后。 _ConnectionFairy . 它与共享 _ConnectionRecord.info 和 Connection.info 访问器。

当连接本身被丢弃时，与特定DBAPI连接关联的字典将被丢弃。

method sqlalchemy.pool._ConnectionFairy.invalidate(e=None, soft=False)¶

将此连接标记为无效。

此方法可以直接调用，也可以作为 Connection.invalidate() 方法。当被调用时，DBAPI连接立即关闭，并从池的进一步使用中丢弃。无效宣告机制通过 _ConnectionRecord.invalidate() 内部方法。

参数

• e¶ -- 指示无效原因的异常对象。

• soft¶ -- 如果为true，则连接不会关闭；相反，此连接将在下次签出时回收。…添加的版本：1.0.3

参见

关于无效的更多信息

attribute sqlalchemy.pool._ConnectionFairy.is_valid¶

如果这个返回真 _ConnectionFairy 仍然是指活动的DBAPI连接。

attribute sqlalchemy.pool._ConnectionFairy.record_info¶

与关联的信息字典 _ConnectionRecord container referred to by this :class: .connectionfairy`。

不像 _ConnectionFairy.info 字典，此字典的寿命在连接之间是持久的，这些连接在 _ConnectionRecord .

1.1 新版功能.

class sqlalchemy.pool._ConnectionRecord(pool, connect=True)¶

内部对象，它维护由 Pool .

这个 _ConnectionRecord 对象始终存在于任何特定的DBAPI连接中，无论该DBAPI连接是否已“签出”。这与 _ConnectionFairy 在签出DBAPI连接时，它只是DBAPI连接的公共外观。

A _ConnectionRecord 可能存在的跨度比单个DBAPI连接的跨度长。例如，如果 _ConnectionRecord.invalidate() 方法，与此关联的DBAPI连接 _ConnectionRecord 将被丢弃，但 _ConnectionRecord 可以再次使用，在这种情况下，当 Pool 下一个使用此记录。

这个 _ConnectionRecord 与连接池事件一起传递，包括 PoolEvents.connect() 和 PoolEvents.checkout() 然而 _ConnectionRecord 仍然是一个内部对象，其API和内部可能会更改。

参见

_ConnectionFairy

attribute sqlalchemy.pool._ConnectionRecord.connection¶

的别名 _ConnectionRecord.dbapi_connection 。

此别名已弃用，请使用新名称。

1.4.24 版后已移除.

attribute sqlalchemy.pool._ConnectionRecord.dbapi_connection = None¶

对被跟踪的实际DBAPI连接的引用。

可能是 None 如果这样 _ConnectionRecord 已标记为无效；如果拥有的池对此进行调用，则新的DBAPI连接可能会替换它。 _ConnectionRecord 重新连接。

对于适配的驱动程序，如Asyncio实现，这是一个 AdaptedConnection 它使驱动程序连接适应DBAPI协议。使用 _ConnectionRecord.driver_connection 获取驱动程序返回的连接对象。

1.4.24 新版功能.

attribute sqlalchemy.pool._ConnectionRecord.driver_connection¶

驱动程序在连接后返回的连接对象。

对于支持DBAPI协议的普通同步驱动程序，此对象与引用的对象相同 _ConnectionRecord.dbapi_connection 。

对于适配的驱动程序(如Asyncio驱动程序)，这是驱动程序返回的实际对象 connect 打电话。

作为 _ConnectionRecord.dbapi_connection 可能是因为 None 如果这是 _ConnectionRecord 已被标记为无效。

1.4.24 新版功能.

attribute sqlalchemy.pool._ConnectionRecord.info¶

这个 .info 与DBAPI连接关联的字典。

这本词典由 _ConnectionFairy.info 和 Connection.info 访问器。

注解

此字典的使用寿命与DBAPI连接本身相关，这意味着它是 丢弃的 每次DBAPI连接关闭和/或失效时。这个 _ConnectionRecord.record_info 字典在 _ConnectionRecord 容器。

method sqlalchemy.pool._ConnectionRecord.invalidate(e=None, soft=False)¶

使此保留的DBAPI连接无效 _ConnectionRecord .

对所有连接无效调用此方法，包括 _ConnectionFairy.invalidate() 或 Connection.invalidate() 调用方法，以及当发生任何所谓的“自动失效”条件时。

参数

• e¶ -- 指示无效原因的异常对象。

• soft¶ -- 如果为True，则连接不会关闭；相反，此连接将在下次签出时回收。。。添加的版本：：1.0.3

参见

关于无效的更多信息

attribute sqlalchemy.pool._ConnectionRecord.record_info¶

与连接记录本身关联的“信息”字典。

不像 _ConnectionRecord.info 字典，链接到DBAPI连接的寿命，此字典链接到 _ConnectionRecord 容器本身，并将在整个生命周期中保持 _ConnectionRecord .

1.1 新版功能.