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

SQLAlchemy 1.1文档

使用引擎和连接

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

基本用法

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游标的接口基本兼容的接口。The DBAPI cursor will be closed by the ResultProxy when all of its result rows (if any) are exhausted. A ResultProxy that returns no rows, such as that of an UPDATE statement (without any returned rows), releases cursor resources immediately upon construction.

When the close() method is called, the referenced DBAPI connection is released to the connection pool. 从数据库本身的角度来看,没有任何东西实际上是“封闭的”,假设使用共享池。池机制在DBAPI连接上发出rollback()调用,以便删除任何事务状态或锁,并且连接已准备就绪,可用于下次使用。

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

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

Where above, the execute() method acquires a new Connection on its own, executes the statement with that object, and returns the ResultProxy. In this case, the ResultProxy contains a special flag known as close_with_result, which indicates that when its underlying DBAPI cursor is closed, the Connection object itself is also closed, which again returns the DBAPI connection to the connection pool, releasing transactional resources.

如果ResultProxy可能有剩余的行,则可以指示明确地关闭其资源:

result.close()

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

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

使用事务

注意

本节介绍如何在直接使用EngineConnection对象时使用事务。当使用SQLAlchemy ORM时,用于事务控制的公共API是通过Session对象在内部使用Transaction对象的。请参阅Managing Transactions了解更多信息。

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

事务块的嵌套

The Transaction object also handles “nested” behavior by keeping track of the outermost begin/commit pair. In this example, two functions both issue a transaction on a Connection, but only the outermost Transaction object actually takes effect when it is committed.

# 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_bWhen method_b calls connection.begin(), it just increments a counter that is decremented when it calls commit(). 如果method_amethod_b调用rollback(),则整个事务将被回滚。method_a调用commit()方法之前,事务不会被提交。这种“嵌套”行为允许创建功能,“保证”一个交易将被使用,如果一个不可用,但会自动参与封闭交易(如果存在的话)。

了解自动提交

前面的事务示例演示了如何使用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()方法。这是使用Engineexecute()方法说明的:

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

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

给定一个表格如下:

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表达式传递给Connectionexecute()方法:

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

显式,无连接执行将表达式传递给Engineexecute()方法:

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.bindEngineMetaData对象相关联。The select() construct produced from the Table object has a method execute(), which will search for an Engine that’s “bound” to the Table.

总体而言,“绑定元数据”的使用有三个一般效果:

注意

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

在存在多个Engine对象的应用程序中,每个对象都与一组表(vertical sharding)逻辑关联,可以使用“绑定的元数据”个别Table可以自动引用适当的Engine特别是ORM通过Session对象支持这种方式,作为将Table对象与适当的Engine关联的一种手段,作为使用绑定参数直接被Session接受。

然而,“隐式执行”技术并不适合与ORM一起使用,因为它绕过了Session维护的事务上下文。

Overall, in the vast majority of cases, “bound metadata” and “implicit execution” are not useful. 虽然“绑定元数据”在ORM配置方面有一定的实用性,但“隐式执行”是一种非常古老的使用模式,在大多数情况下,这种使用模式比有用的模式更容易混淆,并且不鼓励使用它。这两种模式似乎都鼓励在应用程序设计中过度使用权宜的“捷径”,从而导致以后出现问题。

现代的SQLAlchemy的使用,特别是ORM,在任何时候都在交易的上下文中强调工作。 “隐式执行”(implicit execution)概念使得将语句执行与特定事务相关联的工作更加困难。特定SQL语句上的Executable.execute()方法通常意味着执行不是任何特定事务的一部分,这通常不是所期望的效果。

在两个“无连接”的例子中,Connection在幕后创建;由execute()调用返回的ResultProxy引用用于发出SQL语句的ConnectionResultProxy关闭时,底层的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的“架构”是NoneConnection.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参数影响从TableSequence对象派生的SQL表达式语言生成的所有DDL和SQL结构。It does not impact literal string SQL used via the expression.text() construct nor via plain strings passed to Connection.execute().

在模式名称直接来源于TableSequence的情况下,该功能仅在中生效它不会影响字符串模式名称直接传递的方法。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.

版本1.1中的新功能

引擎处置

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

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

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

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

  • 当一个程序想要释放连接池中保留的任何剩余的检入连接,并且期望不再连接到该数据库以备将来的操作。
  • When a program uses multiprocessing or fork(), and an Engine object is copied to the child process, Engine.dispose() should be called so that the engine creates brand new database connections local to that fork. 数据库连接通常不跨越进程边界而行
  • 在测试套件或多租户方案中,可能会创建和处理许多特定的,短暂的Engine对象。

