基本用法¶

从Engine Configuration回顾Engine是通过create_engine()调用创建的：

engine = create_engine('mysql://scott:tiger@localhost/test')

create_engine()的典型用法是每个特定的数据库URL一次，在单个应用程序进程的整个生命周期内全局保存。一个Engine代表进程管理许多单独的DBAPI连接，并且旨在以并发方式调用。The Engine is not synonymous to the DBAPI connect function, which represents just one connection resource - the Engine is most efficient when created just once at the module level of an application, not per-object or per-function call.

对于使用os.fork系统调用的多进程应用程序，或者例如Python multiprocessing模块，通常需要单独的Engine这是因为Engine保持对最终引用DBAPI连接的连接池的引用 - 这些连接池往往不能跨进程边界移植。配置为不使用池的Engine（通过使用NullPool实现）不具备此要求。

该引擎可以直接用于向数据库发出SQL。最通用的方法是首先获取连接资源，通过Engine.connect()方法获取连接资源：

connection = engine.connect()
result = connection.execute("select username from users")
for row in result:
    print("username:", row['username'])
connection.close()

连接是Connection的一个实例，它是实际DBAPI连接的代理对象。在创建Connection时从连接池中检索DBAPI连接。

返回的结果是ResultProxy的一个实例，它引用了一个DBAPI游标并提供了一个与DBAPI游标的接口基本兼容的接口。当它的所有结果行（如果有）用尽时，DBAPI游标将由ResultProxy关闭。A ResultProxy that returns no rows, such as that of an UPDATE statement (without any returned rows), releases cursor resources immediately upon construction.

当调用close()方法时，引用的DBAPI连接将released到连接池中。从数据库本身的角度来看，假设池化正在被使用，没有什么是“封闭的”。池化机制在DBAPI连接上发出一个rollback()调用，以便删除任何事务状态或锁，并且连接已准备好进行下一次使用。

上述过程可以通过使用Engine本身的execute()方法以简写的方式执行：

result = engine.execute("select username from users")
for row in result:
    print("username:", row['username'])

在上面，execute()方法自己获取一个新的Connection，用该对象执行语句并返回ResultProxy。在这种情况下，ResultProxy包含一个称为close_with_result的特殊标志，它指示当其底层DBAPI游标关闭时，Connection也关闭，它再次将DBAPI连接返回到连接池，释放事务资源。

如果ResultProxy可能包含行，则可以指示明确地关闭其资源：

result.close()

如果ResultProxy具有待处理的行并且未被关闭，应用程序将取消引用，则Python垃圾回收最终会关闭游标并触发池的DBAPI连接资源返回到池（SQLAlchemy通过使用weakref回调来实现这一点 - 从来没有__del__方法） - 但依靠Python垃圾回收来管理资源永远不是一个好主意。

我们上面的例子说明了文本SQL字符串的执行。execute()方法当然可以适用更多，包括SQL Expression Language Tutorial中描述的各种SQL表达式结构。

使用交易¶

Connection对象提供了一个返回Transaction对象的begin()方法。This object is usually used within a try/except clause so that it is guaranteed to invoke Transaction.rollback() or Transaction.commit():

connection = engine.connect()
trans = connection.begin()
try:
    r1 = connection.execute(table1.select())
    connection.execute(table1.insert(), col1=7, col2='this is some data')
    trans.commit()
except:
    trans.rollback()
    raise

使用上下文管理器可以更简洁地创建上述块，可以使用Engine：

# runs a transaction
with engine.begin() as connection:
    r1 = connection.execute(table1.select())
    connection.execute(table1.insert(), col1=7, col2='this is some data')

或者从Connection，在这种情况下也可以使用Transaction对象：

with connection.begin() as trans:
    r1 = connection.execute(table1.select())
    connection.execute(table1.insert(), col1=7, col2='this is some data')

# method_a starts a transaction and calls method_b
def method_a(connection):
    trans = connection.begin() # open a transaction
    try:
        method_b(connection)
        trans.commit()  # transaction is committed here
    except:
        trans.rollback() # this rolls back the transaction unconditionally
        raise

# method_b also starts a transaction
def method_b(connection):
    trans = connection.begin() # open a transaction - this runs in the context of method_a's transaction
    try:
        connection.execute("insert into mytable values ('bat', 'lala')")
        connection.execute(mytable.insert(), col1='bat', col2='lala')
        trans.commit()  # transaction is not committed yet
    except:
        trans.rollback() # this rolls back the transaction unconditionally
        raise

# open a Connection and call method_a
conn = engine.connect()
method_a(conn)
conn.close()

了解自动提交¶

前面的事务示例说明了如何使用Transaction，以便多次执行可以参与同一个事务。当我们在不使用Transaction的情况下发出INSERT，UPDATE或DELETE调用时会发生什么？While some DBAPI implementations provide various special “non-transactional” modes, the core behavior of DBAPI per PEP-0249 is that a transaction is always in progress, providing only rollback() and commit() methods but no begin(). SQLAlchemy假定对于任何给定的DBAPI都是这种情况。

鉴于这一要求，SQLAlchemy实现了自己的“自动提交”功能，该功能在所有后端完全一致地工作。这是通过检测代表数据更改操作（即INSERT，UPDATE，DELETE）以及数据定义语言（DDL）语句（如CREATE TABLE，ALTER TABLE）的语句，然后在没有事务正在进行时自动发出COMMIT 。该检测基于语句中存在autocommit=True执行选项。如果语句是纯文本语句并且未设置标志，则使用正则表达式来检测INSERT，UPDATE，DELETE以及针对特定后端的各种其他命令：

conn = engine.connect()
conn.execute("INSERT INTO users VALUES (1, 'john')")  # autocommits

“自动提交”功能仅在没有声明Transaction时才有效。这意味着该功能通常不用于ORM，因为默认情况下Session对象始终保持正在进行的Transaction。

Full control of the “autocommit” behavior is available using the generative Connection.execution_options() method provided on Connection, Engine, Executable, using the “autocommit” flag which will turn on or off the autocommit for the selected scope. 例如，表示提交的存储过程的text()构造可能会使用它，以便SELECT语句将发出COMMIT：

engine.execute(text("SELECT my_mutating_procedure()").execution_options(autocommit=True))

无连接执行，隐式执行¶

回想一下我们提到的第一部分是否执行Connection。“无连接”执行指的是在不是Connection的对象上使用execute()方法。这是使用Engine的execute()方法说明的：

result = engine.execute("select username from users")
for row in result:
    print("username:", row['username'])

除了“无连接”执行之外，还可以使用任何Executable结构的execute()方法，这是支持执行的SQL表达式对象的标记。SQL表达式对象本身引用称为bind的Engine或Connection，它使用它来提供所谓的“隐式”执行服务。

给出如下表格：

from sqlalchemy import MetaData, Table, Column, Integer

meta = MetaData()
users_table = Table('users', meta,
    Column('id', Integer, primary_key=True),
    Column('name', String(50))
)

显式执行将SQL文本或构造的SQL表达式传递给Connection的execute()方法：

engine = create_engine('sqlite:///file.db')
connection = engine.connect()
result = connection.execute(users_table.select())
for row in result:
    # ....
connection.close()

显式无连接执行将表达式传递给Engine的execute()方法：

engine = create_engine('sqlite:///file.db')
result = engine.execute(users_table.select())
for row in result:
    # ....
result.close()

