使用引擎和接头¶

本节详细介绍了 EngineConnection 以及相关对象。重要的是要注意,当使用sqlAlchemy ORM时,通常不会访问这些对象;相反,这些对象 Session 对象用作数据库的接口。但是,对于围绕直接使用文本SQL语句和/或SQL表达式构造而构建的应用程序,而不需要ORM的更高级别管理服务的参与,则 EngineConnection 是国王(还是王后?)-继续阅读。

基本用法

回忆起 引擎配置 那是 Engine 通过创建 create_engine() 调用:

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

的典型用法 create_engine() 是每个特定数据库URL一次,在单个应用程序进程的生命周期内全局保存。单一的 Engine 代表进程管理多个单独的DBAPI连接,并打算以并发方式进行调用。这个 Enginenot 与DBAPI同义 connect 函数,它只表示一个连接资源 Engine 仅在应用程序的模块级创建一次,而不是每个对象或每个函数调用时,效率最高。

对于使用 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连接的对象。DBAPI连接从连接池中的 Connection 创建。

返回的结果是 ResultProxy 它引用了DBAPI游标,并提供了与DBAPI游标基本兼容的接口。dbapi光标将由 ResultProxy 当它的所有结果行(如果有)用完时。一 ResultProxy 它不返回任何行,例如UPDATE语句的行(不返回任何行),在构造后立即释放光标资源。

close() 方法,引用的DBAPI连接是 released 连接池。从数据库本身的角度来看,假设使用池,实际上没有什么是“关闭”的。池机制发出 rollback() 调用DBAPI连接,以便删除任何事务状态或锁,并且该连接已准备好下次使用。

上述步骤可以通过使用 execute() 方法 Engine 本身::

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通过使用weakeref回调实现此目的- 从未 这个 __del__ 方法)-但是,依靠Python垃圾收集来管理资源从来不是一个好主意。

上面的示例说明了文本SQL字符串的执行。这个 execute() 方法当然可以容纳更多的内容,包括中描述的各种SQL表达式构造。 SQL表达式语言教程 .

使用事务

注解

本节介绍如何在直接处理事务时使用事务 EngineConnection 对象。使用SQLAlchemy ORM时,用于事务控制的公共API通过 Session 对象,它使用 Transaction 对象内部。见 管理交易 更多信息。

这个 Connection 对象提供 begin() 返回 Transaction 对象。此对象通常在try/except子句中使用,以确保它可以调用 Transaction.rollback()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')

事务块的嵌套

这个 Transaction 对象还通过跟踪最外层的begin/commit对来处理“嵌套”行为。在本例中,两个函数都在 Connection 但只有最外面的 Transaction 对象在提交时实际生效。

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

上面, method_a 先被调用,它调用 connection.begin() . 然后它调用 method_b . 什么时候? method_b 调用 connection.begin() ,它只是递增一个计数器,当它调用 commit() . 如果任一 method_amethod_b 调用 rollback() ,将回滚整个事务。在以下时间之前未提交事务 method_a 调用 commit() 方法。这种“嵌套”行为允许创建功能,这些功能“保证”如果一个事务不可用,将使用该事务,但如果一个事务存在,将自动参与封闭事务。

了解自动提交

上一个事务示例说明了如何使用 Transaction 以便多个执行可以参与同一事务。如果不使用 Transaction ?虽然一些DBAPI实现提供了各种特殊的“非事务”模式,但根据PEP-0249,DBAPI的核心行为是 事务始终在进行中 ,仅提供 rollback()commit() 方法但不 begin() . SQLAlchemy假定任何给定DBAPI都是这样。

考虑到这一需求,SQLAlchemy实现了自己的“自动提交”功能,该功能可以在所有后端完全一致地工作。这是通过检测表示数据更改操作的语句(即插入、更新、删除)以及数据定义语言(DDL)语句(如创建表、更改表)来实现的,然后在没有事务进行时自动发出提交。检测是基于 autocommit=True 语句的执行选项。如果该语句是纯文本语句且未设置标志,则使用正则表达式检测特定后端的插入、更新、删除以及各种其他命令:

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

“自动提交”功能仅在“否”时有效 Transaction 已另行声明。这意味着该特性通常不与ORM一起使用,因为 Session 默认情况下,对象始终保持 Transaction .

使用Generative可以完全控制“自动提交”行为 Connection.execution_options() 方法提供于 ConnectionEngineExecutable ,使用“autocommit”标志打开或关闭所选作用域的自动提交。例如,A text() 表示提交的存储过程的构造可能会使用它,以便select语句将发出commit::

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

无连接执行,隐式执行

回想一下我们提到的第一节,执行时使用或不使用 Connection . "“无连接”执行是指 execute() 对象上的方法,该对象不是 Connection . 这是用 execute() 方法 Engine ::

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

除了“无连接”执行之外,还可以使用 execute() 任意方法 Executable 构造,它是支持执行的SQL表达式对象的标记。SQL表达式对象本身引用了 EngineConnection 被称为 bind 以提供所谓的“隐式”执行服务。

给出如下表格:

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表达式传递到 execute() 方法 Connection

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

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

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