在引擎被丢弃或垃圾收集时,被检出的连接不会被放弃,因为这些连接在应用程序的其他地方仍被强烈引用。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. Since this process is not easy to control, it is strongly recommended that Engine.dispose() is called only after all checked out connections are checked in or otherwise de-associated from their pool.

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

使用Threadlocal执行策略

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

注意

“threadlocal”功能通常是不鼓励的。它是为特定的使用模式而设计的,通常被认为是传统模式。It has no impact on the “thread safety” of SQLAlchemy components or one’s application. 当使用ORM Session对象时,它也不应该被使用,因为Session本身代表一个正在进行的事务,并且它自己处理维护连接和事务资源的工作。

启用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连接使用的食谱如下。

调用存储过程

对于具有特殊语法或参数关注的存储过程,可以使用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方法从原始DBAPI游标提供多个结果集支持:

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
"""

The above entrypoint would then be accessed as create_engine("mysql+foodialect://").

注册方言进行中

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

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

The above will respond to create_engine("mysql+foodialect://") and load the MyMySQLDialect class from the myapp.dialect module.

0.8版本中的新功能

连接/引擎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对象提供执行支持。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的一个实例。This object represents the “scope” of the transaction, which completes when either the Transaction.rollback() or Transaction.commit() method is called.

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

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() - use a SAVEPOINT

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

Engine.begin() - context manager available from Engine.

begin_nested T0> ( T1> ) T2> ¶ T3>

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

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

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

另见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. Any transactional state present on the DBAPI connection is also unconditionally released via the DBAPI connection’s rollback() method, regardless of any Transaction object that may be outstanding with regards to this Connection.

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

关闭 T0> ¶ T1>

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

连接 T0> ( T1> ) T2> ¶ T3>

返回此Connection的分支版本。

返回的Connection上的Connection.close()方法可以被调用,并且这个Connection

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

连接 T0> ¶ T1>

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

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查询。

New in version 0.9.9.

也可以看看

Connection.get_isolation_level() - view current level

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

Connection.execution_options.isolation_level - set per Connection isolation level

分离 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连接将被逐字地关闭并且不返回到其源池。

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

execute(object, *multiparams, **params)

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

参数:
  • 对象 -

    要执行的声明。可能是以下之一:

  • * 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所接受的“paramstyle”,其可以是“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构造不。调用SELECT或其他特定SQL构造(需要COMMIT时)(通常在调用存储过程等时)使用此选项,并且显式事务未处于进行中。
  • compiled_cache -

    可用于:连接。Connection将一个子句表达式编译成一个Compiled对象时,一个字典中的Compiled对象将被缓存。用户有责任管理该字典的大小,该字典将具有与方言,子句元素,INSERT或UPDATE的VALUES或SET子句中的列名相对应的键,以及用于INSERT或UPDATE语句。这个词典的格式不保证在未来的版本中保持不变。

    请注意,ORM使用自己的“编译”缓存来执行一些操作,包括刷新操作。ORM使用的缓存内部取代了这里指定的缓存字典。

  • isolation_level -

    适用于:Connection设置这个Connection对象(not)的生命周期的事务隔离级别,在该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()方法,或者发生断开连接错误。失效后产生的新连接将不会自动重新应用隔离级别。

  • 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中的新功能

get_isolation_level T0> ( T1> ) T2> ¶ T3>

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

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

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

New in version 0.9.9.

也可以看看

Connection.default_isolation_level - view default level

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

Connection.execution_options.isolation_level - set per Connection isolation level

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. The Connection will not allow a reconnection to proceed until the Transaction object is ended, by calling the Transaction.rollback() method; until that point, any attempt at continuing to use the Connection will raise an 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 tt> callable _* args** kwargs / T5> ¶ T6>

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

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

这个函数和Engine.run_callable()一起允许一个函数与一个ConnectionEngine对象一起运行,而不需要知道一个正在处理。

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

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

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

schema_for_object =< sqlalchemy.sql.schema._SchemaTranslateMap对象>

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

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

版本1.1中的新功能

事务 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的上下文中调用的。一旦成功,交易就承诺。如果引发异常,则在传播异常之前回滚该事务。

注意

The transaction() method is superseded by the usage of the Python with: statement, which can be used 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-level transactional context

Engine.transaction() - engine-level version of Connection.transaction()

class sqlalchemy.engine。 Connectable

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

Connectable的两个实现是ConnectionEngine

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

execute(object, *multiparams, **params)

执行给定的结构并返回一个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 __ urlkwargs

构建一个新的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.Connectablesqlalchemy.log.Identified

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

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

也可以看看:

Engine Configuration

Working with Engines and Connections

开始 T0> ( T1> close_with_result =假 T2> ) T3> ¶ T4>

返回一个上下文管理器,用Transaction建立Connection

例如。:

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被回滚。

The close_with_result flag is normally False, and indicates that the Connection will be closed when the operation is complete. 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对象。

The Connection object is a facade that uses a DBAPI connection internally in order to communicate with the database. 这个连接是从这个Engine引用的连接持有Pool获得的。Connection对象的close()方法被调用时,底层的DBAPI连接就会被返回到连接池中,并在随后的调用中被再次使用connect()

contextual_connect tt> 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是相同的实例。The Engine.dispose() method will replace the connection pool instance for the parent engine as well as this one.
  • 事件监听器是“级联的”,也就是说,新的Engine继承了父代的事件,新的事件可以与新的Engine分别关联。
  • 日志记录配置和日志记录名称是从父Engine复制的。

The intent of the Engine.execution_options() method is to implement “sharding” schemes where multiple Engine objects refer to the same connection pool, but are differentiated by options that would be consumed by a custom event:

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=None)

如果给定的后端具有给定名称的表,则返回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存取器。

run_callable tt> callable _* args** kwargs / T5> ¶ T6>

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

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

这个函数和Connection.run_callable()一起允许一个函数与一个ConnectionEngine对象一起运行,而不需要知道一个正在处理。

schema_for_object =< sqlalchemy.sql.schema._SchemaTranslateMap对象>

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

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

版本1.1中的新功能

table_names(schema=None, connection=None)

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

参数:
  • schema – Optional, retrieve names from a non-default schema.
  • connection – Optional, use a specified connection. 默认值是Enginecontextual_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的上下文中调用的。一旦成功,交易就承诺。如果引发异常,则在传播异常之前回滚该事务。

注意

The transaction() method is superseded by the usage of the Python with: statement, which can be used with Engine.begin():

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

也可以看看:

Engine.begin() - engine-level transactional context

Connection.transaction() - connection-level version of Engine.transaction()

update_execution_options T0> ( T1> **选择 T2> ) T3> ¶ T4>

更新此Engine的默认execution_options字典。

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

class sqlalchemy.engine。 ExceptionContext

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

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

新版本0.9.7.

chained_exception =无

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

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

可能是无。

连接 =无

异常期间使用的Connection

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

游标 =无

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,并且如果异常处理没有被事件绕过,将会被引发。

可能是None,因为并不是所有的异常类型都被SQLAlchemy封装。对于继承dbapi的Error类的DBAPI级异常,此字段将始终存在。

语句 =无

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

可能是无。

class sqlalchemy.engine.NestedTransaction(connection, parent)

基础: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。

这个方法是not public,但是为了阐明所使用的“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.

In the case of a result that is the product of connectionless execution, the underyling Connection object is also closed, which releases DBAPI connection resources.

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

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

使用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游标资源被释放,并且该对象可以被安全地丢弃。

Calls to ResultProxy.fetchone() after all rows have been exhausted will return None. After the ResultProxy.close() method is called, the method will raise ResourceClosedError.

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

第一 T0> ( T1> ) T2> ¶ T3>

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

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

After calling this method, the object is fully closed, e.g. the ResultProxy.close() method will have been called.

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中新增。

returns_rows T0> ¶ T1>

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

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

行计数 T0> ¶ T1>

返回这个结果的'rowcount'。

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

注意

有关ResultProxy.rowcount的注意事项:

  • This attribute returns the number of rows matched, which is not necessarily the same as the number of rows that were actually modified - an UPDATE statement, for example, may have no net change on a given row if the SET values given are the same as those present in the row already. 这样的一行可以匹配但不能修改。在具有两种样式(如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调用的聚合行计数结果。The ResultProxy.supports_sane_rowcount() and ResultProxy.supports_sane_multi_rowcount() methods will report from the dialect if each usage is known to be supported.
  • 使用RETURNING的语句可能不会返回正确的rowcount。
标量 T0> ( T1> ) T2> ¶ T3>

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

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

After calling this method, the object is fully closed, e.g. the ResultProxy.close() method will have been called.

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)

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

通过调用Connectionbegin()方法获取Transaction对象:

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对象。

除了prepare()方法之外,该接口与Transaction的接口相同。

制备 T0> ( T1> ) T2> ¶ T3>

准备这个TwoPhaseTransaction

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