SQLAlchemy 2.0未来（核心）¶

这个包包含了相对较少的过渡元素，以允许“2.0模式”在SQLAlchemy 1.4中发生。这里提供的主要对象是 Engine 和 Connection ，它们都是现有 Engine 和 Connection 对象的方法集更小，并且删除了“autocommit”。

在1.4系列中，通过传递 create_engine.future 旗到 create_engine() ：：

from sqlalchemy import create_engine
engine = create_engine("postgresql://user:pass@host/dbname", future=True)

类似地，对于ORM，启用ORM中的“未来”行为 Session 通过 Session.future 参数 Session 直接或通过 sessionmaker 班级：

from sqlalchemy.orm import sessionmaker

Session = sessionmaker(engine, future=True)

参见

迁移到Alchemy -SQLAlchemy 2.0系列简介

Object Name	Description
Connection	为打包的DB-API连接提供高级功能。
create_engine(arg, *kw)	创建新的 `Engine` 实例。
Engine	连接一个 `Pool` 和 `Dialect` 一起提供数据库连接和行为的源。
select(*entities)	构建新的 `Select` 使用2。x样式API。

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

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

这个 Connection 对象是通过调用 Engine.connect() 的方法。 Engine 对象，并为执行SQL语句和事务控制提供服务。

这是SQLAlchemy 2.0版本 的 Connection 班级。此对象的API和行为基本相同，但在行为上存在以下差异：

为结果返回的结果对象是 CursorResult 对象，该对象是 Result 。此对象的API和行为与 LegacyCursorResult 返回以供1.x样式使用。
对象有 Connection.commit() 和 Connection.rollback() 方法提交或回滚当前正在进行的事务（如果有）。
该对象具有“自动注册”行为，因此任何调用 Connection.execute() 将无条件启动一个可以使用上述方法控制的事务 Connection.commit() 和 Connection.rollback() 方法。
对象没有任何“自动提交”功能。在显式提交事务之前，任何SQL语句或DDL语句后面都不会有任何提交，或者通过 Connection.commit() 方法，或者如果连接正在提交的上下文管理器中使用，例如 Engine.begin() .
SAVEPOINT方法 Connection.begin_nested() 返回A NestedTransaction 与往常一样，保存点可以通过调用 NestedTransaction.commit() 或 NestedTransaction.rollback() 和以前一样。但是，这个保存点“事务”与由连接本身控制的事务没有关联；可以直接提交或回滚整个事务，这不会为保存点发出任何特殊指令（这通常会产生人们想要的效果）。
这个 Connection 对象不支持“分支”，这是一种将此连接引用为父连接的子“连接”使用模式。

类签名

class sqlalchemy.future.Connection (sqlalchemy.engine.Connection)

method sqlalchemy.future.Connection.begin()¶

在自动注册之前开始事务。

返回的对象是 RootTransaction 。此对象表示事务的“作用域”，当 Transaction.rollback() 或 Transaction.commit() 方法被调用。

这个 Connection.begin() 方法在SQLAlchemy 2.0中开始一个事务，通常在连接第一次用于执行语句时都将开始该事务。使用此方法的原因是调用 ConnectionEvents.begin() 事件，或根据上下文管理的块在连接签出范围内组织代码，例如：

with engine.connect() as conn:
    with conn.begin():
        conn.execute(...)
        conn.execute(...)

    with conn.begin():
        conn.execute(...)
        conn.execute(...)

上面的代码与下面的代码在行为上没有什么本质上的不同，下面的代码没有使用 Connection.begin() ；以下样式称为“随走随用”样式：

with engine.connect() as conn:
    conn.execute(...)
    conn.execute(...)
    conn.commit()

    conn.execute(...)
    conn.execute(...)
    conn.commit()

从数据库的角度来看 Connection.begin() Python的DBAPI不以任何方式发出底层DBAPI的连接或任何形式的DBAPI。

参见

处理事务和DBAPI - in the SQLAlchemy 1.4/2.0教程

Connection.begin_nested() -使用保存点

Connection.begin_twophase() -使用两阶段/XID交易

Engine.begin() - context manager available from Engine

method sqlalchemy.future.Connection.begin_nested()¶

开始嵌套事务(即保存点)并返回事务句柄。

返回的对象是 NestedTransaction .

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

如果外部 RootTransaction 不在此上 Connection ，使用“AutoBegin”创建一个新的。此外部事务可以使用“随用随用”风格使用来完成，方法是调用 Connection.commit() 或 Connection.rollback() 。