隐式执行也是无连接的,并使用 execute() 方法。此方法是 Executable 类,它引用的SQL语句足以对数据库调用。该方法使用了以下假设: EngineConnection 已经 跳跃 到表达式对象。我们所说的“绑定”是指 MetaData.bind 已用于关联一系列 Table 对象和所有从这些对象派生的具有特定引擎的SQL构造::

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

上面,我们将 Engine 用一个 MetaData 使用特殊属性的对象 MetaData.bind . 这个 select() 从中生成的构造 Table 对象有一个方法 execute() ,它将搜索 Engine 这是“绑定”到 Table .

总的来说,“绑定元数据”的使用有三个一般影响:

注解

现代SQLAlchemy没有强调“绑定元数据”和“隐式执行”的概念。虽然它们提供了一些便利,但是它们不再是任何API所需要的,也不再是必需的。

在多个应用程序中 Engine 对象存在,每个对象都与一组特定的表(即 垂直切分 )可以使用“绑定元数据”技术,以便 Table 可以参考适当的 Engine 自动;尤其是通过 Session 对象作为关联方式 Table 对象具有适当的 Engine ,作为使用直接由 Session .

但是,“隐式执行”技术根本不适合与ORM一起使用,因为它绕过了由 Session .

总的来说,在 绝大多数 在案例中,“绑定元数据”和“隐式执行”是 没有用 . 虽然“绑定的元数据”在ORM配置方面的用处微乎其微,但“隐式执行”是一种非常古老的使用模式,在大多数情况下,它比帮助更容易混淆,而且不鼓励使用它。这两种模式似乎都鼓励在应用程序设计中过度使用权宜之计的“捷径”,这将导致后来的问题。

现代的sqlAlchemy用法,尤其是ORM,一直强调在事务的上下文中工作;“隐式执行”概念使得将语句执行与特定事务关联起来的工作更加困难。这个 Executable.execute() 特定SQL语句上的方法通常意味着执行不是任何特定事务的一部分,这通常不是期望的效果。

在两个“无连接”示例中, Connection 是在幕后创造的;是 ResultProxy 返回的 execute() 调用引用 Connection 用于发出SQL语句。当 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 定义如下: Table.schema 属性是 None . 这个 Connection.execution_options.schema_translate_map 可以全部指定 Table 架构为的对象 None 而是将架构呈现为 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 参数影响从SQL表达式语言生成的所有DDL和SQL构造,如从 TableSequence 对象。它确实 not 影响通过 expression.text() 构造或通过传递给 Connection.execute() .

该功能生效 only 在这些情况下,模式的名称直接从 TableSequence ;它不会影响直接传递字符串架构名称的方法。根据此模式,它在“can create”/“can drop”检查中生效,这些检查由以下方法执行 MetaData.create_all()MetaData.drop_all() 调用,并在使用表反射时生效 Table 对象。然而它确实如此 not 影响当前的操作 Inspector 对象,因为模式名被显式传递给这些方法。

1.1 新版功能.

引擎处理

这个 Engine 引用连接池,这意味着在正常情况下,存在打开的数据库连接,而 Engine 对象仍驻留在内存中。当一个 Engine 是垃圾收集的,其连接池不再由该引用 Engine ,并且假设它的所有连接都未签出,那么池及其连接也将被垃圾收集,这也会关闭实际的数据库连接。但除此之外, Engine 将保留打开的数据库连接,假定它使用 QueuePool .

这个 Engine 通常是在应用程序的整个生命周期中预先建立和维护的永久性固定装置。它是 not 目的是在每个连接的基础上创建和处理;相反,它是一个注册中心,既维护连接池,也维护数据库和DBAPI使用中的配置信息,以及每个数据库资源的某种程度的内部缓存。

但是,在许多情况下,需要 Engine 完全封闭。对于这些情况,依赖于Python垃圾收集通常不是一个好主意,而是 Engine 可以使用 Engine.dispose() 方法。这将处理引擎的底层连接池,并将其替换为空的新连接池。前提是 Engine 在此时被丢弃,不再使用 checked-in 它所指的连接也将完全关闭。

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

连接 签出not 当引擎被释放或垃圾收集时丢弃,因为应用程序在其他地方仍然强烈引用这些连接。然而,之后 Engine.dispose() 被调用,这些连接不再与 Engine ;当它们被关闭时,它们将被返回到它们现在的孤立连接池,一旦引用它的所有连接也不再在任何地方被引用,最终将被垃圾收集。由于这一过程不容易控制,强烈建议 Engine.dispose() 只有在签入所有已签出的连接或从其池中取消关联后才调用。

对于受 Engine 对象使用连接池是为了完全禁用池。这通常只会对新连接的使用产生适度的性能影响,这意味着当一个连接被签入时,它将完全关闭,而不会保留在内存中。见 切换池实现 有关如何禁用池的指南。

使用线程本地执行策略

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

1.3 版后已移除: “threadlocal”引擎策略已被弃用,将在将来的版本中删除。

这种策略是为一种特殊的使用模式而设计的,这种模式通常被认为是遗留模式。它有 无冲击 关于SQLAlchemy组件或应用程序的“线程安全”。使用ORM时也不应使用它 Session 对象,作为 Session 它本身表示一个正在进行的事务,本身处理维护连接和事务性资源的工作。