隐式执行也是无连接的，并且使用表达式本身的execute()方法。该方法作为Executable类的一部分提供，该类引用了足以用于针对数据库调用的SQL语句。The method makes usage of the assumption that either an Engine or Connection has been bound to the expression object. 通过“绑定”，我们的意思是使用特殊属性MetaData.bind将一系列Table对象和从它们派生的所有SQL构造与特定引擎相关联：

engine = create_engine('sqlite:///file.db')
meta.bind = engine
result = users_table.select().execute()
for row in result:
    # ....
result.close()

上面，我们使用特殊属性MetaData.bind将Engine与MetaData对象相关联。从Table对象产生的select()结构有一个方法execute()，它将搜索Engine >“绑定”到Table。

总的来说，“绑定元数据”的使用有三个一般效果：

• SQL语句对象获得一个Executable.execute()方法，该方法自动查找要执行的“绑定”。
• The ORM Session object supports using “bound metadata” in order to establish which Engine should be used to invoke SQL statements on behalf of a particular mapped class, though the Session also features its own explicit system of establishing complex Engine/ mapped class configurations.
• The MetaData.create_all(), MetaData.drop_all(), Table.create(), Table.drop(), and “autoload” features all make usage of the bound Engine automatically without the need to pass it explicitly.

在两个“无连接”示例中，Connection在幕后创建；由execute()调用返回的ResultProxy引用用于发出SQL语句的Connection。当ResultProxy关闭时，底层的Connection将关闭，导致DBAPI连接返回到池中，同时删除事务资源。

模式名称翻译¶

为了支持将公共表集分配到多个模式中的多租户应用程序，可以使用Connection.execution_options.schema_translate_map执行选项来重新利用一组Table对象来呈现在不同的模式名称下没有任何更改。

给定一张表格：

user_table = Table(
    'user', metadata,
    Column('id', Integer, primary_key=True),
    Column('name', String(50))
)

由Table.schema属性定义的Table的“模式”是None。Connection.execution_options.schema_translate_map可以指定模式为None的所有Table对象将呈现模式为user_schema_one

connection = engine.connect().execution_options(
    schema_translate_map={None: "user_schema_one"})

result = connection.execute(user_table.select())

上面的代码将在表单的数据库上调用SQL：

SELECT user_schema_one.user.id, user_schema_one.user.name FROM
user_schema.user

也就是说，模式名称被替换为我们翻译的名称。该地图可以指定任意数量的目标 - >目的地模式：

connection = engine.connect().execution_options(
    schema_translate_map={
        None: "user_schema_one",     # no schema name -> "user_schema_one"
        "special": "special_schema", # schema="special" becomes "special_schema"
        "public": None               # Table objects with schema="public" will render with no schema
    })

Connection.execution_options.schema_translate_map参数会影响从Table或Sequence对象派生的SQL表达式语言生成的所有DDL和SQL结构。It does not impact literal string SQL used via the expression.text() construct nor via plain strings passed to Connection.execute().

在模式的名称直接来源于Table或Sequence的情况下，该功能仅对有效；它不会影响字符串模式名称直接传递的方法。By this pattern, it takes effect within the “can create” / “can drop” checks performed by methods such as MetaData.create_all() or MetaData.drop_all() are called, and it takes effect when using table reflection given a Table object. However it does not affect the operations present on the Inspector object, as the schema name is passed to these methods explicitly.

引擎处置¶

Engine指的是连接池，这意味着在正常情况下存在开放的数据库连接，而Engine对象仍驻留在内存中。当一个Engine被垃圾收集时，它的连接池不再被Engine引用，并且假定它的连接都没有被检出，池和它的连接将会也会被垃圾收集，这也会影响到实际的数据库连接。但是否则，假设它使用QueuePool的正常默认池实现，Engine将保持开放数据库连接。

Engine通常是一个永久性的固定装置，可以在应用程序的整个使用期限内建立并维持。不打算在每个连接的基础上创建和处理；它是一个注册表，它维护一个连接池以及有关正在使用的数据库和DBAPI的配置信息，以及一定程度的每个数据库资源的内部缓存。

然而，在很多情况下，Engine引用的所有连接资源都需要完全关闭。在这些情况下依靠Python垃圾回收来发生这种情况通常不是一个好主意；相反，可以使用Engine.dispose()方法显式地处理Engine。这将处理引擎的底层连接池，并将其替换为空的新连接池。如果Engine在此处被丢弃并且不再使用，那么它引用的所有签入连接也将完全关闭。

调用Engine.dispose()的有效用例包括：

• 当一个程序想要释放连接池保留的任何剩余的检入连接，并且期望不再连接到该数据库以用于将来的任何操作。
• 当程序使用多处理或fork()，并且Engine对象被复制到子进程时，应调用Engine.dispose()这样引擎会在该叉上创建全新的数据库连接。数据库连接通常不跨越进程边界传递而不是。
• 在测试套件或多租户方案中，可能会创建和处理许多特定的，短暂的Engine对象。

Connections that are checked out are not discarded when the engine is disposed or garbage collected, as these connections are still strongly referenced elsewhere by the application. However, after Engine.dispose() is called, those connections are no longer associated with that Engine; when they are closed, they will be returned to their now-orphaned connection pool which will ultimately be garbage collected, once all connections which refer to it are also no longer referenced anywhere. 由于这个过程不容易控制，强烈建议只有在所有签出的连接被签入或以其他方式取消关联后，Engine.dispose()才会被调用。

对Engine对象使用连接池产生负面影响的应用程序的替代方法是完全禁用池。这对于使用新的连接只会产生适度的性能影响，并且意味着当连接被签入时，它被完全封闭并且不被保存在内存中。有关如何禁用池的准则，请参见Switching Pool Implementations。

使用Threadlocal执行策略¶

“threadlocal”引擎策略是一个可选功能，非ORM应用程序可以使用该功能将事务与当前线程关联，以便应用程序的所有部分都可以隐式地参与该事务，而无需显式引用Connection

启用threadlocal的步骤如下：

db = create_engine('mysql://localhost/test', strategy='threadlocal')

The above Engine will now acquire a Connection using connection resources derived from a thread-local variable whenever Engine.execute() or Engine.contextual_connect() is called. 只要引用该连接资源，该连接资源就会被维护，这允许应用程序的多个点在使用无连接执行时共享事务：

def call_operation1():
    engine.execute("insert into users values (?, ?)", 1, "john")

def call_operation2():
    users.update(users.c.user_id==5).execute(name='ed')

db.begin()
try:
    call_operation1()
    call_operation2()
    db.commit()
except:
    db.rollback()

通过使用Engine.connect()方法获取不属于threadlocal范围的Connection，可以将显式执行与无连接执行混合在一起：

db.begin()
conn = db.connect()
try:
    conn.execute(log_table.insert(), message="Operation started")
    call_operation1()
    call_operation2()
    db.commit()
    conn.execute(log_table.insert(), message="Operation succeeded")
except:
    db.rollback()
    conn.execute(log_table.insert(), message="Operation failed")
finally:
    conn.close()

要访问绑定到threadlocal作用域的Connection，请调用Engine.contextual_connect()：

conn = db.contextual_connect()
call_operation3(conn)
conn.close()

Calling close() on the “contextual” connection does not release its resources until all other usages of that resource are closed as well, including that any ongoing transactions are rolled back or committed.

使用原始DBAPI连接¶