小技巧

的“自动开始”行为 Connection.begin_nested() 是特定于 2.0 style 使用；有关传统行为，请参见 Connection.begin_nested() 。

这个 NestedTransaction 保持独立于 Connection 对象本身。调用 Connection.commit() 或 Connection.rollback() 将始终影响实际包含的数据库事务本身，而不是保存点本身。提交数据库事务时，将清除已建立的任何SAVEPOINT，并提交其作用域内的数据更改。

参见

Connection.begin()

method sqlalchemy.future.Connection.close()¶

关闭此 Connection .

这也有召唤的作用 Connection.rollback() 如果有任何交易到位。

method sqlalchemy.future.Connection.commit()¶

提交当前正在进行的事务。

此方法提交当前事务（如果已启动）。如果没有启动任何事务，则假定连接处于非无效状态，则该方法无效。

交易开始于 Connection 当第一次执行语句时自动执行，或者 Connection.begin() 方法被调用。

注解

这个 Connection.commit() 方法仅作用于链接到的主数据库事务 Connection 对象。它不会对从中调用的保存点进行操作 Connection.begin_nested() 方法；若要控制保存点，请调用 NestedTransaction.commit() 上 NestedTransaction 由 Connection.begin_nested() 方法本身。

method sqlalchemy.future.Connection.execute(statement, parameters=None, execution_options=None)¶

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

参数

statement¶ --
要执行的语句。这始终是一个同时位于 ClauseElement 和 Executable 层次结构，包括：
- Select
- Insert, Update, Delete
- TextClause and TextualSelect
- DDL and objects which inherit from DDLElement
parameters¶ -- 将绑定到语句中的参数。这可以是参数名到值的字典，也可以是字典的可变序列（例如列表）。当传递字典列表时，底层语句执行将使用DBAPI cursor.executemany() 方法。当传递单个字典时，DBAPI cursor.execute() 方法。
execution_options¶ -- 执行选项的可选字典，它将与语句执行关联。此字典可以提供接受的选项的子集 Connection.execution_options() .

返回

一 Result 对象。

method sqlalchemy.future.Connection.rollback()¶

回滚当前正在进行的事务。

如果当前事务已启动，此方法将回滚当前事务。如果没有启动任何事务，则该方法无效。如果事务已启动且连接处于无效状态，则使用此方法清除该事务。

交易开始于 Connection 当第一次执行语句时自动执行，或者 Connection.begin() 方法被调用。

注解

这个 Connection.rollback() 方法仅作用于链接到的主数据库事务 Connection 对象。它不会对从中调用的保存点进行操作 Connection.begin_nested() 方法；若要控制保存点，请调用 NestedTransaction.rollback() 上 NestedTransaction 由 Connection.begin_nested() 方法本身。

method sqlalchemy.future.Connection.scalar(statement, parameters=None, execution_options=None)¶

执行SQL语句构造并返回标量对象。

此方法是调用 Result.scalar() 方法调用 Connection.execute() 方法。参数是等效的。

返回: 一个标量Python值，表示返回的第一行的第一列。

function sqlalchemy.future.create_engine(*arg, **kw)¶

创建新的 Engine 实例。

传递给的参数 create_engine() 传递给x的基本上是相同的 create_engine() 功能。不同的是，返回的对象是 Engine 它具有API的2.0版本。

class sqlalchemy.future.Engine(pool, dialect, url, logging_name=None, echo=None, query_cache_size=500, execution_options=None, hide_parameters=False)¶

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

这是SQLAlchemy 2.0版本 的 Engine .

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

参见

引擎配置

使用引擎和接头

类签名

class sqlalchemy.future.Engine (sqlalchemy.engine.Engine)

method sqlalchemy.future.Engine.begin()¶

返回A Connection 已开始事务的对象。

这种方法的使用与 Engine.connect() ，通常作为上下文管理器，它将在块结束时自动维护事务的状态，方法是调用 Connection.commit() 当块正常成功时，或 Connection.rollback() 当引发异常时，在向外传播异常之前：

with engine.begin() as connection:
    connection.execute(text("insert into table values ('foo')"))

参见

Engine.connect()

Connection.begin()

method sqlalchemy.future.Engine.connect()¶

返回一个新的 Connection 对象。

这个 Connection 充当Python上下文管理器，因此此方法的典型用法如下：