有可能 threadlocal 实现如下:

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

以上 Engine 现在将获得 Connection 使用从线程局部变量派生的连接资源 Engine.execute()Engine.contextual_connect() 被称为。只要引用了该连接资源,就可以维护该连接资源,从而允许应用程序的多个点在使用无连接执行时共享事务::

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() 获取的方法 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()

访问 Connection 绑定到线程本地作用域,调用 Engine.contextual_connect() ::

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

调用 close() 在“上下文”连接上没有 release 它的资源,直到该资源的所有其他用途也被关闭,包括回滚或提交任何正在进行的事务。

使用原始DBAPI连接

有些情况下,SQLAlchemy在访问某些 DBAPI 函数,例如调用存储过程以及处理多个结果集。在这些情况下,直接处理原始DBAPI连接也同样有利。

访问原始DBAPI连接的最常见方法是从已经存在的 Connection 直接对象。使用 Connection.connection 属性:

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

这里的DBAPI连接实际上是一个“代理”的原始连接池,但是这是一个在大多数情况下可以忽略的实现细节。因为DBAPI连接仍然包含在拥有的范围内 Connection 对象,最好利用 Connection 对象,用于大多数功能,如事务控制以及调用 Connection.close() 方法;如果直接在DBAPI连接上执行这些操作,则 Connection 将不知道这些状态变化。

克服由拥有者维护的DBAPI连接所施加的限制。 Connection ,DBAPI连接也可用,无需获取 Connection 首先,使用 Engine.raw_connection() 方法 Engine ::

dbapi_conn = engine.raw_connection()

这个DBAPI连接和以前一样也是一个“代理”形式。这种代理的目的现在很明显,当我们调用 .close() 此连接的方法,DBAPI连接通常不是实际关闭的,而是 released 返回引擎的连接池:

dbapi_conn.close()

尽管SQLAlchemy将来可能会为更多的DBAPI用例添加内置模式,但由于这些情况往往很少需要,并且它们在很大程度上取决于使用中的DBAPI类型,所以在任何情况下,直接DBAPI调用模式总是存在于需要的情况下。

以下是DBAPI连接的一些方法。

调用存储过程

对于具有特殊语法或参数问题的存储过程,DBAPI级别 callproc 可用于:

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

多个结果集

通过使用 nextset 方法:

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. 包应该有一个包含方言类的模块,该模块通常是 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://") .

在进程中注册方言

SQLAlchemy还允许在当前进程中注册方言,而不需要单独安装。使用 register() 功能如下:

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

以上将对 create_engine("mysql+foodialect://") 并加载 MyMySQLDialect 类从 myapp.dialect 模块。

连接/引擎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语句以及 ClauseElementCompiledDefaultGenerator 对象。提供了一个 begin() 返回方法 Transaction 对象。

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

连接对象表示从连接池签出的单个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() 方法。

begin()

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

返回的对象是 Transaction . 此对象表示事务的“范围”,当 Transaction.rollback()Transaction.commit() 方法被调用。

嵌套调用 begin() 在同一个 Connection 将返回新 Transaction 表示封闭事务范围内的模拟事务的对象,即:

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

调用 Transaction.commit() 只有通过最外层调用时才有效果 Transaction 对象,尽管 Transaction.rollback() 任何一种方法 Transaction 对象将回滚事务。

参见

Connection.begin_nested() -使用保存点

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

Engine.begin() - context manager available from Engine

begin_nested()

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

返回的对象是 NestedTransaction .

嵌套事务需要基础数据库中的保存点支持。层次结构中的任何事务都可以 commitrollback 但是,最外层的事务仍然控制整个 commitrollback 一个整体的交易。

begin_twophase(xid=None)

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

返回的对象是 TwoPhaseTransaction 除了提供的方法外, Transaction ,还提供 prepare() 方法。

参数

xid -- 两阶段事务ID。如果未提供,将生成随机ID。

close()

关闭此 Connection .

这将导致底层数据库资源的发布,即内部引用的DBAPI连接。DBAPI连接通常恢复到保持连接的状态。 Pool 被引用 Engine 产生了这个 Connection . DBAPI连接上存在的任何事务状态也会通过DBAPI连接无条件释放 rollback() 方法,无论 Transaction 与此相关的未解决对象 Connection .

close() 被称为 Connection 永久处于关闭状态,不允许进一步操作。

closed

如果此连接已关闭,则返回true。

connect()

返回此的分支版本 Connection .

这个 Connection.close() 返回的方法 Connection 可以叫这个 Connection 将保持打开状态。

这种方法提供了使用对称性 Engine.connect() 包括用于上下文管理器。

connection

此连接管理的基础DB-API连接。

default_isolation_level

分配给此的默认隔离级别 Connection .

这是隔离级别设置, Connection 第一次通过 Engine.connect() 方法。此级别在 Connection.execution_options.isolation_level 用于更改PER上的设置 -Connection 基础。

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

0.9.9 新版功能.

detach()

将基础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连接将被逐字关闭,不会返回到其原始池。

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

execute(object_, *multiparams, **params)

执行SQL语句构造并返回 ResultProxy .