在某些情况下，SQLAlchemy不提供访问某些DBAPI函数的通用方法，例如调用存储过程以及处理多个结果集。在这些情况下，直接处理原始DBAPI连接也是适宜的。

访问原始DBAPI连接的最常见方式是直接从已存在的Connection对象中获取它。它使用Connection.connection属性存在：

connection = engine.connect()
dbapi_conn = connection.connection

这里的DBAPI连接实际上是源于连接池的“代理”，但这是一个实现细节，在大多数情况下可以忽略。As this DBAPI connection is still contained within the scope of an owning Connection object, it is best to make use of the Connection object for most features such as transaction control as well as calling the Connection.close() method; if these operations are performed on the DBAPI connection directly, the owning Connection will not be aware of these changes in state.

To overcome the limitations imposed by the DBAPI connection that is maintained by an owning Connection, a DBAPI connection is also available without the need to procure a Connection first, using the Engine.raw_connection() method of Engine:

dbapi_conn = engine.raw_connection()

这个DBAPI连接又是一个“代理”形式，就像以前一样。这个代理的目的是显而易见的，因为当我们调用这个连接的.close()方法时，DBAPI连接通常并不实际关闭，而是released到引擎的连接池：

dbapi_conn.close()

尽管SQLAlchemy未来可能会为更多DBAPI用例添加内置模式，但由于这些情况往往很少需要，并且它们也高度依赖于所使用的DBAPI的类型而有所不同，所以无论如何，直接DBAPI对于那些需要的情况，调用模式总是存在的。

以下是一些DBAPI连接使用的配方。

connection = engine.raw_connection()
try:
    cursor = connection.cursor()
    cursor.callproc("my_procedure", ['x', 'y', 'z'])
    results = list(cursor.fetchall())
    cursor.close()
    connection.commit()
finally:
    connection.close()

connection = engine.raw_connection()
try:
    cursor = connection.cursor()
    cursor.execute("select * from table1; select * from table2")
    results_one = cursor.fetchall()
    cursor.nextset()
    results_two = cursor.fetchall()
    cursor.close()
finally:
    connection.close()

注册新方言¶

create_engine()函数调用使用setuptools入口点定位给定的方言。这些入口点可以在setup.py脚本中为第三方方言建立。例如，要创建一个新的方言“foodialect：//”，步骤如下：

1. 创建一个名为foodialect的包。

2. 该包应该有一个包含dialect类的模块，该类通常是sqlalchemy.engine.default.DefaultDialect的子类。在这个例子中，我们假设它叫做FooDialect，它的模块通过foodialect.dialect访问。

3. 入口点可以在setup.py中建立，如下所示：

   entry_points="""
   [sqlalchemy.dialects]
   foodialect = foodialect.dialect:FooDialect
   """

如果方言在现有的SQLAlchemy支持的数据库之上为特定的DBAPI提供支持，则可以给出名称，包括数据库限定。例如，如果FooDialect实际上是一个MySQL方言，那么可以像这样建立入口点：

entry_points="""
[sqlalchemy.dialects]
mysql.foodialect = foodialect.dialect:FooDialect
"""

上面的入口点将作为create_engine("mysql+foodialect://")访问。

from sqlalchemy.dialects import registry
registry.register("mysql.foodialect", "myapp.dialect", "MyMySQLDialect")

连接/引擎API ¶

class sqlalchemy.engine.Connection(engine, connection=None, close_with_result=False, _branch_from=None, _execution_options=None, _dispatch=None, _has_events=None)¶

基础：sqlalchemy.engine.Connectable

为包装的DB-API连接提供高级功能。

为基于字符串的SQL语句以及ClauseElement，Compiled和DefaultGenerator对象提供执行支持。Provides a begin() method to return Transaction objects.

Connection对象是不是线程安全的。虽然可以在使用正确同步访问的线程之间共享Connection，但底层DBAPI连接仍可能不支持线程之间的共享访问。有关详细信息，请查阅DBAPI文档。

Connection对象表示从连接池检出的单个dbapi连接。在此状态下，连接池不会影响连接，包括连接的到期或超时状态。为了使连接池正确管理连接，只要连接未被使用，连接应该返回到连接池（即connection.close()）。

__init__(engine, connection=None, close_with_result=False, _branch_from=None, _execution_options=None, _dispatch=None, _has_events=None)¶

构建一个新的连接。

这里的构造函数不是公共的，只能由Engine调用。请参阅Engine.connect()和Engine.contextual_connect()方法。

开始 T0> （ T1> ） T2> ¶ T3>

开始一个事务并返回一个事务句柄。

返回的对象是Transaction的一个实例。该对象表示事务的“范围”，当调用Transaction.rollback()或Transaction.commit()方法时，该范围完成。

Nested calls to begin() on the same Connection will return new Transaction objects that represent an emulated transaction within the scope of the enclosing transaction, that is:

trans = conn.begin()   # outermost transaction
trans2 = conn.begin()  # "nested"
trans2.commit()        # does nothing
trans.commit()         # actually commits

Calls to Transaction.commit() only have an effect when invoked via the outermost Transaction object, though the Transaction.rollback() method of any of the Transaction objects will roll back the transaction.

也可以看看：

Connection.begin_nested() - 使用SAVEPOINT

Connection.begin_twophase() - 使用两阶段/ XID事务

Engine.begin() - 可从Engine使用的上下文管理器。

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

开始一个嵌套事务并返回一个事务句柄。

返回的对象是NestedTransaction的一个实例。

嵌套事务需要底层数据库中的SAVEPOINT支持。层次结构中的任何事务都可以commit和rollback，但最外层的事务仍然控制整个commit或rollback一个整体的交易。

另见Connection.begin()，Connection.begin_twophase()。

begin_twophase T0> （ T1> XID =无 T2> ） T3> ¶ T4>

开始一个两阶段或XA事务并返回一个事务句柄。

返回的对象是TwoPhaseTransaction的一个实例，它除了由Transaction提供的方法之外，还提供了一个prepare()方法。

参数：	xid ¶ - 两阶段事务ID。如果未提供，则会生成随机ID。

另见Connection.begin()，Connection.begin_twophase()。

靠近 T0> （ T1> ） T2> ¶ T3>

关闭这个Connection。

这会导致释放基础数据库资源，即内部引用的DBAPI连接。The DBAPI connection is typically restored back to the connection-holding Pool referenced by the Engine that produced this Connection. 无论任何Transaction对象在DBAPI连接上存在的任何事务状态都通过DBAPI连接的rollback()方法无条件释放，这可能与Connection

close()被调用后，Connection永久处于关闭状态，并且不允许进一步的操作。

关闭 T0> ¶ T1>

如果此连接已关闭，则返回True。

连接 T0> （ T1> ） T2> ¶ T3>

返回此Connection的分支版本。

可以调用返回的Connection上的Connection.close()方法，并且该Connection

此方法通过Engine.connect()提供使用对称性，包括与上下文管理器一起使用。

连接 T0> ¶ T1>

由此Connection管理的底层DB-API连接。

也可以看看

Working with Raw DBAPI Connections

contextual_connect T0> （ T1> ** kwargs T2> ） T3> ¶ T4>

返回此Connection的分支版本。

可以调用返回的Connection上的Connection.close()方法，并且该Connection

此方法使用Engine.contextual_connect()提供使用对称性，包括与上下文管理器一起使用。

default_isolation_level T0> ¶ T1>

分配给Connection的默认隔离级别。

