连接类

Connection和AsyncConnection类是 PostgreSQL 数据库会话的主要包装器。您可以将它们想象成类似于 psql 的会话。

与 psql 相比，其中一个区别是Connection通常自动处理事务：在您明确提交更改之前，其他会话将无法看到更改。有关详细信息，请查看事务管理。

class psycopg.Connection(pgconn, row_factory=<function tuple_row>)

用于数据库连接的包装器。

此类实现了符合 DBAPI 的接口。如果你要编写一个“经典的”阻塞程序（最终使用线程或 Eventlet/gevent 进行并发），这就是你想要使用的。如果您的程序使用asyncio，则可能需要改用AsyncConnection。

连接以上下文管理器的形式出现时：在代码块退出时，当前事务将被提交（或在异常情况下回滚），然后连接会被关闭。

classmethod connect(conninfo='', *, autocommit=False, prepare_threshold=5, row_factory=None, cursor_factory=None, context=None, **kwargs)

连接到数据库服务器并返回新的连接实例。

返回类型:

Connection[Any]

参数:

• conninfo – 用于指定连接目标和连接方式的连接字符串（一个postgresql://形式的 URL 或key=value键值对的列表）。
• kwargs – 指定连接字符串的更多参数。它们会覆盖 !conninfo 中指定的那些参数值。
• autocommit – 如果传递 !True 值，则不会自动启动事务。有关详细信息，请参阅事务管理。
• row_factory – 指定要创建提取数据的记录类型的行工厂（默认值：~psycopg.rows.tuple_row()）。有关详细信息，请参阅行工厂。
• cursor_factory – 连接的 cursor_factory 属性的初始值（Psycopg 3.1 中的新功能）。
• prepare_threshold – 连接的 prepare_threshold 属性的初始值（Psycopg 3.1 中的新功能）。

更专业的用法：

参数:

• context – 要从中复制初始的适配器配置的上下文。它可能是一个带有自定义加载器和转储器的 ~psycopg.adapt.AdaptersMap，用作创建多个连接的模板。有关更多详细信息，请参阅数据适配配置。

此方法也称为 psycopg.connect() 。

• 接受的连接参数列表
• 影响连接的环境变量

在 3.1 版更改： 添加了 !prepare_threshold 和 !cursor_factory 参数。

close()

关闭数据库连接。

您可以使用：

with psycopg.connect() as conn:
    ...

以在退出代码块时自动关闭连接。请参阅连接上下文。

closed

如果连接已关闭，则属性值为 !True。

broken

如果连接中断，则属性值为 !True。断开的连接始终是关闭的，但没有以干净的方式关闭，例如使用 close() 或 !with 块。

cursor(*, binary: bool = False, row_factory: Optional[RowFactory] = None) → Cursor

cursor(name: str, *, binary: bool = False, row_factory: Optional[RowFactory] = None, scrollable: Optional[bool] = None, withhold: bool = False) → ServerCursor

返回一个新游标以将命令和查询发送到连接。

参数:

• name – 如果未指定，则创建客户端游标，如果指定，则创建服务端游标。有关详细信息，请参阅游标类型。
• binary – 如果传递 !True 从数据库返回二进制值。查询返回的所有类型都必须具有二进制加载器。有关详细信息，请参阅二进制参数和结果。
• row_factory – 如果指定，则覆盖连接上设置的 row_factory。有关详细信息，请参阅行工厂。
• scrollable – 指定创建的服务端游标的 ~ServerCursor.scrollable 属性。
• withhold – 指定创建的服务端游标的 ~ServerCursor.withhold 属性。

返回:

由 cursor_factory 指定的类的游标（如果指定了 !name，则游标类由 server_cursor_factory 指定）。

您可以使用：

with conn.cursor() as cur:
    ...

以在退出代码块时自动关闭游标。

cursor_factory: Type[Cursor[TypeVar(Row, covariant=True)]]

由 cursor() 和 execute() 返回的类型或工厂函数。

默认值为 psycopg.Cursor。