参数
  • object -- 要执行的语句。可能是: 普通字符串 任何 ClauseElement 构造,它也是 Executable ,比如 select() 构造 * a FunctionElement, such as that generated by func, will be automatically wrapped in a SELECT statement, which is then executed. * 一 DDLElement 对象 * a DefaultGenerator object * 一 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" ) In the case that a plain SQL string is passed, and the underlying DBAPI accepts positional bind parameters, a collection of tuples or individual values in * 可以传递多路径::conn.execute(“insert into table(id,value,value)”值(??),(1,“v1”),(2,“v2”))conn.execute(“insert into table(id,value)values(?)?),1,“v1”)注:使用问号“?”或者其他符号取决于DBAPI所接受的“paramStyle”,它可以是“qmark”、“named”、“pyformat”、“format”、“numeric”中的任何一个。见 pep-249 有关ParamStyle的详细信息。要以DBAPI不可知的方式执行使用绑定参数的文本SQL语句,请使用 text() 构造。

execution_options(**opt)

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

方法返回此的副本 Connection 它引用相同的基础DBAPI连接,但也定义了给定的执行选项,这些选项将在调用 execute() . 作为新的 Connection 引用相同的基础资源,通常最好确保立即丢弃副本,这在以下情况下是隐式的:

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

注意,任何键/值都可以传递给 Connection.execution_options() ,它将存储在 _execution_options 字典 Connection . 例如,它适用于最终用户方案与事件侦听器通信。

当前由SQLAlchemy本身识别的关键字包括下面列出的所有关键字 Executable.execution_options() 以及其他特定于 Connection .

参数
  • autocommit -- 可用于:连接,语句。如果为true,则在以“自动提交”模式执行时(即在连接上未开始显式事务时),将在执行后调用提交。注意,默认情况下,DBAPI连接总是在事务中——SQLAlchemy使用应用于不同类型语句的规则来确定是否调用commit以提供其“autocommit”功能。通常,所有的insert/update/delete语句以及create/drop语句都启用了autocommit行为;select构造不启用。当调用需要提交(通常在调用存储过程等时)且未进行显式事务的Select或其他特定SQL构造时,请使用此选项。

  • compiled_cache -- 在:连接上可用。字典在哪里 CompiledConnection 将子句表达式编译为 Compiled 对象。用户有责任管理此字典的大小,其中包含与方言、子句元素、插入或更新的值或集合子句中的列名对应的键,以及插入或更新语句的“批处理”模式。本词典的格式在将来的版本中不一定保持不变。注意,ORM使用自己的“已编译”缓存进行一些操作,包括刷新操作。ORM使用的缓存在内部取代此处指定的缓存字典。

  • isolation_level -- 可供选择: Connection . 为此的生命周期设置事务隔离级别 Connection 对象(对象) not 基础DBAPI连接,在终止时将级别重置为其原始设置。 Connection 对象)。有效值包括 create_engine.isolation_level 传递给的参数 create_engine() . 这些级别是半数据库特定的;有关有效级别,请参阅各个方言文档。请注意,此选项在源站的生命周期内必然会影响基础DBAPI连接 Connection ,而不是每次执行。只有将基础DBAPI连接返回到连接池,即 Connection.close() 方法被调用。…警告:: isolation_level 执行选项应该 not 当事务已经建立时使用,即 Connection.begin() 已调用方法或类似方法。数据库无法更改正在进行的事务的隔离级别,不同的dbapis和/或sqlachemy方言可能隐式回滚或提交事务,或者根本不影响连接。…versionChanged::0.9.9当 isolation_level 执行选项在事务启动后使用 Connection.begin() 或类似的。…注:: isolation_level 如果 Connection 无效,例如通过 Connection.invalidate() 方法,或者如果发生断开错误。失效后生成的新连接不会自动重新应用隔离级别。…参阅: create_engine.isolation_level -设置 Engine 隔离级别 Connection.get_isolation_level() -查看当前级别 SQLite Transaction Isolation PostgreSQL Transaction Isolation MySQL Transaction Isolation SQL Server Transaction Isolation 设置事务隔离级别 -为ORM

  • no_parameters -- 什么时候? True 如果最终参数列表或字典完全为空,则将调用光标上的语句 cursor.execute(statement) ,根本不传递参数集合。一些DBAPI(如psycopg2和mysql python)仅在存在参数时才将百分号视为重要的符号;此选项允许代码生成包含百分号(可能还有其他字符)的SQL,这些百分号与DBAPI是否执行它或是否通过管道传输到稍后由命令行工具调用的脚本无关。

  • stream_results -- 可用于:连接,语句。如果可能,向方言指示结果应“流式”而不是预缓冲。这是许多DBAPI的限制。该标志目前只被psycopg2、mysqldb和pymysql方言理解。

  • schema_translate_map -- 提供:连接,引擎。将架构名称映射到架构名称的字典,该字典将应用于 Table.schema 各元素 Table 当SQL或DDL表达式元素编译为字符串时遇到;将根据原始名称的映射中的存在来转换生成的架构名称。…版本已添加::1.1..参阅: 模式名称的翻译

get_execution_options()

获取将在执行期间生效的非SQL选项。

1.3 新版功能.

get_isolation_level()

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

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