这是通过Engine.connect()方法首次采购时Connection所具有的隔离级别设置。该级别保持不变，直到Connection.execution_options.isolation_level用于更改每个Connection的设置为止。

与Connection.get_isolation_level()不同，此属性是从方言获得的第一个连接提前设置的，因此在调用此存取器时不会调用SQL查询。

版本0.9.9中的新功能

也可以看看

Connection.get_isolation_level() - 查看当前级别

create_engine.isolation_level - 根据Engine设置隔离级别

Connection.execution_options.isolation_level - 根据Connection设置隔离级别

分离 T0> （ T1> ） T2> ¶ T3>

从连接池中分离底层的DB-API连接。

例如。：

with engine.connect() as conn:
    conn.detach()
    conn.execute("SET search_path TO schema1, schema2")

    # work with connection

# connection is fully closed (since we used "with:", can
# also call .close())

这个Connection实例将保持可用。当关闭（或如上所述从上下文管理器上下文退出）时，DB-API连接将被逐字关闭并且不返回到其源池。

此方法可用于将应用程序的其余部分与连接上的已修改状态（例如事务隔离级别或类似事件）隔离。

执行 tt> （ object，* multiparams，** params / T5> ¶ T6>

执行一个SQL语句结构并返回一个ResultProxy。

参数：

对象 ¶ - 要执行的声明。可能是以下之一： 一个纯字符串 任何ClauseElement结构也是Executable的子类，如select()结构 一个FunctionElement（例如由func生成的）将自动包装在SELECT语句中，然后执行该语句。 一个DDLElement对象 一个DefaultGenerator对象 一个Compiled对象 * multiparams / ** params ¶ - 表示要在执行中使用的绑定参数值。通常，格式是传递给* multiparams的一个或多个字典的集合： conn.execute( table.insert(), {"id":1, "value":"v1"}, {"id":2, "value":"v2"} ) ...或** params解释的个别键/值： conn.execute( table.insert(), id=1, value="v1" ) 在传递普通SQL字符串并且底层DBAPI接受位置绑定参数的情况下，可以传递* multiparams中的元组或集合中的单个值： conn.execute( "INSERT INTO table (id, value) VALUES (?, ?)", (1, "v1"), (2, "v2") ) conn.execute( "INSERT INTO table (id, value) VALUES (?, ?)", 1, "v1" ) 请注意，问号“？”或其他符号的使用取决于DBAPI所使用的“参数样式”，它可以是“qmark”，“named”，“pyformat”，“format”，“ “数字”。有关参数样式的详细信息，请参见pep-249。 要使用DBAPI不可知的方式使用绑定参数的文本SQL语句，请使用text()结构。

execution_options T0> （ T1> **选择 T2> ） T3> ¶ T4>

为执行期间生效的连接设置非SQL选项。

The method returns a copy of this Connection which references the same underlying DBAPI connection, but also defines the given execution options which will take effect for a call to execute(). 由于新的Connection引用了相同的底层资源，因此确保立即丢弃副本通常是一个好主意，如果在以下情况下使用，则隐含这些副本：

result = connection.execution_options(stream_results=True).\
                    execute(stmt)

请注意，任何键/值都可以传递给Connection.execution_options()，并存储在Connection的_execution_options字典中。例如，它适用于终端用户方案与事件监听器进行通信。

当前由SQLAlchemy识别的关键字包括Executable.execution_options()中列出的所有关键字，以及Connection特定的关键字。

参数：

autocommit ¶ - 适用于：Connection，语句。如果为True，则在执行“自动提交”模式时，即执行显式事务时，COMMIT将在执行后调用。请注意，默认情况下，DBAPI连接始终处于事务中 - SQLAlchemy使用应用于不同类型语句的规则来确定是否调用COMMIT以提供其“自动提交”功能。通常，所有INSERT / UPDATE / DELETE语句以及CREATE / DROP语句都启用了自动提交行为； SELECT构造不。当调用需要COMMIT的SELECT或其他特定的SQL构造时（通常在调用存储过程等时）使用此选项，并且显式事务未处于进行中。 compiled_cache ¶ - 适用于：连接。当Connection将一个子句表达式编译成一个Compiled对象时，将会缓存Compiled对象的字典。用户有责任管理该字典的大小，该字典将具有与方言，子句元素，INSERT或UPDATE的VALUES或SET子句中的列名相对应的键，以及用于INSERT或UPDATE语句。本字典的格式不保证在未来版本中保持不变。 请注意，ORM使用其自己的“已编译”缓存来执行某些操作，包括刷新操作。ORM使用的缓存内部取代了此处指定的缓存字典。 isolation_level ¶ - 适用于：Connection。为Connection对象的生命周期设置事务隔离级别（不是解除绑定DBAPI连接，在此Connection对象）。 有效值包括传递给create_engine()的create_engine.isolation_level参数接受的字符串值。这些级别是半数据库特定的；请参阅有关级别的个人方言文档。 请注意，该选项必然会影响源Connection生命周期的底层DBAPI连接，并且不是每次执行。直到底层DBAPI连接返回到连接池，即调用Connection.close()方法时，才会删除此设置。 警告 The isolation_level execution option should not be used when a transaction is already established, that is, the Connection.begin() method or similar has been called. 数据库无法更改正在进行的事务的隔离级别，并且不同的DBAPI和/或SQLAlchemy方言可能隐式回滚或提交事务，或根本不影响连接。 Changed in version 0.9.9: A warning is emitted when the isolation_level execution option is used after a transaction has been started with Connection.begin() or similar. 注意 如果Connection无效，则isolation_level执行选项隐式重置，例如，通过Connection.invalidate()方法，或者发生断开连接错误。失效后产生的新连接将不会自动重新应用隔离级别。 也可以看看 create_engine.isolation_level - 根据Engine设置隔离级别 Connection.get_isolation_level() - 查看当前级别 SQLite Transaction Isolation Postgresql Transaction Isolation MySQL Transaction Isolation SQL Server Transaction Isolation Setting Transaction Isolation Levels - for the ORM no_parameters ¶ - 当True时，如果最终参数列表或字典完全为空，则将调用光标上的语句作为cursor.execute(statement)，而不是根本不传递参数集合。一些DBAPI如psycopg2和mysql-python只有在参数存在时才将百分号视为重要符号；此选项允许代码生成包含百分号（可能还有其他字符）的SQL，这些符号是由DBAPI执行还是通过管理后来由命令行工具调用的脚本传递。 New in version 0.7.6. stream_results ¶ - 适用于：Connection，语句。如果可能的话，对方言表示结果应该是“流式”而不是预先缓冲的。这是许多DBAPI的限制。国旗目前只能通过psycopg2方言来理解。 schema_translate_map ¶ - 适用于：连接，引擎。将模式名映射到模式名称的字典，将SQL或DDL表达式元素编译为字符串时遇到的每个Table元素的Table.schema得到的模式名称将根据原始名称的映射中的存在进行转换。 版本1.1中的新功能 也可以看看 Translation of Schema Names

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

返回分配给Connection的当前隔离级别。

这通常是由方言确定的默认隔离级别，除非已经使用Connection.execution_options.isolation_level功能来改变每个Connection的隔离级别基础。

此属性通常会执行实时SQL操作以获取当前隔离级别，因此返回的值是底层DBAPI连接上的实际级别，无论此状态是如何设置的。与Connection.default_isolation_level访问器比较，该访问器返回方言级设置而不执行SQL查询。