server_cursor_factory: Type[ServerCursor[TypeVar(Row, covariant=True)]]

指定名称时由 cursor() 返回的类型或工厂函数。

默认值为 psycopg.ServerCursor。

row_factory: RowFactory[TypeVar(Row, covariant=True)]

定义由 ~Cursor.fetchone() 和其他游标 fetch 方法返回的行类型的行工厂。

默认值为 ~psycopg.rows.tuple_row，这意味着 fetch 方法将返回简单元组。

有关定义游标返回的对象的详细信息，请参阅行工厂。

execute(query, params=None, *, prepare=None, binary=False)

执行查询并返回游标以读取其结果。

返回类型:

Cursor[TypeVar(Row, covariant=True)]

参数:

• query (!str, !bytes, sql.SQL, 或 sql.Composed) – 要执行的查询。
• params (序列 或 映射) – 要传递给查询的参数（如果有）。
• prepare – 强制 （!True）或不允许 （!False）使用预备查询。默认情况下（!None）会自动进行预备查询。请参阅预备语句。
• binary – 如果为 !True，则游标将从数据库返回二进制值。查询返回的所有类型都必须具有二进制加载器。有关详细信息，请参阅二进制参数和结果。

该方法只是创建一个 Cursor 实例，执行请求的查询，并返回它。

有关执行查询的所有详细信息，请参阅将参数传递给 SQL 查询。

pipeline()

将连接切换到管道模式。

返回类型:

Iterator[Pipeline]

该方法是一个上下文管理器：你应该使用以下方法调用它：

with conn.pipeline() as p:
    ...

在代码块的末尾，会建立一个同步点，到达该点连接会重新进入正常模式。

可以从管道模式的代码块内递归的调用该方法。最里面的块将在退出时建立一个同步点，但管道模式将保持，直到最外面的代码块退出。

有关详细信息，请参阅管道模式支持。

版本 3.1 中的新功能。

事务管理方法

有关详细信息，请参阅事务管理。

commit()

将任何挂起的事务提交到数据库。

rollback()

回滚到任何挂起事务的开始。

transaction(savepoint_name=None, force_rollback=False)

使用新事务或嵌套事务启动一个上下文块。

参数:

• savepoint_name (Optional[str]) – 用于管理一个嵌套事务的保存点的名称。如果是 !None，将会自动选择一个名称。
• force_rollback (bool) – 即使没有错误，也要在代码块结束时回滚事务（例如，尝试进行无影响操作的过程）。

返回类型:

Transaction

必须使用如下语法调用该方法：

with conn.transaction():
    ...

with conn.transaction() as tx:
    ...

如果需要与事务对象交互，后者会很有用。有关详细信息，请参阅事务上下文。

在事务块中，不可能调用 commit() 或 rollback() 。

autocommit

连接的自动提交状态。

该属性对于同步连接是可写的，对于异步连接是只读的：您应该改为调用 !await ~AsyncConnection.set_autocommit (value) 。

以下三个属性控制新事务的特征。有关详细信息，请参阅事务特征。

isolation_level

在连接上启动的新事务的隔离级别。

!None 表示使用服务器 default_transaction_isolation 配置参数中的默认设置。

read_only

在连接上启动的新事务的只读状态。

!None 表示使用服务器的 default_transaction_read_only 配置参数中的默认设置。

deferrable

在连接上启动的新事务的可延迟状态。

!None 表示使用服务器的 default_transaction_deferrable 配置参数中的默认设置。

检查和配置连接状态

pgconn: psycopg.pq.PGconn

!Connection 类中包装底层的 libpq 连接的 ~pq.PGconn 对象。

它可用于向 PostgreSQL 发送底层命令并访问当前未由 Psycopg 包装的功能。

info

用于检查连接属性的 ConnectionInfo 属性。

prepare_threshold

查询在预备处理之前执行的次数。

• 如果设置为 0，则在首次执行每个查询时进行预备处理。
• 如果设置为 !None，则在连接上禁用预备语句。

默认值：5