此属性通常会执行实时SQL操作以获取当前隔离级别,因此返回的值是基础DBAPI连接的实际级别,而不管如何设置此状态。相比于 Connection.default_isolation_level 访问器,返回方言级别设置而不执行SQL查询。

0.9.9 新版功能.

in_transaction()

如果事务正在进行,则返回true。

info

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

这里的数据将与DBAPI连接一起使用,包括在它返回到连接池并在随后的实例中再次使用之后。 Connection .

invalidate(exception=None)

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

基本DBAPI连接实际上是关闭的(如果可能的话),并被丢弃。它的源连接池通常会延迟地创建一个新连接来替换它。

下次使用时(其中“使用”通常指使用 Connection.execute() 方法或类似方法),此 Connection 将尝试使用 Pool 作为连接源(例如“重新连接”)。

如果交易正在进行(例如 Connection.begin() 方法)当 Connection.invalidate() 方法在dbapi级别被调用,当dbapi连接关闭时,与此事务关联的所有状态都将丢失。这个 Connection 将不允许重新连接继续,直到 Transaction 对象结束,方法是调用 Transaction.rollback() 方法;在此之前,继续使用 Connection 将提高 InvalidRequestError . 这是为了防止应用程序意外地继续正在进行的事务操作,尽管事务由于无效而丢失。

这个 Connection.invalidate() 方法和自动失效一样,将在连接池级别调用 PoolEvents.invalidate() 事件。

invalidated

如果此连接无效,则返回true。

run_callable(callable_, *args, **kwargs)

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

给定的 * ARGS和 * *Kwargs在 Connection 争论。

这个函数,以及 Engine.run_callable() ,允许使用 ConnectionEngine 对象,不需要知道正在处理哪个对象。

scalar(object_, *multiparams, **params)

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

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

schema_for_object = <sqlalchemy.sql.schema._SchemaTranslateMap object>

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

用于 TableSequence 以及类似的对象,并考虑到 Connection.execution_options.schema_translate_map 参数。

1.1 新版功能.

transaction(callable_, *args, **kwargs)

在事务边界内执行给定的函数。

函数通过此 Connection 作为第一个参数,后跟给定的 * ARGS和 * *KWARG,例如:

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() - engine-level version of Connection.transaction()

class sqlalchemy.engine.Connectable

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

的两个实现 ConnectableConnectionEngine .

Connectable还必须实现引用 Dialect 实例。

connect(**kwargs)

返回A Connection 对象。

根据上下文,这可能是 self 如果此对象已经是 Connection 或新采购的 Connection 如果此对象是 Engine .

contextual_connect(*arg, **kw)

返回A Connection 对象,它可能是正在进行的上下文的一部分。

1.3 版后已移除: 这个 Engine.contextual_connect()Connection.contextual_connect() 方法已弃用。此方法是线程本地引擎策略的产物,也将被弃用。对于来自的显式连接 Engine 使用 Engine.connect() 方法。

根据上下文,这可能是 self 如果此对象已经是 Connection 或新采购的 Connection 如果此对象是 Engine .

create(entity, **kwargs)

为给定的架构实体发出CREATE语句。

0.7 版后已移除: 这个 Connectable.create() 方法已弃用,将在将来的版本中删除。请使用 .create() 特定模式对象上的方法以发出DDL序列,包括 Table.create()Index.create()MetaData.create_all() .

drop(entity, **kwargs)

为给定的架构实体发出DROP语句。

0.7 版后已移除: 这个 Connectable.drop() 方法已弃用,将在将来的版本中删除。请使用 .drop() 特定模式对象上的方法以发出DDL序列,包括 Table.drop()Index.drop()MetaData.drop_all() .

execute(object_, *multiparams, **params)

执行给定的构造并返回 ResultProxy .

scalar(object_, *multiparams, **params)

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

执行后将关闭基础光标。

class sqlalchemy.engine.CreateEnginePlugin(url, kwargs)

一组钩子,用于增强 Engine 基于URL中入口点名称的对象。

目的 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")

或者, create_engine.plugins" argument may be passed as a list to :func: .创建引擎:

engine = create_engine(
  "mysql+pymysql://scott:tiger@localhost/test",
  plugins=["myplugin"])

1.2.3 新版功能: 插件名称也可以指定为 create_engine() 作为清单