with engine.connect() as connection:
    connection.execute(text("insert into table values ('foo')"))
    connection.commit()

在上面，块完成后，连接被“关闭”，其底层DBAPI资源返回到连接池。这还具有回滚任何显式开始或通过autobegin开始的事务的效果，并将发出 ConnectionEvents.rollback() 事件，如果其中一个已启动且仍在进行中。

参见

Engine.begin()

method sqlalchemy.future.Engine.execute(*arg, **kw)¶

执行给定的构造并返回 CursorResult 。

1.4 版后已移除: 这个 Engine.execute() 方法被认为是SQLAlChemy 1.x系列的遗留方法，将在2.0中删除。SQLAlChemy 2.0中的所有语句都由 Connection.execute() 一种方法 Connection ，或在ORM中由 Session.execute() 一种方法 Session 。(有关SQLAlChemy 2.0的背景信息位于：迁移到Alchemy )

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

在这里，一个 Connection 是使用 Engine.connect() 方法，以及使用该连接执行的语句。返回者 CursorResult 被标记为使得当 CursorResult 耗尽且其基础游标关闭时， Connection 这里创建的也将被关闭，这允许将其关联的DBAPI连接资源返回到连接池。

method sqlalchemy.future.Engine.has_table(*arg, **kw)¶: 如果给定后端具有给定名称的表，则返回True。

1.4 版后已移除: 这个 Engine.has_table() 方法已弃用，并将在将来的版本中删除。请参阅 Inspector.has_table() 。

参见

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

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

method sqlalchemy.future.Engine.run_callable(*arg, **kw)¶

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

1.4 版后已移除: 这个 Engine.run_callable() 方法已弃用，并将在将来的版本中删除。使用 Engine.begin() 取而代之的是上下文管理器。

给定的*args and * *Kwarg在通过后通过 Connection 论点。

此函数与 Connection.run_callable() ，允许函数在运行时使用 Connection 或 Engine 对象，而不需要知道正在处理的是哪一个。

method sqlalchemy.future.Engine.scalar(*arg, **kw)¶

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

1.4 版后已移除: 这个 Engine.scalar() 方法被认为是SQLAlChemy 1.x系列的遗留方法，将在2.0中删除。SQLAlChemy 2.0中的所有语句都由 Connection.execute() 一种方法 Connection ，或在ORM中由 Session.execute() 一种方法 Session ； Result.scalar() 方法然后可以用来返回标量结果。(有关SQLAlChemy 2.0的背景信息位于：迁移到Alchemy )

底层结果/游标在执行后关闭。

method sqlalchemy.future.Engine.table_names(*arg, **kw)¶

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

1.4 版后已移除: 这个 Engine.table_names() 方法已弃用，并将在将来的版本中删除。请参阅 Inspector.get_table_names() 。

参数

schema¶ -- 可选，从非默认架构检索名称。
connection¶ -- 可选，使用指定的连接。

method sqlalchemy.future.Engine.transaction(*arg, **kw)¶

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

1.4 版后已移除: 这个 Engine.transaction() 方法已弃用，并将在将来的版本中删除。使用 Engine.begin() 取而代之的是上下文管理器。

该函数被传递给 Connection 新采购自 Engine.connect() 作为第一个参数，后跟给定的*args and * *Kwargs。

例如：

def do_something(conn, x, y):
    conn.execute(text("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(text("some statement"), {'x':5, 'y':10})

参见

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

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

function sqlalchemy.future.select(*entities)¶

构建新的 Select 使用2。x样式API。

1.4 新版功能: -The select() 函数现在按位置接受列参数。最高层 select() 函数将根据传入参数自动使用1.x或2.x样式的API；使用 select() 从 sqlalchemy.future 模块将强制只使用2.x样式的构造函数。

类似功能也可通过 FromClause.select() 任意方法 FromClause .

参见

选择 -核心教程说明 select() .

参数: *entities¶ -- 要从中选择的实体。对于核心用法，这通常是一系列 ColumnElement 和/或 FromClause 将构成结果语句的columns子句的对象。对于那些属于 FromClause （典型地 Table 或 Alias 对象） FromClause.c 提取集合以形成 ColumnElement 物体。此参数也将接受 TextClause 构造，以及ORM映射类。

SQLAlchemy 1.4 Documentation

SQLAlchemy 1.4 Documentation

SQLAlchemy Core

SQLAlchemy 2.0未来（核心）¶