版本0.9.9中的新功能

也可以看看

Connection.default_isolation_level - 查看默认级别

create_engine.isolation_level - 根据Engine设置隔离级别

Connection.execution_options.isolation_level - 根据Connection设置隔离级别

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

如果事务正在进行，则返回True。

信息 T0> ¶ T1>

与此Connection引用的底层DBAPI连接关联的信息字典，允许用户定义的数据与连接相关联。

这里的数据将与DBAPI连接一起进行，包括返回到连接池之后，并在Connection的后续实例中再次使用。

无效 T0> （ T1> 例外=无 T2> ） T3> ¶ T4>

使与Connection关联的基础DBAPI连接失效。

底层的DBAPI连接实际上是关闭的（如果可能的话），并且被丢弃。它的源连接池通常会懒惰地创建一个新的连接来替换它。

Upon the next use (where “use” typically means using the Connection.execute() method or similar), this Connection will attempt to procure a new DBAPI connection using the services of the Pool as a source of connectivty (e.g. a “reconnection”).

If a transaction was in progress (e.g. the Connection.begin() method has been called) when Connection.invalidate() method is called, at the DBAPI level all state associated with this transaction is lost, as the DBAPI connection is closed. 通过调用Transaction.rollback()方法，Connection不会允许重新连接继续，直到Transaction对象结束。在此之前，任何继续使用Connection的尝试都会引发一个InvalidRequestError。这是为了防止应用程序意外地继续正在进行的事务操作，尽管事务由于失效而丢失。

The Connection.invalidate() method, just like auto-invalidation, will at the connection pool level invoke the PoolEvents.invalidate() event.

也可以看看

More on Invalidation

无效 T0> ¶ T1>

如果此连接失效，则返回True。

run_callable （ callable _，* args，** kwargs / T5> ¶ T6>

给定一个可调用的对象或函数，执行它，传递一个Connection作为第一个参数。

给定的* args和** kwargs在Connection参数后传递。

该函数与Engine.run_callable()一起允许函数与Connection或Engine对象一起运行，而无需知道哪个一个正在处理。

标量 （ object，* multiparams，** params / T5> ¶ T6>

执行并返回第一行的第一列。

执行后关闭基础结果/游标。

schema_for_object =＆lt； sqlalchemy.sql.schema._SchemaTranslateMap对象＆gt； ¶

返回对象的“.schema”属性。

用于Table，Sequence和类似对象，并考虑Connection.execution_options.schema_translate_map参数。

版本1.1中的新功能

也可以看看

Translation of Schema Names

事务 （ callable _，* args，** kwargs / T5> ¶ T6>

在事务边界内执行给定的功能。

函数传递这个Connection作为第一个参数，接下来是给定的* args和** kwargs，例如：

def do_something(conn, x, y):
    conn.execute("some statement", {'x':x, 'y':y})

conn.transaction(do_something, 5, 10)

函数内部的操作都在单个Transaction的上下文中调用。成功后，交易即告承诺。如果引发异常，则在传播异常之前回滚该事务。

注意

transaction()方法被Python with:语句的使用所取代：语句可与Connection.begin()一起使用：

with conn.begin():
    conn.execute("some statement", {'x':5, 'y':10})

与Engine.begin()一样：

with engine.begin() as conn:
    conn.execute("some statement", {'x':5, 'y':10})

也可以看看：

Engine.begin() - 引擎级事务上下文

Engine.transaction() - Connection.transaction()

class sqlalchemy.engine。 Connectable ¶

支持执行SQL构造的对象的接口。

Connectable的两个实现是Connection和Engine。

Connectable must also implement the ‘dialect’ member which references a Dialect instance.

连接 T0> （ T1> ** kwargs T2> ） T3> ¶ T4>

返回一个Connection对象。

Depending on context, this may be self if this object is already an instance of Connection, or a newly procured Connection if this object is an instance of Engine.

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

返回一个Connection对象，该对象可能是正在进行的上下文的一部分。

Depending on context, this may be self if this object is already an instance of Connection, or a newly procured Connection if this object is an instance of Engine.

创建 （ 实体，** kwargs ） t5 >

为给定的模式实体发出CREATE语句。

Deprecated since version 0.7: Use the create() method on the given schema object directly, i.e. Table.create(), Index.create(), MetaData.create_all()

drop （ entity，** kwargs ） t5 >

发出给定模式实体的DROP语句。

Deprecated since version 0.7: Use the drop() method on the given schema object directly, i.e. Table.drop(), Index.drop(), MetaData.drop_all()

执行 tt> （ object，* multiparams，** params / T5> ¶ T6>

执行给定的结构并返回一个ResultProxy。

标量 （ object，* multiparams，** params / T5> ¶ T6>

执行并返回第一行的第一列。

底层游标在执行后关闭。

class sqlalchemy.engine.CreateEnginePlugin(url, kwargs)¶

一组挂钩，旨在根据URL中的入口点名称来扩充Engine对象的构造。

CreateEnginePlugin的用途是允许第三方系统应用引擎，池和方言级事件侦听器，而不需要修改目标应用程序；相反，插件名称可以添加到数据库URL中。CreateEnginePlugin的目标应用程序包括：

• 连接和SQL性能工具，例如它使用事件来跟踪结账的次数和/或花在语句上的时间
• 连接插件，如代理

插件以与方言类似的方式使用入口点进行注册：

