Python API reference¶
Use this page to look up exact signatures, defaults, return types, and exceptions. Begin with the Python quickstart or the Python overview if you are choosing an entry point.
| Looking for | Section |
|---|---|
connect, Database, Connection, and cursors |
Database objects |
| Large results, requests, COPY, and prepared statements | Requests and streaming |
| Event-loop wrappers | Asyncio |
| Checkpoint, backup, events, and extensions | Management and events |
| Codecs and Arrow | Values and adapters |
| DB-API errors | Exceptions |
The remainder of this page is generated from the frozen Python API inventory, source type annotations, and docstrings. A documentation build fails when a public export is missing from the inventory or reference grouping.
Product metadata¶
Runtime identity, capability discovery, and DB-API module metadata.
| Name | Meaning |
|---|---|
postgamma.__version__ |
Python package version. |
postgamma.apilevel |
PEP 249 API level, currently 2.0. |
postgamma.threadsafety |
PEP 249 thread-safety level, currently 2. |
postgamma.paramstyle |
PEP 249 cursor parameter style, currently numeric. |
Return the loaded native library identity and capability mask.
Return the optional capabilities advertised by the loaded kernel.
Bases: IntFlag
Optional capabilities advertised by the loaded PostGamma kernel.
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
Database objects¶
Lazy instances, logical sessions, materialized results, and DB-API cursors.
Database(
path: str | PathLike[str],
*,
mode: OpenMode | str = OpenMode.OPEN_OR_CREATE,
settings: (
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
) = None,
worker_count: int = 4,
timeout: float | None = _DEFAULT_TIMEOUT_SECONDS,
resource_root: str | PathLike[str] | None = None,
executable_path: str | PathLike[str] | None = None,
result_buffer_limit: int = 0,
maximum_value_size: int = 0,
event_queue_capacity: int = 64
)
A lazy in-process PostgreSQL instance backed by one cluster directory.
path names the persistent PostgreSQL cluster directory, not a DSN,
server address, SQL database name, or SQLite-style file. The directory is
initialized on first open when mode permits creation and it does not
already contain a compatible cluster. Construction alone does not open it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | PathLike[str]
|
Persistent cluster directory. A relative path is resolved when the instance first opens; its parent directory must already exist. |
required |
mode
|
OpenMode | str
|
Whether to open or create, require an existing cluster, or create a new cluster only when the final path does not exist. |
OPEN_OR_CREATE
|
settings
|
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
|
Instance/startup PostgreSQL settings as a mapping or iterable of name/value pairs. Values are converted to strings. |
None
|
worker_count
|
int
|
Number of carrier workers available to logical sessions. The native PostgreSQL 19 kernel requires at least two. |
4
|
timeout
|
float | None
|
Default operation deadline in seconds, or |
_DEFAULT_TIMEOUT_SECONDS
|
resource_root
|
str | PathLike[str] | None
|
Advanced override for the bundled PostgreSQL resource pack. Installed wheels resolve this automatically. |
None
|
executable_path
|
str | PathLike[str] | None
|
Advanced PostgreSQL executable-identity override.
Installed wheels resolve it to |
None
|
result_buffer_limit
|
int
|
Maximum materialized result bytes, or zero for the embedded default. |
0
|
maximum_value_size
|
int
|
Maximum individual value bytes, or zero for the embedded default. |
0
|
event_queue_capacity
|
int
|
Maximum number of routed instance events. |
64
|
Note
Entering the context, calling :meth:open, opening a connection, or
executing through the database triggers the first open. A closed
Database object cannot be reopened; construct a new object for the
same persistent path.
instance-attribute
¶
instance-attribute
¶
instance-attribute
¶
instance-attribute
¶
instance-attribute
¶
Create or open the cluster and return this database object.
With the default mode="open_or_create", a missing final directory
is initialized in a private staging directory and published atomically.
A compatible existing cluster is opened without replacing data.
Returns:
| Type | Description |
|---|---|
Self
|
This database object after the embedded instance is ready. |
Raises:
| Type | Description |
|---|---|
OperationalError
|
The path is missing when creation is disabled, is nonempty but incompatible, is already owned, or cannot be initialized or opened. |
ForkedProcessError
|
The object was inherited across |
connect(
*,
user: str = "postgamma",
database: str = "postgres",
application_name: str = "postgamma-python",
settings: (
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
) = None,
autocommit: bool = False,
timeout: float | None = None
) -> Connection
Open one logical PostgreSQL session owned by this database.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user
|
str
|
Existing PostgreSQL role. New roles are not created implicitly. |
'postgamma'
|
database
|
str
|
Existing SQL database inside the cluster. This is not the cluster-directory path. |
'postgres'
|
application_name
|
str
|
Value reported by PostgreSQL for this session. |
'postgamma-python'
|
settings
|
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
|
Session-local PostgreSQL settings. |
None
|
autocommit
|
bool
|
Commit every statement independently when true. When false, ordinary statements begin an implicit transaction. |
False
|
timeout
|
float | None
|
Connection operation deadline in seconds. |
None
|
Returns:
| Type | Description |
|---|---|
Connection
|
A logical connection. Closing it leaves this shared database |
Connection
|
instance open. |
Raises:
| Type | Description |
|---|---|
DatabaseError
|
PostgreSQL rejects the SQL database, role, or session options. |
OperationalError
|
The instance cannot start or accept the session. |
execute(
sql: str,
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None
) -> Result
Execute one autocommitted statement on a temporary connection.
Return a synchronized executor, request, and event snapshot.
Return the next owned log, notice, notification, or overflow event.
Register a host-thread event callback, optionally for one event kind.
Remove a previously registered event callback.
Drain queued events and invoke callbacks on the calling host thread.
Start an in-process checkpoint and optionally wait for completion.
maintenance(
kind: Any = "vacuum_analyze",
*,
database: str | None = None,
user: str | None = None,
wait: bool = True,
timeout: float | None = None
) -> Any
Run VACUUM, ANALYZE, VACUUM ANALYZE, or database REINDEX.
logical_dump(
stream: Any,
*,
flags: int = 0,
database: str | None = None,
user: str | None = None,
channel_capacity: int = 256 * 1024,
progress_quantum: int = 64 * 1024,
wait: bool = True,
timeout: float | None = None
) -> Any
Write an in-process PostgreSQL logical archive to a binary stream.
logical_restore(
stream: Any,
*,
flags: int = 0,
database: str | None = None,
user: str | None = None,
channel_capacity: int = 256 * 1024,
progress_quantum: int = 64 * 1024,
wait: bool = True,
timeout: float | None = None
) -> Any
Restore an in-process PostgreSQL logical archive from a binary stream.
Return metadata for extensions statically reviewed into this build.
Close the instance.
A failed or timed-out close leaves the native handle open so the same
Database may retry close() with another timeout or mode.
Quiesce and close the instance before the host calls fork().
Bases: str, Enum
Explicit policy for opening a persistent cluster path.
classmethod
¶
Normalize an enum member or its public string spelling.
Connection(
owner: Database,
handle: Any,
*,
autocommit: bool,
timeout: float | None,
implicit_release: Any | None
)
One logical PostgreSQL session over the in-memory protocol.
A connection preserves PostgreSQL transaction state, temporary objects, prepared statements, session settings, and notifications across calls. Operations on one connection are serialized; different connections owned by one database may execute concurrently.
Connections returned by top-level :func:postgamma.connect lease a shared
process-local Database for their canonical cluster path. The last such
connection closes the implicit instance. A connection returned by
:meth:Database.connect closes only its logical session.
property
writable
¶
Return whether statements commit without an implicit transaction.
property
¶
Return the current PostgreSQL transaction-status constant.
Return a PostgreSQL parameter-status value by name.
execute(
sql: str,
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None
) -> Result
Execute one statement and return a materialized result.
Use PostgreSQL extended-protocol markers such as $1 and $2.
DB-API cursor markers such as :1 apply only to :class:Cursor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sql
|
str
|
One PostgreSQL statement. |
required |
parameters
|
Sequence[Any] | None
|
Values for positional markers, or |
None
|
timeout
|
float | None
|
Statement deadline in seconds. |
None
|
Returns:
| Type | Description |
|---|---|
Result
|
A Python-owned materialized result positioned before its first row. |
Raises:
| Type | Description |
|---|---|
QueryTimeoutError
|
The host-side deadline expires. |
QueryCanceledError
|
This request is canceled. |
DatabaseError
|
PostgreSQL rejects or cannot execute the statement. |
stream(
sql: str,
parameters: Sequence[Any] | None = None,
*,
chunk_rows: int = 1024,
timeout: float | None = None,
result_buffer_limit: int = 0,
on_notice: Any | None = None
) -> Any
Execute a query as bounded, caller-driven row chunks.
Execute simple-protocol SQL and return every ordered result.
Create a reusable extended-protocol prepared statement.
Start COPY FROM STDIN or COPY TO STDOUT and return a byte-stream object.
copy_from(
sql: str,
source: Any,
*,
chunk_size: int = 64 * 1024,
timeout: float | None = None
) -> Result
Copy bytes from a readable object and return PostgreSQL's command result.
copy_to(
sql: str,
target: Any,
*,
chunk_size: int = 64 * 1024,
timeout: float | None = None
) -> Result
Copy bytes to a writable object and return PostgreSQL's command result.
execute_arrow(
sql: str,
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None
) -> Any
Execute a query and expose its struct array through Arrow C Data.
Return a transaction scope that commits or rolls back without closing.
The connection must be idle when the scope is entered. Nested scopes are rejected rather than silently changing transaction ownership.
Close this session and its cursors.
Once native close starts, this connection accepts only further close
attempts. A failed or timed-out attempt preserves its handle for that
cleanup; closed becomes true only after native close succeeds.
PEP 249 cursor backed by materialized PostGamma results.
execute(
operation: str,
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None
) -> Self
Execute one numeric-parameter DB-API statement and return this cursor.
Execute one statement for each supplied parameter sequence.
Raise NotSupportedError because procedure calls are unavailable.
Return up to size rows, defaulting to arraysize.
Accept the optional PEP 249 input-size hint as a no-op.
Accept the optional PEP 249 output-size hint as a no-op.
A materialized, Python-owned PostgreSQL result.
class-attribute
instance-attribute
¶
instance-attribute
¶
_rows = tuple(
tuple(
(
None
if value is None
else decode_value(value[0], value[1], value[2])
)
for value in row
)
for row in native["rows"]
)
property
¶
Return PEP 249 column descriptions, or None without columns.
property
¶
Return all rows owned by this materialized result.
Return the next row, or None after the result is exhausted.
Return up to size rows from the current result position.
dataclass
¶
Column(
name: str | None,
table_oid: int,
table_column: int,
type_oid: int,
type_size: int,
type_modifier: int,
format: int,
)
PostgreSQL result-column metadata independent of PostgreSQL headers.
property
¶
Return this column in the seven-field PEP 249 description form.
connect(
path: str | PathLike[str],
*,
mode: OpenMode | str = OpenMode.OPEN_OR_CREATE,
database: str = "postgres",
user: str = "postgamma",
application_name: str = "postgamma-python",
settings: (
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
) = None,
connection_settings: (
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
) = None,
worker_count: int = 4,
autocommit: bool = False,
timeout: float | None = _DEFAULT_TIMEOUT_SECONDS,
resource_root: str | PathLike[str] | None = None,
executable_path: str | PathLike[str] | None = None
) -> Connection
Open a logical session on a shared process-local embedded instance.
path is a PostgreSQL cluster directory. The default mode opens an
existing compatible cluster or initializes a missing final directory. All
top-level connections for the same canonical path share one embedded
instance while retaining independent PostgreSQL session and transaction
state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | PathLike[str]
|
Persistent PostgreSQL cluster-directory path. |
required |
mode
|
OpenMode | str
|
|
OPEN_OR_CREATE
|
database
|
str
|
Existing PostgreSQL logical database inside the cluster. |
'postgres'
|
user
|
str
|
Existing PostgreSQL role for the logical session. |
'postgamma'
|
application_name
|
str
|
PostgreSQL application name for the session. |
'postgamma-python'
|
settings
|
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
|
Instance/startup PostgreSQL settings. Repeated top-level connections must request the same instance settings. |
None
|
connection_settings
|
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
|
Session-local PostgreSQL settings. |
None
|
worker_count
|
int
|
Carrier workers shared by sessions on this instance. |
4
|
autocommit
|
bool
|
Commit each statement independently when true. |
False
|
timeout
|
float | None
|
Default operation deadline in seconds, or |
_DEFAULT_TIMEOUT_SECONDS
|
resource_root
|
str | PathLike[str] | None
|
Advanced resource-pack override; wheels resolve it. |
None
|
executable_path
|
str | PathLike[str] | None
|
Advanced PostgreSQL executable-identity override;
wheels resolve it to |
None
|
Returns:
| Type | Description |
|---|---|
Connection
|
An independent logical connection. Its close releases one instance |
Connection
|
lease; the last implicit connection shuts down the shared instance. |
Raises:
| Type | Description |
|---|---|
OperationalError
|
The path violates the requested mode or cannot open. |
InterfaceError
|
Instance options conflict with a live implicit instance. |
DatabaseError
|
PostgreSQL rejects the requested logical database or role. |
Example
import postgamma with postgamma.connect("application.pgm", autocommit=True) as connection: ... connection.execute("create table if not exists values_(n int)")
Requests and streaming¶
Caller-driven requests, bounded rows, COPY, prepared statements, and scheduler state.
Request(
connection: Connection,
handle: Any,
*,
timeout: float | None,
on_notice: Any | None = None
)
One ordered, caller-driven PostgreSQL result sequence.
class-attribute
instance-attribute
¶
__slots__ = (
"connection",
"_handle",
"_closed",
"_deadline",
"_on_notice",
"_copy_ref",
"_owns_gate",
"id",
"waitable",
"__weakref__",
)
instance-attribute
¶
classmethod
¶
start(
connection: Connection,
sql: str,
parameters: Sequence[Any] | None = None,
*,
chunk_rows: int = 0,
timeout: float | None = None,
result_buffer_limit: int = 0,
script: bool = False,
on_notice: Any | None = None
) -> Request
Submit SQL and return one caller-driven ordered request.
classmethod
¶
from_statement(
statement: PreparedStatement,
parameters: Sequence[Any] | None,
*,
chunk_rows: int,
timeout: float | None,
result_buffer_limit: int,
on_notice: Any | None
) -> Request
Execute a prepared statement as a caller-driven request.
Take one result without blocking and expose its availability state.
Block for one ordered result, returning None at end of sequence.
Yield all ordinary results and verify the terminal boundary.
A bounded synchronous row stream with terminal-result verification.
class-attribute
instance-attribute
¶
__slots__ = (
"request",
"columns",
"command_status",
"rowcount",
"_rows",
"_chunk_iterator",
"_rows_seen",
"_closed",
"__weakref__",
)
property
¶
Return PEP 249 descriptions after column metadata becomes available.
classmethod
¶
start(
connection: Connection,
sql: str,
parameters: Sequence[Any] | None,
*,
chunk_rows: int,
timeout: float | None,
result_buffer_limit: int,
on_notice: Any | None
) -> RowStream
Submit a bounded-row request and return its stream.
classmethod
¶
Wrap an existing chunked request as a row stream.
Return the next streamed row, or None at the terminal boundary.
Return up to size rows while preserving bounded native chunks.
Materialize and return every remaining streamed row in Python.
Bases: _CopyBase
Partial, backpressure-aware COPY FROM STDIN byte writer.
class-attribute
instance-attribute
¶
Abort COPY and release the active request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str | None
|
Optional PostgreSQL COPY failure message. |
None
|
Finish COPY IN and return PostgreSQL's terminal command result.
Copy from a readable binary object until it returns end of input.
Bases: _CopyBase
Partial, backpressure-aware COPY TO STDOUT byte reader.
class-attribute
instance-attribute
¶
Abort COPY and release the active request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str | None
|
Optional PostgreSQL COPY failure message. |
None
|
Read up to size COPY OUT bytes, returning empty bytes at end.
Copy all output to a writable binary object and return the result.
A reusable prepared statement owned by one logical connection.
class-attribute
instance-attribute
¶
property
¶
Describe parameter types and result columns, caching the result.
classmethod
¶
prepare(
connection: Connection,
sql: str,
parameter_type_oids: Sequence[int] | None,
) -> PreparedStatement
Prepare SQL with optional declared parameter type OIDs.
execute(
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None,
on_notice: Any | None = None
) -> Result
Execute this statement and return one materialized result.
stream(
parameters: Sequence[Any] | None = None,
*,
chunk_rows: int = 1024,
timeout: float | None = None,
result_buffer_limit: int = 0,
on_notice: Any | None = None
) -> RowStream
Execute this statement as a bounded row stream.
dataclass
¶
dataclass
¶
ConnectionStatus(
transaction_status: int,
pin_reasons: PinReason,
carrier_retained: bool,
virtual_backend_pid: int,
connection_id: int,
active_request_id: int,
)
A synchronized transaction and executor-scheduling snapshot.
classmethod
¶
Construct a typed status snapshot from the native ABI mapping.
Bases: IntFlag
Reasons a logical session currently retains one executor worker.
Asyncio¶
Event-loop adapters over the same native handles and level-triggered waitables.
Asyncio facade over a lazy :class:postgamma.Database.
property
¶
Return the synchronous database object wrapped by this facade.
async
¶
Open one logical connection and return its asyncio facade.
async
¶
execute(
sql: str,
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None
) -> Result
Execute one autocommitted statement on a temporary connection.
async
¶
Yield instance events without occupying a worker thread.
async
¶
Run an in-process checkpoint and return its final progress snapshot.
async
¶
maintenance(
kind: Any = "vacuum_analyze",
*,
timeout: float | None = None,
**options: Any
) -> OperationProgress
Run one supported maintenance command to completion.
async
¶
Write a logical archive through an asynchronous operation driver.
async
¶
logical_restore(
stream: Any,
*,
timeout: float | None = None,
**options: Any
) -> OperationProgress
Restore a logical archive through an asynchronous operation driver.
One serialized asyncio session; other sessions still run concurrently.
property
¶
Return the synchronous logical connection wrapped by this facade.
async
¶
async
¶
execute(
sql: str,
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None
) -> Result
Execute one statement through a caller-driven native request.
async
¶
stream(
sql: str,
parameters: Sequence[Any] | None = None,
*,
chunk_rows: int = 1024,
timeout: float | None = None,
result_buffer_limit: int = 0,
on_notice: Any | None = None
) -> AsyncRowStream
Execute SQL and return an asynchronous bounded row stream.
async
¶
Execute simple-protocol SQL and return every ordered result.
async
¶
Prepare SQL and return an asynchronous statement facade.
async
¶
Start COPY IN or COPY OUT and return an asynchronous byte stream.
Return a single-use asynchronous transaction scope.
async
¶
async
¶
Close the logical connection without blocking the event loop.
Async facade over COPY IN or COPY OUT partial I/O.
Asyncio execution facade for one reusable prepared statement.
async
¶
execute(
parameters: Sequence[Any] | None = None,
*,
timeout: float | None = None,
on_notice: Any | None = None
) -> Result
Execute the prepared statement and materialize one result.
async
¶
stream(
parameters: Sequence[Any] | None = None,
*,
chunk_rows: int = 1024,
timeout: float | None = None,
result_buffer_limit: int = 0,
on_notice: Any | None = None
) -> AsyncRowStream
Execute the prepared statement as a bounded asynchronous stream.
async
¶
connect_async(
path: str | PathLike[str],
*,
mode: OpenMode | str = OpenMode.OPEN_OR_CREATE,
database: str = "postgres",
user: str = "postgamma",
application_name: str = "postgamma-python",
settings: (
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
) = None,
connection_settings: (
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
) = None,
worker_count: int = 4,
autocommit: bool = False,
timeout: float | None = _DEFAULT_TIMEOUT_SECONDS,
resource_root: str | PathLike[str] | None = None,
executable_path: str | PathLike[str] | None = None
) -> AsyncConnection
Open one logical session without blocking the asyncio event loop.
This is the asynchronous counterpart of :func:postgamma.connect. It
accepts the same options, shares the same process-local instance registry,
and returns an already-open :class:AsyncConnection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | PathLike[str]
|
Persistent PostgreSQL cluster-directory path. |
required |
mode
|
OpenMode | str
|
|
OPEN_OR_CREATE
|
database
|
str
|
Existing PostgreSQL logical database inside the cluster. |
'postgres'
|
user
|
str
|
Existing PostgreSQL role for the logical session. |
'postgamma'
|
application_name
|
str
|
PostgreSQL application name for the session. |
'postgamma-python'
|
settings
|
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
|
Instance/startup PostgreSQL settings. Repeated connections must request the same instance settings. |
None
|
connection_settings
|
Mapping[str, Any] | Iterable[tuple[str, Any]] | None
|
Session-local PostgreSQL settings. |
None
|
worker_count
|
int
|
Carrier workers shared by sessions on this instance. |
4
|
autocommit
|
bool
|
Commit each statement independently when true. |
False
|
timeout
|
float | None
|
Default operation deadline in seconds, or |
_DEFAULT_TIMEOUT_SECONDS
|
resource_root
|
str | PathLike[str] | None
|
Advanced resource-pack override; wheels resolve it. |
None
|
executable_path
|
str | PathLike[str] | None
|
Advanced executable-identity override; wheels resolve it and do not launch that executable. |
None
|
Returns:
| Type | Description |
|---|---|
AsyncConnection
|
An open asynchronous logical connection whose close releases one |
AsyncConnection
|
process-local instance lease. |
Raises:
| Type | Description |
|---|---|
OperationalError
|
The path violates the requested mode or cannot open. |
InterfaceError
|
Instance options conflict with a live implicit instance. |
DatabaseError
|
PostgreSQL rejects the requested logical database or role. |
Management and events¶
Instance events, bundled-extension metadata, checkpoints, maintenance, and logical archives.
dataclass
¶
Bases: IntEnum
Kinds delivered through an instance event queue.
dataclass
¶
LogEvent(
kind: EventKind,
connection_id: int,
request_id: int,
virtual_backend_pid: int,
severity: str,
sqlstate: str,
message: str,
detail: str,
)
Bases: Event
One structured PostgreSQL log record routed to the host.
dataclass
¶
dataclass
¶
dataclass
¶
dataclass
¶
BundledExtension(
id: str,
sql_name: str,
version: str,
postgresql_major: int,
sdk_abi_version: int,
capabilities: int,
)
Borrowed build metadata copied for one reviewed bundled extension.
classmethod
¶
Copy one native bundled-extension metadata mapping.
Bases: IntFlag
Composable logical dump and restore options.
One in-process checkpoint, maintenance, dump, or restore operation.
class-attribute
instance-attribute
¶
property
¶
Return the most recent synchronized operation progress snapshot.
classmethod
¶
Create a pending checkpoint operation for a database.
classmethod
¶
maintenance(
owner: Database,
*,
kind: MaintenanceKind | str | int,
database_name: str | None = None,
user: str | None = None
) -> Operation
Create a pending VACUUM, ANALYZE, or REINDEX operation.
classmethod
¶
Create a pending logical dump writing to a binary stream.
classmethod
¶
Create a pending logical restore reading from a binary stream.
classmethod
¶
_logical(
owner: Database,
stream: Any,
*,
dump: bool,
flags: int,
database_name: str | None = None,
user: str | None,
channel_capacity: int,
progress_quantum: int
) -> Operation
Drive this operation to a terminal state within a deadline.
Bases: IntEnum
Stable progress phases shared by management operations.
dataclass
¶
OperationProgress(
kind: OperationKind,
state: OperationState,
phase: OperationPhase,
bytes_received: int,
bytes_produced: int,
total_bytes: int,
objects_completed: int,
objects_total: int,
)
A synchronized management-operation progress snapshot.
classmethod
¶
Construct a typed progress snapshot from the native ABI mapping.
Bases: IntEnum
Lifecycle states for a caller-driven management operation.
Values and adapters¶
Lossless unknown values, explicit encoders, custom codecs, and Arrow C Data export.
dataclass
¶
dataclass
¶
One explicit PostgreSQL parameter representation for a custom encoder.
dataclass
¶
Explicitly encode a Python value as jsonb.
dataclass
¶
register_codec(
*,
oid: int,
decoder: Decoder,
python_type: type[Any] | None = None,
encoder: Encoder | None = None
) -> None
Register an application or bundled-extension codec.
Registration is process-wide and affects values decoded after the call. A Python encoder is optional, but its type and callable must be supplied together.
Remove a previously registered custom codec.
A one-shot Arrow struct array exported through the PyCapsule protocol.
The PostGamma kernel does not link an Arrow runtime. Consumers such as
PyArrow, Polars, and DataFusion take ownership through __arrow_c_array__.
DB-API constructors and type objects¶
PEP 249 constructors and comparison objects.
| Name | Meaning |
|---|---|
postgamma.STRING |
DB-API string type comparison object. |
postgamma.BINARY |
DB-API binary type comparison object. |
postgamma.NUMBER |
DB-API numeric type comparison object. |
postgamma.DATETIME |
DB-API date and time type comparison object. |
postgamma.ROWID |
DB-API row identifier type comparison object. |
Construct the date value required by PEP 249.
Construct the time value required by PEP 249.
Timestamp(
year: int,
month: int,
day: int,
hour: int,
minute: int,
second: int,
) -> datetime.datetime
Construct the timestamp value required by PEP 249.
Construct a local date from seconds since the epoch.
Construct a local time from seconds since the epoch.
Construct a local timestamp from seconds since the epoch.
Convert a bytes-like value to the PEP 249 binary representation.
Exceptions¶
PEP 249 errors plus explicit timeout, cancellation, and fork failures.
Bases: Exception
A non-fatal database warning.
Error(
message: str,
*,
status: int | None = None,
status_name: str | None = None,
sqlstate: str | None = None,
severity: str | None = None,
detail: str | None = None,
hint: str | None = None
)
Bases: Exception
Base class for every PostGamma database exception.