PostgreSQL and migrations API

Stores

postgres

Direct PostgreSQL action store over an application-owned async connection pool.

PostgresActionStore

PostgresActionStore(pool: ConnectionSource, *, schema: str = 'threvo_actions')

Bases: ActionStore

Tenant-scoped runtime adapter; erasure requires PostgresRetentionStore.

create async

create(proposal: StoredProposal) -> None

get async

get(tenant_reference: str, proposal_reference: str) -> StoredProposal | None

compare_and_set async

compare_and_set(*, tenant_reference: str, proposal_reference: str, expected_revision: int, expected_statuses: tuple[LifecycleStatus, ...], updated: StoredProposal) -> bool

admit_execution async

admit_execution(*, tenant_reference: str, proposal_reference: str, expected_revision: int, admitted_at: datetime, updated: StoredProposal) -> EffectClaimResult

get_effect_claim_owner async

get_effect_claim_owner(*, tenant_reference: str, action_type: ActionType, semantic_effect_reference: str) -> str | None

PostgresRetentionStore

PostgresRetentionStore(pool: ConnectionSource, *, schema: str = 'threvo_actions')

Bases: RetentionStore

Privileged erasure adapter intended for a separate retention pool.

mark_erasure_pending async

mark_erasure_pending(*, tenant_reference: str, proposal_reference: str, expected_revision: int, pending_at: datetime) -> bool

complete_erasure async

complete_erasure(*, tenant_reference: str, proposal_reference: str, expected_revision: int, erased_at: datetime) -> bool

ConnectionSource

Bases: Protocol

acquire

acquire() -> AbstractAsyncContextManager[_Connection]

StoredDataCorruptionError

Bases: RuntimeError

Migration runner

migrations

Explicit, advisory-locked PostgreSQL migrations for the optional adapter.

MigrationStatus dataclass

MigrationStatus(applied_versions: tuple[int, ...], pending_versions: tuple[int, ...], connected_role_owns_proposals: bool | None = None)

applied_versions instance-attribute

applied_versions: tuple[int, ...]

pending_versions instance-attribute

pending_versions: tuple[int, ...]

connected_role_owns_proposals class-attribute instance-attribute

connected_role_owns_proposals: bool | None = None

PostgresMigrationSQL dataclass

PostgresMigrationSQL(version: int, filename: str, checksum: str, phase: MigrationPhase, compatible_with_previous_runtime: bool, requires_writer_quiescence: bool, sql: str)

One pending PostgreSQL migration rendered exactly for a schema.

version instance-attribute

version: int

filename instance-attribute

filename: str

checksum instance-attribute

checksum: str

phase instance-attribute

phase: MigrationPhase

compatible_with_previous_runtime instance-attribute

compatible_with_previous_runtime: bool

requires_writer_quiescence instance-attribute

requires_writer_quiescence: bool

sql instance-attribute

sql: str

ConnectionSource

Bases: Protocol

acquire

acquire() -> AbstractAsyncContextManager[_Connection]

InvalidSchemaNameError

Bases: ValueError

MigrationStateError

Bases: RuntimeError

check_postgres_readiness async

check_postgres_readiness(pool: ConnectionSource, *, schema: str, lane: DatabaseAccessLane) -> DatabaseReadiness

Check current migrations and effective lane privileges without writes.

inspect_postgres async

inspect_postgres(pool: ConnectionSource, *, schema: str) -> MigrationStatus

migrate_postgres async

migrate_postgres(pool: ConnectionSource, *, schema: str, lock_timeout: timedelta = timedelta(seconds=30), writers_quiesced: bool = False) -> MigrationStatus

plan_postgres_migrations

plan_postgres_migrations(*, schema: str, pending_versions: tuple[int, ...] | None = None) -> tuple[PostgresMigrationSQL, ...]

Render exact packaged SQL for review without connecting or mutating.

postgres_migration_compatibility

postgres_migration_compatibility() -> tuple[MigrationCompatibility, ...]

Return immutable compatibility metadata for PostgreSQL migrations.

quote_schema_name

quote_schema_name(schema: str) -> str

render_postgres_grants

render_postgres_grants(*, schema: str, runtime_role: str, retention_role: str) -> str

Render the official least-privilege runtime and retention grants.

render_postgres_migration_script

render_postgres_migration_script(*, schema: str, from_version: int, writers_quiesced: bool = False) -> str

Render a complete offline upgrade script pinned to an expected version.

from_version=0 renders a fresh-database bootstrap. Existing databases must name their exact current version so the script can validate the immutable migration ledger before applying any DDL.

See Migration compatibility before automating an upgrade. Contract migrations on an existing schema require an explicit writer quiescence acknowledgement.

See Database readiness for the read-only startup gate.