有关详细信息，请参阅预备语句。

prepared_max

连接上预备语句的最大数量。

默认值：100

如果需要对更多查询进行预备处理，则会 DEALLOCATE 旧的查询。

可以用来做一些很酷的事情的方法

cancel()

取消连接上的当前操作。

notifies()

从数据库接收到消息后立即生成通知对象。

返回类型:

Generator[Notify, None, None]

在连接中使用LISTEN后，当数据库中的任何会话在其中一个侦听的通道上生成NOTIFY时，将收到通知。

add_notify_handler(callback)

注册一个要在收到通知时调用的可调用对象。

参数:

callback (Callable[[Notify], None]) – 收到通知时调用的回调。

有关详细信息，请参阅异步通知。

remove_notify_handler(callback)

取消注册以前注册的用于通知的可调用对象。

参数:

callback (Callable[[Notify], None]) – 要删除的回调。

add_notice_handler(callback)

注册在收到通知消息时要调用的可调用对象。

参数:

callback (Callable[[Diagnostic], None]) – 收到消息时调用的回调。

有关详细信息，请参阅服务端消息。

remove_notice_handler(callback)

取消注册以前注册的用于通知消息的可调用对象。

参数:

callback (Callable[[Diagnostic], None]) – 要删除的回调。

fileno()

返回连接的文件描述符。

此函数允许在等待可用的函数（例如 selector 模块中定义的函数）中将连接用作类似文件的对象。

返回类型:

int

两阶段提交支持方法

版本 3.1 中的新功能。

两阶段提交协议支持，用于这些方法的介绍性说明。

xid(format_id, gtrid, bqual)

返回要传递给此连接的 !tpc_*() 方法的 Xid。

两阶段提交协议支持中介绍了参数类型和约束。

传递给该方法的值将在返回的对象上作为成员 ~Xid.format_id、~Xid.gtrid、~Xid.bqual 提供。

返回类型:

Xid

tpc_begin(xid)

使用给定的事务 ID !xid 开启一个两阶段事务。

参数:

• xid (Xid 或 str) – 事务的 ID

此方法应该在事务外部调用（即，自上次 commit() 或 rollback() 并且 ~ConnectionInfo.transaction_status 是 ~pq.TransactionStatus.IDLE 以来，可能没有执行任何操作）。

此外，在两阶段事务中调用 !commit() 或 !rollback() 会发生错误：在这种情况下，会引发 ProgrammingError 异常。

!xid 可以是 xid() 方法返回的对象，也可以是纯字符串：后者允许使用提供的字符串作为 PostgreSQL 事务 ID 创建事务。另请参阅 tpc_recover()。

tpc_prepare()

执行以 tpc_begin() 开启的事务的第一阶段。

如果在两阶段事务之外使用此方法，则会引发 ProgrammingError 异常。

调用 !tpc_prepare() 后，在调用 tpc_commit() 或 tpc_rollback() 之前，不能执行任何语句。

PREPARE TRANSACTION PostgreSQL 命令。

tpc_commit(xid=None)

提交准备好的两阶段事务。

参数:

• xid (Xid 或 str) – 事务的 ID

当调用时没有参数时，!tpc_commit() 提交之前使用 tpc_prepare() 准备的两阶段事务。

如果在 tpc_prepare() 之前调用 !tpc_commit()，则执行单阶段提交。如果只有一个资源参与全局事务，事务管理器可以选择这样做。

当使用事务 ID !xid 调用时，数据库将提交给定的事务。如果提供了无效的事务 ID，则会引发 ProgrammingError 异常。该形式应在事务外部调用，并用于恢复。

返回时，两阶段事务结束。

COMMIT PREPARED PostgreSQL 命令。

tpc_rollback(xid=None)

回滚准备好的两阶段事务。

参数:

• xid (Xid 或 str) – 事务的 ID

当调用时没有参数时，!tpc_rollback() 回滚两阶段事务。它可以在 tpc_prepare() 之前或之后调用。