这个 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() 钩子。在这个钩子中,可以对引擎进行额外的更改,最典型的是涉及事件设置(例如,在 核心事件

1.1 新版功能.

__init__(url, kwargs)

构建新的 CreateEnginePlugin .

插件对象在每次调用 create_engine() . 单一的 Engine 将传递给 CreateEnginePlugin.engine_created() 与此URL对应的方法。

参数
  • url -- 这个 URL 对象。插件应该检查它在这里需要什么,并从 URL.query 收集。URL也可以以任何其他方式就地修改。

  • kwargs -- 传递给:func`.create_engine`的关键字参数。插件可以在适当的位置读取和修改这个字典,以影响用于创建引擎的最终参数。它还应该从字典中删除它的自定义参数。

engine_created(engine)

接收 Engine 对象完全构造后。

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

handle_dialect_kwargs(dialect_cls, dialect_args)

解析和修改方言Kwargs

handle_pool_kwargs(pool_cls, pool_args)

解析和修改池Kwargs

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

基地: sqlalchemy.engine.Connectablesqlalchemy.log.Identified

连接一个 PoolDialect 一起提供数据库连接和行为的源。

Engine 对象是使用 create_engine() 功能。

begin(close_with_result=False)

返回一个上下文管理器 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 操作完成后将关闭。当设置为 True ,表示 Connection 处于“一次性”模式,其中 ResultProxy 第一次调用返回 Connection.execute() 将关闭 Connection 当那 ResultProxy 已耗尽所有结果行。

参见

Engine.connect() -获得A Connection 从一个 Engine .

Connection.begin() -启动一个 Transaction 对于一个特定的 Connection .

connect(**kwargs)

返回一个新的 Connection 对象。

这个 Connection 对象是在内部使用DBAPI连接以便与数据库通信的外观。此连接是从连接保持中获得的 Pool 引用人: Engine . 当 close() 方法 Connection 对象,然后将基础DBAPI连接返回到连接池,在随后的对 connect() .

contextual_connect(close_with_result=False, **kwargs)

返回A Connection 对象,它可能是某些正在进行的上下文的一部分。

1.3 版后已移除: 这个 Engine.contextual_connect() 方法已弃用。此方法是线程本地引擎策略的产物,也将被弃用。对于来自的显式连接 Engine 使用 Engine.connect() 方法。

默认情况下,此方法与 Engine.connect() . 亚类 Engine 可以重写此方法以提供上下文行为。

参数

close_with_result -- 如果是真的,第一个 ResultProxy 创建的 Connection 将调用 Connection.close() 当任何挂起的结果行用完时,该连接的方法。这用于提供由 Engine.execute() 方法。

dispose()

释放此使用的连接池 Engine .

这有完全关闭所有 当前已签入 数据库连接。仍被签出的连接将 not 关闭,但它们将不再与此关联 Engine 因此,当它们单独关闭时,最终 Pool 它们与之相关联的将被垃圾收集,并且如果在签入时尚未关闭,它们将被完全关闭。

在释放旧连接池后立即创建新连接池。与所有SQLAlchemy连接池一样,只要 Engine 不再使用,不会建立新连接。

参见

引擎处理

driver

驱动程序名称 Dialect 在使用中 Engine .

execute(statement, *multiparams, **params)

执行给定的构造并返回 ResultProxy .

这些参数与 Connection.execute() .

这里,A Connection 是使用 contextual_connect() 方法,以及使用该连接执行的语句。归还的人 ResultProxy 标记为当 ResultProxy 已耗尽并且其基础光标已关闭, Connection 在此创建的数据库也将关闭,这将允许其关联的DBAPI连接资源返回到连接池。

execution_options(**opt)

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

归还的人 Engine 与原件有关 Engine 因为它共享相同的连接池和其他状态:

  • 这个 Pool 新使用 Engine 是同一个实例。这个 Engine.dispose() 方法将替换父引擎以及此引擎的连接池实例。

  • 事件侦听器是“级联”的,也就是说,新的 Engine 继承父级的事件,新事件可以与新事件关联 Engine 个别地。

  • 日志配置和日志记录名称从父级复制 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")

上面, shard1 引擎作为工厂 Connection 将包含执行选项的对象 shard_id=shard1shard2 将生产 Connection 包含执行选项的对象 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

参见

Connection.execution_options() -更新上的执行选项 Connection 对象。

Engine.update_execution_options() -更新给定的执行选项 Engine 就位。

Engine.get_execution_options()

get_execution_options()

获取将在执行期间生效的非SQL选项。

has_table(table_name, schema=None)

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

参见

带检查器的细颗粒反射 -使用 Inspector 接口。

quoted_name -用于传递引用信息和模式标识符。

name

字符串名称 Dialect 在使用中 Engine .

raw_connection(_connection=None)

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

返回的对象是正在使用的底层驱动程序所使用的DBAPI连接对象的代理版本。对象将具有与实际DBAPI连接相同的行为,除了 close() 方法将导致连接返回池,而不是实际关闭。

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

run_callable(callable_, *args, **kwargs)

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

给定的 * ARGS和 * *Kwargs在 Connection 争论。

这个函数,以及 Connection.run_callable() ,允许使用 ConnectionEngine 对象,不需要知道正在处理哪个对象。

scalar(statement, *multiparams, **params)

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

执行后将关闭基础光标。

schema_for_object = <sqlalchemy.sql.schema._SchemaTranslateMap object>

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

用于 TableSequence 以及类似的对象,并考虑到 Connection.execution_options.schema_translate_map 参数。

1.1 新版功能.

table_names(schema=None, connection=None)

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

参数
  • schema -- 可选,从非默认架构中检索名称。

  • connection -- 可选,使用指定的连接。默认为 contextual_connect 为此 Engine .

transaction(callable_, *args, **kwargs)

在事务边界内执行给定的函数。

函数通过 Connection 新购自 Engine.contextual_connect() 作为第一个参数,后跟给定的 * ARGS和 * *克沃斯。

例如。::

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() - connection-level version of Engine.transaction()

update_execution_options(**opt)

更新此的默认执行选项字典 Engine .

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

class sqlalchemy.engine.ExceptionContext

封装有关正在进行的错误条件的信息。

此对象只存在于传递给 ConnectionEvents.handle_error() 事件,支持一个接口,该接口可以在不向后不兼容的情况下进行扩展。

0.9.7 新版功能.

chained_exception = None

异常链中的前一个处理程序返回的异常(如果有)。

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

可能没有。

connection = None

这个 Connection 在异常期间使用。

此成员存在,除非第一次连接时出现故障。

cursor = None

DBAPI光标对象。

可能没有。

engine = None

这个 Engine 在异常期间使用。

即使在第一次连接失败的情况下,此成员也应始终存在。

1.0.0 新版功能.

execution_context = None

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

这适用于语句执行操作,但不适用于事务开始/结束等操作。当异常在 ExecutionContext 可以构造。

请注意 ExceptionContext.statementExceptionContext.parameters 成员可以表示不同于 ExecutionContext ,可能在以下情况下 ConnectionEvents.before_cursor_execute() 事件或类似事件修改了要发送的语句/参数。

可能没有。

invalidate_pool_on_disconnect = True

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

ConnectionEvents.handle_error() 事件的作用是,在断开连接期间,池中的全部连接集合不会失效;只有作为错误主题的当前连接才会真正失效。

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

1.0.3 新版功能.

is_disconnect = None

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

此标志在 ConnectionEvents.handle_error() 处理程序。

SQLAlchemy将遵从此标志,以确定连接是否应在随后失效。也就是说,通过分配给该标志,可以通过更改该标志来调用或阻止“断开”事件,从而导致连接和池无效。

original_exception = None

捕获的异常对象。

此成员始终存在。

parameters = None

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

可能没有。

sqlalchemy_exception = None

这个 sqlalchemy.exc.StatementError 它包装了原始数据,如果事件没有规避异常处理,则将引发异常处理。

可能是none,因为并非所有异常类型都由sqlAlchemy包装。对于DBAPI级别的异常(它是DBAPI错误类的子类),此字段将始终存在。

statement = None

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

可能没有。

class sqlalchemy.engine.NestedTransaction(connection, parent)

基地: sqlalchemy.engine.Transaction

表示“嵌套”或保存点事务。

一个新的 NestedTransaction 可使用 Connection.begin_nested() 方法。

接口与 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 还处理结果列数据的后处理,使用 TypeEngine 对象,从生成此结果集的原始SQL语句中引用。

_cursor_description()

可以被子类重写。

_process_row

RowProxy 的别名

_soft_close()

软关闭此 ResultProxy .

这将释放所有dbapi光标资源,但从语义的角度来看,会让resultProxy“打开”,这意味着fetchxxx()方法将继续返回空结果。

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

  • 所有结果行都使用fetchxxx()方法耗尽。

  • cursor.description为“无”。

这种方法是 不公开 但为了澄清所使用的“自动关闭”过程而记录在案。

1.0.0 新版功能.

close()

关闭此ResultProxy。

这将关闭与语句执行相对应的基础DBAPI光标(如果仍存在)。注意,当 ResultProxy 排出所有可用的行。 ResultProxy.close() 通常是可选方法,除非在丢弃 ResultProxy 还有其他行等待提取。

如果结果是 connectionless execution ,基础 Connection 对象也被关闭,其中 releases DBAPI连接资源。

调用此方法后,调用将引发 ResourceClosedError 以后使用时。

在 1.0.0 版更改: - the ResultProxy.close() method has been separated out from the process that releases the underlying DBAPI cursor resource. The "auto close" feature of the Connection now performs a so-called "soft close", which releases the underlying DBAPI cursor, but allows the ResultProxy to still behave as an open-but-exhausted result set; the actual ResultProxy.close() method is never called. It is still safe to discard a ResultProxy that has been fully exhausted without calling this method.

fetchall()

获取所有行,就像db-api一样 cursor.fetchall() .

在所有行用完之后,将释放底层DBAPI光标资源,并且可以安全地丢弃该对象。

后续调用 ResultProxy.fetchall() 将返回空列表。后 ResultProxy.close() 方法被调用,该方法将引发 ResourceClosedError .

在 1.0.0 版更改: -添加了“软关闭”行为,允许在调用 ResultProxy.close() 方法。

fetchmany(size=None)

获取许多行,就像db-api一样 cursor.fetchmany(size=cursor.arraysize) .

在所有行用完之后,将释放底层DBAPI光标资源,并且可以安全地丢弃该对象。

调用 ResultProxy.fetchmany() 所有行用完后,将返回一个空列表。后 ResultProxy.close() 方法被调用,该方法将引发 ResourceClosedError .

在 1.0.0 版更改: -添加了“软关闭”行为,允许在调用 ResultProxy.close() 方法。

fetchone()

获取一行,就像db-api一样 cursor.fetchone() .

在所有行用完之后,将释放底层DBAPI光标资源,并且可以安全地丢弃该对象。

调用 ResultProxy.fetchone() 当所有的行都用完后,将返回 None . 后 ResultProxy.close() 方法被调用,该方法将引发 ResourceClosedError .

在 1.0.0 版更改: -添加了“软关闭”行为,允许在调用 ResultProxy.close() 方法。

first()

获取第一行,然后无条件关闭结果集。

如果不存在行,则返回“无”。

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

inserted_primary_key

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

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

这只适用于单行 insert() 未显式指定的构造 Insert.returning() .

请注意,指定server_default子句的主键列或其他列不符合“autoincrement”列的条件(请参阅中的注释 Column ,并且是使用数据库端默认值生成的,将在此列表中显示为 None 除非后端支持“返回”,并且在启用“隐式返回”的情况下执行insert语句。

加薪 InvalidRequestError 如果执行的语句不是已编译的表达式构造或不是insert()构造。

is_insert

如果这是真的 ResultProxy 是执行已编译的表达式语言的结果 expression.insert() 构造。

如果是真的,这意味着 inserted_primary_key 属性是可访问的,假定语句不包含用户定义的“返回”构造。

keys()

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

last_inserted_params()

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

加薪 InvalidRequestError 如果执行的语句不是已编译的表达式构造或不是insert()构造。

last_updated_params()

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

加薪 InvalidRequestError 如果执行的语句不是已编译的表达式构造或不是update()构造。

lastrow_has_defaults()

返回 lastrow_has_defaults() 从底层 ExecutionContext .

ExecutionContext 有关详细信息。

lastrowid

返回dbapi光标上的“lastrowid”访问器。

这是一种特定于DBAPI的方法,仅对支持它的后端和适当的语句有效。它的行为在后端不一致。

在使用insert()表达式构造时,通常不需要使用此方法;在 inserted_primary_key 属性为新插入的行提供主键值的元组,而不考虑数据库后端。

next()

实现next()协议。

1.2 新版功能.

postfetch_cols()

返回 postfetch_cols() 从底层 ExecutionContext .

ExecutionContext 有关详细信息。

加薪 InvalidRequestError 如果执行的语句不是已编译的表达式构造,或者不是insert()或update()构造。

prefetch_cols()

返回 prefetch_cols() 从底层 ExecutionContext .

ExecutionContext 有关详细信息。

加薪 InvalidRequestError 如果执行的语句不是已编译的表达式构造,或者不是insert()或update()构造。

returned_defaults

返回使用 ValuesBase.return_defaults() 特征。

该值是的实例 RowProxyNone 如果 ValuesBase.return_defaults() 未使用或后端不支持返回。

0.9.0 新版功能.

returns_rows

如果这是真的 ResultProxy 返回行。

也就是说,如果调用这些方法是合法的 fetchone()fetchmany() fetchall() .

rowcount

返回此结果的“行数”。

“rowcount”报告行数 匹配的 按UPDATE或DELETE语句的WHERE条件。

注解

注意事项 ResultProxy.rowcount

  • 此属性返回行数 匹配的 ,这不一定与实际的行数相同 被改进的 -例如,如果给定的设置值与行中已有的设置值相同,则UPDATE语句可能不会对给定行进行净更改。这样的行将被匹配,但不会被修改。在具有这两种样式(如mysql)的后端,默认情况下会将rowcount配置为在所有情况下返回匹配计数。

  • ResultProxy.rowcountonly 与更新或删除语句一起使用。与python dbapi所说的相反,它确实做到了 not 返回select语句结果中可用的行数,因为dbapis在未缓冲行时不支持此功能。

  • ResultProxy.rowcount 可能不是所有方言都能完全实现。尤其是,大多数DBAPI不支持来自ExecuteMany调用的聚合行计数结果。这个 ResultProxy.supports_sane_rowcount()ResultProxy.supports_sane_multi_rowcount() 如果已知支持每种用法,则方法将从方言报告。

  • 使用RETURN的语句可能不会返回正确的行数。

scalar()

获取第一行的第一列,并关闭结果集。

如果不存在行,则返回“无”。

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

supports_sane_multi_rowcount()

返回 supports_sane_multi_rowcount 来自方言。

ResultProxy.rowcount 背景。

supports_sane_rowcount()

返回 supports_sane_rowcount 来自方言。

ResultProxy.rowcount 背景。

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

基地: sqlalchemy.engine.BaseRowProxy

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

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

has_key(key)

如果此rowproxy包含给定的键,则返回true。

items()

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

keys()

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

class sqlalchemy.engine.Transaction(connection, parent)

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

这个 Transaction 对象是通过调用 begin() 方法 Connection ::

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() 方法以控制事务边界。它还实现了一个上下文管理器接口,以便 with 语句可与 Connection.begin() 方法:

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

事务对象是 not 线程安全。

close()

关闭此 Transaction .

如果此事务是begin/commit嵌套中的基本事务,则该事务将回滚()。否则,方法返回。

这用于取消事务,而不影响封闭事务的范围。

commit()

提交此 Transaction .

rollback()

回滚这个 Transaction .

class sqlalchemy.engine.TwoPhaseTransaction(connection, xid)

基地: sqlalchemy.engine.Transaction

表示两阶段事务。

一个新的 TwoPhaseTransaction 可使用 Connection.begin_twophase() 方法。

接口与 Transaction 加上 prepare() 方法。

prepare()

准备好这个 TwoPhaseTransaction .

准备之后,可以提交事务。