entry_points={
    'sqlalchemy.plugins': [
        'myplugin = myapp.plugins:MyPlugin'
    ]

使用上述名称的插件将从数据库URL中调用，如下所示：

from sqlalchemy import create_engine

engine = create_engine(
  "mysql+pymysql://scott:tiger@localhost/test?plugin=myplugin")

plugin参数支持多个实例，以便URL可以指定多个插件；它们按URL中的顺序加载：

engine = create_engine(
  "mysql+pymysql://scott:tiger@localhost/"
  "test?plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three")

插件可以接收来自URL字符串的附加参数以及传递给create_engine()的关键字参数。将URL对象和关键字字典传递给构造函数，以便可以从url的URL.query集合以及字典中提取这些参数：

class MyPlugin(CreateEnginePlugin):
    def __init__(self, url, kwargs):
        self.my_argument_one = url.query.pop('my_argument_one')
        self.my_argument_two = url.query.pop('my_argument_two')
        self.my_argument_three = kwargs.pop('my_argument_three', None)

如上所述的参数将从以下内容中消耗：

from sqlalchemy import create_engine

engine = create_engine(
  "mysql+pymysql://scott:tiger@localhost/"
  "test?plugin=myplugin&my_argument_one=foo&my_argument_two=bar",
  my_argument_three='bat')

URL和字典用于引擎的后续设置，因此插件可以在原地修改它们的参数。只有插件才能理解的参数应该被弹出或以其他方式移除，以便之后不会将其解释为错误参数。

当引擎创建过程完成并生成Engine对象时，它将再次通过CreateEnginePlugin.engine_created()钩子传递给插件。在这个钩子中，可以对引擎进行额外的改变，通常涉及事件的设置（例如在Core Events中定义的那些事件）。

版本1.1中的新功能

__ init __ （ url，kwargs ）

构建一个新的CreateEnginePlugin。

每次调用create_engine()时，都会单独实例化插件对象。一个Engine将被传递给与此URL对应的CreateEnginePlugin.engine_created()方法。

参数：	url¶ – the URL object. 插件应该检查​​它在这里的需求，并从URL.query集合中移除它的自定义参数。URL也可以以其他任何方式就地修改。 kwargs ¶ - 将关键字参数传递给：func`.create_engine`。该插件可以在原地读取和修改该字典，以影响用于创建引擎的最终参数。它应该从字典中删除它的自定义参数。

engine_created T0> （ T1> 发动机 T2> ） T3> ¶ T4>

完全构建时接收Engine对象。

插件可能会对引擎进行其他更改，例如注册引擎或连接池事件。

class sqlalchemy.engine.Engine(pool, dialect, url, logging_name=None, echo=None, proxy=None, execution_options=None)¶

基础：sqlalchemy.engine.Connectable，sqlalchemy.log.Identified

将Pool和Dialect连接在一起，以提供数据库连接和行为的来源。

一个Engine对象使用create_engine()函数公开实例化。

也可以看看：

Engine Configuration

Working with Engines and Connections

开始 T0> （ T1> close_with_result =假 T2> ） T3> ¶ T4>

返回一个上下文管理器，它提供一个Connection和一个Transaction建立的。

例如。：

with engine.begin() as conn:
    conn.execute("insert into table (x, y, z) values (1, 2, 3)")
    conn.execute("my_special_procedure(5)")

在成功操作后，Transaction被提交。如果发生错误，则回滚Transaction。

close_with_result标志通常是False，并且表示当操作完成时Connection将被关闭。When set to True, it indicates the Connection is in “single use” mode, where the ResultProxy returned by the first call to Connection.execute() will close the Connection when that ResultProxy has exhausted all result rows.

New in version 0.7.6.

也可以看看：

Engine.connect() - 从Engine获取Connection。

Connection.begin() - 为特定的Connection启动一个Transaction。

连接 T0> （ T1> ** kwargs T2> ） T3> ¶ T4>

返回一个新的Connection对象。

Connection对象是一个在内部使用DBAPI连接以与数据库通信的Facade。该连接是从Engine引用的连接持有Pool中获取的。当Connection对象的close()方法被调用时，底层的DBAPI连接将被返回到连接池，并在随后的调用中再次使用它connect()

contextual_connect （ close_with_result = False，** kwargs ） / T5>

返回一个Connection对象，该对象可能是某个正在进行的上下文的一部分。

默认情况下，此方法与Engine.connect()执行相同的操作。Engine的子类可以重写此方法以提供上下文行为。

参数：	close_with_result¶ – When True, the first ResultProxy created by the Connection will call the Connection.close() method of that connection as soon as any pending result rows are exhausted. 这用于提供由Engine.execute()方法提供的“无连接执行”行为。

处置 T0> （ T1> ） T2> ¶ T3>

处置此Engine使用的连接池。

这具有完全关闭当前在数据库连接中检入的所有的效果。仍然检出的连接将不关闭，但它们将不再与此Engine关联，因此，当它们单独关闭时，最终会导致Pool

在处理旧的连接池后立即创建新的连接池。与所有SQLAlchemy连接池一样，这个新池在第一次请求之前不会与数据库建立任何实际连接，因此只要不再使用Engine，将不会创建新连接。

也可以看看

Engine Disposal

驱动器 T0> ¶ T1>

此Engine使用的Dialect的驱动程序名称。

execute(statement, *multiparams, **params)¶

执行给定的结构并返回一个ResultProxy。

参数与Connection.execute()使用的参数相同。

这里，使用contextual_connect()方法获取Connection，并使用该连接执行语句。返回的ResultProxy被标记，以便当ResultProxy耗尽且其底层游标关闭时，此处创建的Connection也将被关闭，允许将其关联的DBAPI连接资源返回到连接池。

execution_options T0> （ T1> **选择 T2> ） T3> ¶ T4>

返回一个新的Engine，它将提供Connection对象给定的执行选项。

返回的Engine保持与原始Engine的相关性，因为它共享相同的连接池和其他状态：

• 新的Engine使用的Pool是相同的实例。Engine.dispose()方法将替代父引擎的连接池实例以及此引擎。
• 事件侦听器是“级联的”，也就是说，新的Engine继承父级的事件，新的事件可以与新的Engine分别关联。
• 日志记录配置和logging_name从父节点Engine复制。

Engine.execution_options()方法的目的是实现“分片”方案，其中多个Engine对象引用同一个连接池，但通过选项由自定义事件消耗：

primary_engine = create_engine("mysql://")
shard1 = primary_engine.execution_options(shard_id="shard1")
shard2 = primary_engine.execution_options(shard_id="shard2")

Above, the shard1 engine serves as a factory for Connection objects that will contain the execution option shard_id=shard1, and shard2 will produce Connection objects that contain the execution option shard_id=shard2.

给定连接时，事件处理程序可以使用上述执行选项来执行模式切换或其他操作。下面我们发出一个MySQL use语句来切换数据库，同时使用Connection.info字典跟踪我们建立的数据库，从而为我们提供了一个持久性存储空间遵循DBAPI连接：

from sqlalchemy import event
from sqlalchemy.engine import Engine

shards = {"default": "base", shard_1: "db1", "shard_2": "db2"}

@event.listens_for(Engine, "before_cursor_execute")
def _switch_shard(conn, cursor, stmt,
        params, context, executemany):
    shard_id = conn._execution_options.get('shard_id', "default")
    current_shard = conn.info.get("current_shard", None)

    if current_shard != shard_id:
        cursor.execute("use %s" % shards[shard_id])
        conn.info["current_shard"] = shard_id

0.8版本中的新功能

也可以看看

Connection.execution_options() - update execution options on a Connection object.

Engine.update_execution_options() - update the execution options for a given Engine in place.

has_table （ table_name，schema =无 ） t5 >

如果给定的后端具有给定名称的表，则返回True。

也可以看看

Fine Grained Reflection with Inspector - detailed schema inspection using the Inspector interface.

quoted_name - 用于将引用信息与架构标识符一起传递。

名称 T0> ¶ T1>

Engine使用的Dialect的字符串名称。

raw_connection T0> （ T1> _connection =无 T2> ） T3> ¶ T4>

从连接池中返回一个“原始”DBAPI连接。

返回的对象是正在使用的底层驱动程序使用的DBAPI连接对象的代理版本。该对象与真实的DBAPI连接具有完全相同的行为，只是它的close()方法将导致连接返回到池中，而不是实际关闭。

当不需要由Connection提供的API时，该方法为特殊情况提供直接的DBAPI连接访问。当Connection对象已经存在时，DBAPI连接可以使用Connection.connection访问器。

也可以看看

Working with Raw DBAPI Connections

run_callable （ callable _，* args，** kwargs / T5> ¶ T6>

给定一个可调用的对象或函数，执行它，传递一个Connection作为第一个参数。

给定的* args和** kwargs在Connection参数后传递。

该函数与Connection.run_callable()一起允许函数与Connection或Engine对象一起运行，而无需知道哪个一个正在处理。

schema_for_object =＆lt； sqlalchemy.sql.schema._SchemaTranslateMap对象＆gt； ¶

返回对象的“.schema”属性。

用于Table，Sequence和类似对象，并考虑Connection.execution_options.schema_translate_map参数。

版本1.1中的新功能

也可以看看

Translation of Schema Names

table_names(schema=None, connection=None)¶

返回数据库中可用的所有表名称的列表。

参数：	schema¶ – Optional, retrieve names from a non-default schema. 连接 ¶ - 可选，使用指定的连接。默认值是Engine的contextual_connect。

事务 （ callable _，* args，** kwargs / T5> ¶ T6>

在事务边界内执行给定的功能。

该函数传递一个从Engine.contextual_connect()新获得的Connection作为第一个参数，接下来是给定的* args和** kwargs。

例如。：

def do_something(conn, x, y):
    conn.execute("some statement", {'x':x, 'y':y})

engine.transaction(do_something, 5, 10)

函数内部的操作都在单个Transaction的上下文中调用。成功后，交易即告承诺。如果引发异常，则在传播异常之前回滚该事务。

注意

transaction()方法被Python with:语句，可用于Engine.begin()：

with engine.begin() as conn:
    conn.execute("some statement", {'x':5, 'y':10})

也可以看看：

Engine.begin() - 引擎级事务上下文

Connection.transaction() - Engine.transaction()

update_execution_options T0> （ T1> **选择 T2> ） T3> ¶ T4>

更新此Engine的默认execution_options字典。

** opt中的给定键/值将被添加到将用于所有连接的默认执行选项。该字典的初始内容可以通过execution_options参数发送到create_engine()。

也可以看看

Connection.execution_options()

Engine.execution_options()

class sqlalchemy.engine。 ExceptionContext ¶

封装有关正在进行的错误情况的信息。

该对象仅用于传递给ConnectionEvents.handle_error()事件，支持可以扩展而没有向后不兼容的接口。

版本0.9.7中的新功能

chained_exception =无 ¶

前面的处理程序在异常链中返回的异常（如果有）。

如果存在，这个异常将是最终由SQLAlchemy引发的异常，除非后续的处理程序替换它。

可能是无。

连接 =无 ¶

异常期间使用的Connection。

除第一次连接失败的情况外，该成员在场。

也可以看看

ExceptionContext.engine

游标 =无 ¶

DBAPI游标对象。

可能是无。

引擎 =无 ¶

异常期间使用的Engine。

即使在首次连接失败的情况下，该成员也应始终存在。

版本1.0.0中的新功能

execution_context =无 ¶

与正在执行的执行操作相对应的ExecutionContext。

这是用于语句执行操作，但不适用于事务开始/结束等操作。在构造ExecutionContext之前引发异常时，它也不存在。

Note that the ExceptionContext.statement and ExceptionContext.parameters members may represent a different value than that of the ExecutionContext, potentially in the case where a ConnectionEvents.before_cursor_execute() event or similar modified the statement/parameters to be sent.

可能是无。

invalidate_pool_on_disconnect = True ¶

表示当“断开”条件生效时，池中的所有连接是否应该失效。

在ConnectionEvents.handle_error()事件的范围内将此标志设置为False将会产生这样的效果，即在断开连接期间池中的完整连接集合不会失效；只有当前连接是错误的主题，实际上会失效。

此标志的用途是用于自定义断开连接处理方案，其中池中其他连接的失效将基于其他条件执行，或者甚至基于每个连接执行。

版本1.0.3中的新功能

is_disconnect =无 ¶

表示发生的异常是否表示“断开”状况。

该标志在ConnectionEvents.handle_error()处理程序的范围内将始终为True或False。

SQLAlchemy将会根据这个标志来确定连接是否应该随后失效。也就是说，通过分配此标志，可以通过更改此标志来调用或阻止导致连接和池无效的“断开”事件。

original_exception =无 ¶

被捕获的异常对象。

此会员始终在场。

参数 =无 ¶

直接发送到DBAPI的参数集合。

可能是无。

sqlalchemy_exception =无 ¶

包含原始文件的sqlalchemy.exc.StatementError，并且如果异常处理没有被事件绕过，将会引发该文件。

可能为无，因为并非所有异常类型都由SQLAlchemy包装。对于继承dbapi的Error类的DBAPI级异常，此字段将始终存在。

语句 =无 ¶

直接发送到DBAPI的字符串SQL语句。

可能是无。

class sqlalchemy.engine。 NestedTransaction （ connection，T5> ） T6> ¶ T7>

基础：sqlalchemy.engine.Transaction

表示“嵌套”或SAVEPOINT事务。

可以使用Connection.begin_nested()方法获取新的NestedTransaction对象。

该界面与Transaction的界面相同。

class sqlalchemy.engine.ResultProxy(context)¶

包装一个DB-API游标对象，以便更容易地访问行列。

单个列可以通过它们的整数位置，不区分大小写的列名称或通过schema.Column对象来访问。例如。：

row = fetchone()

col1 = row[0]    # access via integer position

col2 = row['col2']   # access via name

col3 = row[mytable.c.mycol] # access via Column object.

ResultProxy also handles post-processing of result column data using TypeEngine objects, which are referenced from the originating SQL statement that produced this result set.

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

可能被子类覆盖。

_process_row T0> ¶ T1>

RowProxy的别名

_soft_close T0> （ T1> _autoclose_connection =真 T2> ） T3> ¶ T4>

软关闭这个ResultProxy。

这将释放所有的DBAPI游标资源，但是从语义的角度来看ResultProxy是“open”的，意味着fetchXXX()方法将继续返回空结果。

此方法在以下情况下自动调用：

• 所有结果行都使用fetchXXX()方法耗尽。
• cursor.description是None。

此方法不公开，但为了阐明所使用的“autoclose”过程而进行了记录。

版本1.0.0中的新功能

也可以看看

ResultProxy.close()

靠近 T0> （ T1> ） T2> ¶ T3>

关闭这个ResultProxy。

这将关闭与语句执行相关的底层DBAPI游标，如果仍然存在的话。请注意，当ResultProxy耗尽所有可用行时，DBAPI游标会自动释放。ResultProxy.close() is generally an optional method except in the case when discarding a ResultProxy that still has additional rows pending for fetch.

在结果是connectionless execution的结果的情况下，解除绑定Connection对象也被关闭，该releases DBAPI连接资源。

在调用此方法后，调用fetch方法将不再有效，这会在随后的使用中引发ResourceClosedError。

版本1.0.0中已更改： - ResultProxy.close()方法已从释放基础DBAPI游标资源的进程中分离出来。Connection的“自动关闭”功能现在执行所谓的“软关闭”，它释放底层的DBAPI游标，但允许ResultProxy仍然表现为开放但耗尽的结果集；实际的ResultProxy.close()方法永远不会被调用。在不调用此方法的情况下放弃已经完全耗尽的ResultProxy仍是安全的。

也可以看看

Working with Engines and Connections

ResultProxy._soft_close()

使用fetchall T0> （ T1> ） T2> ¶ T3>

获取所有行，就像DB-API cursor.fetchall()一样。

在所有行耗尽后，释放基础DBAPI游标资源，并可以安全地丢弃该对象。

随后对ResultProxy.fetchall()的调用将返回一个空列表。After the ResultProxy.close() method is called, the method will raise ResourceClosedError.

在版本1.0.0中更改： - 增加了“软关闭”行为，允许在调用ResultProxy.close()之前将结果用于“耗尽”方法。

支持fetchmany T0> （ T1> 大小=无 T2> ） T3> ¶ T4>

取多行，就像DB-API cursor.fetchmany(size=cursor.arraysize)。

在所有行耗尽后，释放基础DBAPI游标资源，并可以安全地丢弃该对象。

所有行被抽取后调用ResultProxy.fetchmany()将返回一个空列表。After the ResultProxy.close() method is called, the method will raise ResourceClosedError.

在版本1.0.0中更改： - 增加了“软关闭”行为，允许在调用ResultProxy.close()之前将结果用于“耗尽”方法。

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

获取一行，就像DB-API cursor.fetchone()一样。

在所有行耗尽后，释放基础DBAPI游标资源，并可以安全地丢弃该对象。

所有行耗尽后调用ResultProxy.fetchone()将返回None。After the ResultProxy.close() method is called, the method will raise ResourceClosedError.

在版本1.0.0中更改： - 增加了“软关闭”行为，允许在调用ResultProxy.close()之前将结果用于“耗尽”方法。

第一 T0> （ T1> ） T2> ¶ T3>

取出第一行，然后无条件关闭结果集。

如果没有行存在，则返回None。

调用此方法后，对象完全关闭，例如ResultProxy.close()方法将被调用。

inserted_primary_key T0> ¶ T1>

返回刚刚插入的行的主键。

返回值是与目标表中主键列列表对应的标量值列表。

这仅适用于没有明确指定Insert.returning()的单行insert()结构。

请注意，指定server_default子句或者不符合“自动增量”列的主键列（请参见Column中的注释）并且使用数据库端默认值生成的主键列将出现在此处列表为None，除非后端支持“返回”并且启用了使用“隐式返回”执行的插入语句。

如果执行语句不是编译的表达式结构或不是insert()结构，则引发InvalidRequestError。

is_insert T0> ¶ T1>

True if this ResultProxy is the result of a executing an expression language compiled expression.insert() construct.

当为True时，这意味着可以访问inserted_primary_key属性，假定该语句不包含用户定义的“返回”结构。

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

返回行的当前字符串集合。

last_inserted_pa​​rams T0> （ T1> ） T2> ¶ T3>

从该执行中返回插入参数的集合。

如果执行语句不是编译的表达式结构或不是insert()结构，则引发InvalidRequestError。

last_updated_pa​​rams T0> （ T1> ） T2> ¶ T3>

从此执行中返回更新参数的集合。

如果执行语句不是编译表达式结构或不是update()结构，则引发InvalidRequestError。

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

从底层的ExecutionContext返回lastrow_has_defaults()。

有关详细信息，请参阅ExecutionContext。

lastrowid T0> ¶ T1>

返回DBAPI游标上的'lastrowid'访问器。

这是一个特定于DBAPI的方法，仅适用于支持它的后端，适用于适当的语句。它的行为在后端不一致。

使用insert()表达式结构时，通常不需要使用此方法；无论数据库后端如何，inserted_primary_key属性都为新插入的行提供主键值的元组。

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

从底层的ExecutionContext返回postfetch_cols()。

有关详细信息，请参阅ExecutionContext。

如果执行的语句不是编译的表达式结构，或者不是insert()或update()结构，则引发InvalidRequestError。

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

从底层的ExecutionContext返回prefetch_cols()。

有关详细信息，请参阅ExecutionContext。

如果执行的语句不是编译的表达式结构，或者不是insert()或update()结构，则引发InvalidRequestError。

returned_defaults T0> ¶ T1>

返回使用ValuesBase.return_defaults()特征获取的默认列的值。

如果不使用ValuesBase.return_defaults()或者后端不支持RETURNING，则该值为RowProxy的实例，或None。

版本0.9.0中的新功能

也可以看看

ValuesBase.return_defaults()

returns_rows T0> ¶ T1>

如果这个ResultProxy返回行，则为真。

即如果调用方法fetchone()，fetchmany() fetchall()是合法的。

行计数 T0> ¶ T1>

为此结果返回'rowcount'。

'rowcount'通过UPDATE或DELETE语句的WHERE标准报告匹配的行数。

注意

关于ResultProxy.rowcount的说明：

• 该属性返回匹配的行数，它不一定与实际修改的行数相同 - 例如，UPDATE语句可能没有网络如果给定的SET值与已存在的行值相同，则在给定行上进行更改。这样的行可以匹配但不能修改。在具有两种样式（例如MySQL）的后端上，默认情况下会配置rowcount以在所有情况下返回匹配计数。
• ResultProxy.rowcount is only useful in conjunction with an UPDATE or DELETE statement. Contrary to what the Python DBAPI says, it does not return the number of rows available from the results of a SELECT statement as DBAPIs cannot support this functionality when rows are unbuffered.
• ResultProxy.rowcount may not be fully implemented by all dialects. 特别是，大多数DBAPI不支持executemany调用的聚合行计数结果。如果已知支持每种用法，则方法将从方言报告ResultProxy.supports_sane_rowcount()和ResultProxy.supports_sane_multi_rowcount()方法。
• 使用RETURNING的语句可能不会返回正确的rowcount。

标量 T0> （ T1> ） T2> ¶ T3>

获取第一行的第一列，然后关闭结果集。

如果没有行存在，则返回None。

调用此方法后，对象完全关闭，例如ResultProxy.close()方法将被调用。

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

从方言返回supports_sane_multi_rowcount。

有关背景，请参阅ResultProxy.rowcount。

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

从方言返回supports_sane_rowcount。

有关背景，请参阅ResultProxy.rowcount。

class sqlalchemy.engine.RowProxy(parent, row, processors, keymap)¶

基础：sqlalchemy.engine.BaseRowProxy

来自单个游标行的代理值。

主要遵循“有序字典”行为，将结果值映射到基于字符串的列名称，行中结果的整数位置以及可以映射到生成此结果集的原始列的Column实例（用于结果对应于构造的SQL表达式）。

对象的has_key T0> （ T1> 键 T2> ） T3> ¶ T4>

如果此RowProxy包含给定的键，则返回True。

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

返回一个元组列表，每个元组包含一个键/值对。

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

以RowProxy表示的字符串形式返回键列表。

class sqlalchemy.engine.Transaction(connection, parent)¶

表示正在进行的数据库事务。

Transaction对象是通过调用Connection的begin()方法来获取的：

from sqlalchemy import create_engine
engine = create_engine("postgresql://scott:tiger@localhost/test")
connection = engine.connect()
trans = connection.begin()
connection.execute("insert into x (a, b) values (1, 2)")
trans.commit()

该对象提供了rollback()和commit()方法来控制事务边界。它还实现了一个上下文管理器接口，以便Python with语句可以与Connection.begin()方法一起使用：

with connection.begin():
    connection.execute("insert into x (a, b) values (1, 2)")

事务对象是不是线程安全。

另见：Connection.begin()，Connection.begin_twophase()，Connection.begin_nested()。

靠近 T0> （ T1> ） T2> ¶ T3>

关闭这个Transaction。

如果此事务是开始/提交嵌套中的基本事务，则事务将回滚()。否则，该方法返回。

这用于取消交易而不影响封闭交易的范围。

提交 T0> （ T1> ） T2> ¶ T3>

提交这个Transaction。

回滚 T0> （ T1> ） T2> ¶ T3>

回滚这个Transaction。

class sqlalchemy.engine.TwoPhaseTransaction(connection, xid)¶

基础：sqlalchemy.engine.Transaction

代表两阶段交易。

可以使用Connection.begin_twophase()方法获取新的TwoPhaseTransaction对象。

该接口与Transaction的接口相同，并增加了prepare()方法。

制备 T0> （ T1> ） T2> ¶ T3>

准备这个TwoPhaseTransaction。

在PREPARE之后，交易可以被提交。