当使用事务 ID !xid 调用时，它会回滚给定的事务。如果提供了无效的事务 ID，则会引发 ProgrammingError 异常。该形式应在事务外部调用，并用于恢复。

返回时，两阶段事务结束。

ROLLBACK PREPARED PostgreSQL 命令。

tpc_recover()

返回类型:

List[Xid]

返回表示挂起事务的 Xid 列表，适合与 tpc_commit() 或 tpc_rollback() 一起使用。

如果事务不是由 Psycopg 发起的，则返回的 Xid 将具有属性 ~Xid.format_id 和 ~Xid.bqual 设置为 !None 和 ~Xid.gtrid 设置为 PostgreSQL 事务 ID：这样的 Xid 仍然可用于恢复。Psycopg 使用与 PostgreSQL JDBC 驱动程序相同的算法对字符串中的 XA 三元组进行编码，因此，使用此类驱动程序的程序启动的事务应该会被正确地解压缩。

由 !tpc_recover() 返回的 Xid 还有额外的属性 ~Xid.prepared， ~Xid.owner， ~Xid.database，填充了从服务端读取的值。

pg_prepared_xacts 系统视图。

class psycopg.AsyncConnection(pgconn, row_factory=<function tuple_row>)

用于数据库连接的异步包装器。

此类实现了受 DBAPI 启发的接口，所有阻塞方法都以协程实现。除非另有指定，非阻塞方法都与 Connection 类共享。

以下方法同匹配的 !Connection 方法具有相同的行为，但应使用 await 关键字调用。

async classmethod connect(conninfo='', *, autocommit=False, prepare_threshold=5, context=None, row_factory=None, cursor_factory=None, **kwargs)

返回类型:

AsyncConnection[Any]

*在 3.1 版本更改：*异步自动解析域名。在以前的版本中，除非指定了 !hostaddr 参数或使用 ~psycopg._dns.resolve_hostaddr_async() 函数，否则名称解析会阻塞。

async close()

您可以使用async with在退出代码块时自动关闭连接，但请注意异步行为的一些差异：有关详细信息，请参阅使用异步连接。

cursor(*, binary: bool = False, row_factory: Optional[RowFactory] = None) → AsyncCursor

cursor(name: str, *, binary: bool = False, row_factory: Optional[RowFactory] = None, scrollable: Optional[bool] = None, withhold: bool = False) → AsyncServerCursor

您可以使用：

async with conn.cursor() as cur:
    ...

以在退出代码块时自动关闭游标。

cursor_factory*: Type[AsyncCursor[TypeVar(Row, covariant=True)]]*

默认值为 psycopg.AsyncCursor。

server_cursor_factory*: Type[AsyncServerCursor[TypeVar(Row, covariant=True)]]*

默认值为 psycopg.AsyncServerCursor。

row_factory*: AsyncRowFactory[TypeVar(Row, covariant=True)]*

async execute(query, params=None, *, prepare=None, binary=False)

返回类型:

AsyncCursor[TypeVar(Row, covariant=True)]

pipeline()

上下文管理器，用于将连接切换到管道模式。

返回类型:

AsyncIterator[AsyncPipeline]

它必须被这样调用：

async with conn.pipeline() as p:
    ...

async commit()

async rollback()

transaction(savepoint_name=None, force_rollback=False)

使用新事务或嵌套事务启动上下文代码块。

返回类型:

AsyncTransaction

它必须被这样调用：

async with conn.transaction() as tx:
    ...

async notifies()

返回类型:

AsyncGenerator[Notify, None]

async set_autocommit(value)

~Connection.autocommit 属性修改方法的异步版本。

async set_isolation_level(value)

~Connection.isolation_level 属性修改方法的异步版本。

async set_read_only(value)

~Connection.read_only 属性修改方法的异步版本。

async set_deferrable(value)

~Connection.deferrable 属性修改方法的异步版本。

async tpc_prepare()

async tpc_commit(xid=None)

async tpc_rollback(xid=None)

async tpc_recover()

返回类型:

List[Xid]