sql.postgres.connection

import sql.postgres.connection

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.postgres.connection.* needs import sql.postgres.connection.

A PostgreSQL connection, as the layer above the adapters sees one.

Statements are compiled once

Every statement run here goes through the extended protocol, which compiles it on the server and then executes the compiled form. The compiled form is kept, keyed by the statement’s text, so a statement run in a loop is compiled once. That is also what makes binary parameters and results possible: both need to know the types, and compiling is what reports them.

Cursors need a transaction

A PostgreSQL portal is destroyed when its transaction ends, and a statement outside a transaction is its own transaction. So a cursor opened outside one would be closed by the server before the first row was read. This opens a transaction for the cursor’s own sake in that case and commits it when the cursor closes.

Constants

CACHE_LIMIT

sql.postgres.connection.CACHE_LIMIT = 64

How many compiled statements a connection keeps.

Classes

PostgresConnection

class sql.postgres.PostgresConnection < DriverConnection

An open PostgreSQL connection.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.postgres.PostgresConnection(driver, protocol, options)

Parameters

• driver (Driver)
• protocol (Protocol) — An authenticated protocol.
• options (dict)

PostgresConnection.protocol()

sql.postgres.PostgresConnection.protocol() -> Protocol

The protocol underneath, for the PostgreSQL-only features that are not part of the shared contract.

Returns Protocol

PostgresConnection.parameters()

sql.postgres.PostgresConnection.parameters() -> dict

The settings the server reported when the connection opened.

Returns dict

PostgresConnection.schema_adapter()

sql.postgres.PostgresConnection.schema_adapter() -> PostgresSchema

This connection’s introspection.

Returns PostgresSchema

PostgresConnection.execute()

sql.postgres.PostgresConnection.execute(sql: string, values: list) -> dict

Runs a statement for its effect.

Parameters

• sql (string)
• values (list)

Returns dict — { rows_affected, last_insert_id }

PostgresConnection.select()

sql.postgres.PostgresConnection.select(sql: string, values: list) -> dict

Runs a statement and reads its whole result.

Parameters

• sql (string)
• values (list)

Returns dict — { columns, rows }

PostgresConnection.open_cursor()

sql.postgres.PostgresConnection.open_cursor(sql: string, values: list, options: dict) -> PostgresCursor

Runs a statement and hands back a cursor over its result.

Parameters

• sql (string)
• values (list)
• options (dict) — { batch }, how many rows to fetch at a time. Defaults to 256.

Returns PostgresCursor

PostgresConnection.prepare()

sql.postgres.PostgresConnection.prepare(sql: string) -> PostgresStatement

Compiles a statement for repeated use.

Parameters

• sql (string)

Returns PostgresStatement

PostgresConnection.begin()

sql.postgres.PostgresConnection.begin(isolation)

Opens a transaction, or takes a savepoint when one is open.

Parameters

• isolation (string|nil)

PostgresConnection.commit()

sql.postgres.PostgresConnection.commit()

Commits, or releases the innermost savepoint.

PostgresConnection.rollback()

sql.postgres.PostgresConnection.rollback()

Rolls back, or undoes the innermost savepoint.

PostgresConnection.savepoint()

sql.postgres.PostgresConnection.savepoint(name: string)

PostgresConnection.release_savepoint()

sql.postgres.PostgresConnection.release_savepoint(name: string)

PostgresConnection.rollback_to()

sql.postgres.PostgresConnection.rollback_to(name: string)

PostgresConnection.in_transaction()

sql.postgres.PostgresConnection.in_transaction() -> bool

Whether a transaction is open.

The server reports this with every result, so this is what it last said rather than a guess kept on this side.

Returns bool

PostgresConnection.in_failed_transaction()

sql.postgres.PostgresConnection.in_failed_transaction() -> bool

Whether the open transaction has failed and can now only be rolled back, which is the state PostgreSQL puts one in after an error.

Returns bool

PostgresConnection.last_insert_id()

sql.postgres.PostgresConnection.last_insert_id()

Always raises: PostgreSQL does not report the id of an inserted row.

Raises NotSupportedError always.

PostgresConnection.ping()

sql.postgres.PostgresConnection.ping() -> bool

Checks the connection is usable.

Returns bool

PostgresConnection.server_version()

sql.postgres.PostgresConnection.server_version() -> string

The server’s version, such as '17.2'.

Returns string

PostgresConnection.listener()

sql.postgres.PostgresConnection.listener() -> Listener

A listener for LISTEN and NOTIFY on this connection.

var listener = db.native().listener()
listener.listen('jobs')

Returns Listener

PostgresConnection.notifications()

sql.postgres.PostgresConnection.notifications() -> list[dict]

Notifications received on this connection since the last call.

Returns list[dict] — Each { channel, payload, pid }.

PostgresConnection.close()

sql.postgres.PostgresConnection.close()

Closes the connection. Safe to call more than once.

PostgresConnection.is_closed()

sql.postgres.PostgresConnection.is_closed()

PostgresConnection.to_string()

sql.postgres.PostgresConnection.to_string()

2026, Richard Ore and Zuri contributors