Operate the PostgreSQL durability provider.

Migrate explicitly, then connect

Use separate migration and runtime credentials. Migration is a deployment action, not an implicit side effect of every application startup.

use stateknot_store_postgres::{PostgresStore, PostgresStoreOptions};

let options = PostgresStoreOptions::default();
PostgresStore::migrate_database(&migration_url, options.clone()).await?;
let store = PostgresStore::connect(&runtime_url, options).await?;
store.health_check().await?;

Startup refuses missing, newer, older, incomplete, or checksum-mismatched schemas. Do not catch that refusal and continue with a partially compatible database.

Use one validated startup configuration

PostgresStoreConfig provides a closed environment contract and a production-safe builder. Production keeps verified TLS and disables implicit migration by default. Enabling production auto-migration requires a distinct STATEKNOT_MIGRATION_DATABASE_URL; connection URLs are redacted from errors and Debug output.

use stateknot_store_postgres::{PostgresStore, PostgresStoreConfig};

let config = PostgresStoreConfig::from_env()?;
let store = PostgresStore::connect_config(config).await?;

Required: DATABASE_URL. Optional closed booleans: STATEKNOT_AUTO_MIGRATE and STATEKNOT_DEV_MODE. Production migration uses a separately privileged URL. For a trusted local database only, STATEKNOT_DEV_MODE=true enables migrations, disables TLS, and caps the pool at four connections; the equivalent explicit helper is PostgresStore::connect_development(...).

Secure and bounded defaults

Transport

TLS certificate and hostname verification is the default. URL query parameters cannot silently weaken it.

Pool

1–16 connections, five-second acquire timeout, ten-minute idle retirement, and thirty-minute maximum connection lifetime.

Transactions

Five-second lock timeout and fifteen-second statement timeout; invalid or unbounded timing relationships fail during connection setup.

Ownership

Thirty-second run leases with a five-minute renewal horizon. Outbox network attempts use a fixed, non-renewable one-minute lease.

Treat graph versions as immutable releases

Migration 13 adds a tenant-scoped compiled graph registry. The key is the exact graph owner, name, and version; canonical bytes and the definition digest may never change beneath that key. Register the graph before a run can depend on its reference.

let outcome = store
    .register_graph_definition(tenant_id, compiled_graph)
    .await?;

Identical retries converge on the original registration. Different bytes under the same version return a conflict. Every load recompiles and checks canonical bytes, redundant key columns, digest, and tenant binding; claimed recovery quarantines missing or corrupt pinned evidence under its exact live fence.

Never expose a half-initialized Agent run

Migration 15 adds immutable agent_admissions. DurableAgentAdmission commits authenticated intent, database time, Active lifecycle, the sequence-one event, superstep-zero checkpoint, graph anchors, and scheduler projections as one transaction. Exact retries recover and revalidate the original commit; changed intent conflicts.

The scheduler-ready index now requires a checkpoint, so low-level uninitialized rows cannot be claimed. Use the durable admission guide for trusted ingress, idempotency, rollout, and sensitive-data requirements.

Migration 16 adds tenant-scoped durable submission keys. A key mapping commits with admission, stores no raw key, accepts fresh candidate IDs for the same logical retry, and rejects changed content or a second key for one run. See the run/result guide.

Do not weaken TLS casually

VerifyFull is appropriate for production. RequireEncryption encrypts without authenticating the server and is therefore a deliberate downgrade. Disabled is only for a trusted local socket or an isolated test network.

Register artifacts as immutable evidence

Migration 18 adds tenant-qualified artifacts and artifact_parents. Each row binds canonical reference bytes and digest, content length and digest, the origin run/event, same-tenant lineage, idempotency key, and a private provider-neutral locator. Exact retries converge; changed metadata conflicts, and every load revalidates the complete projection.

Object I/O stays outside the registry transaction. The durable artifact guide defines private conditional publication, authorization-before-lookup, complete integrity verification, egress policy, and cleanup obligations.

Bind known model failures without weakening the barrier

Migration 19 lets a pending node result bind an exact terminal Model revision whose status is committed or failed. The composite foreign key still pins tenant, run, invocation, revision, digest, status, and Journal anchor. Prepared and executing revisions remain ineligible and continue to block Checkpoint advancement.

The Provider-native Graph uses this only for deterministic bounded output repair: a response-phase response.malformed failure must include exact Usage before it may become consumed evidence. The PostgreSQL 16/17 matrix covers a populated v18→v19 upgrade, legacy-constraint refusal, failed-binding reload, and successor-barrier commit.

Separate database roles

The migration role needs the ability to create the owned schema and migration table. The runtime role needs only the documented table and projection operations; it should not receive DDL or update/delete access to immutable journal, checkpoint, invocation revision, attempt, result, graph definition, or consumption history.

The exact current grant surface is maintained in the repository's provider operations document. Review it against the release you deploy rather than copying grants from an older article.

Qualification and current limits

CI runs the mandatory provider, Runtime and artifact-store integration suites independently against PostgreSQL 16 and 17. The suites cover migrations, lost acknowledgements, fencing, corruption rejection, concurrency, rollback injection, outbox recovery, durable waits, quarantine, immutable graph registration/recovery, ready-node planning, delayed-retry scheduling, lifecycle commits, durable model/tool execution, fairness reservations and retention, canonical parallel sibling commits, ordered read-only Tool waves with write barriers, atomic Agent admission, durable ingress-key/run-result verification, and weighted cross-tenant Agent Loop execution. Model binding evidence adds populated migration 18→19, committed-only constraint refusal, exact failed-revision recovery, and successor-barrier release. Artifact evidence adds populated migration 17→18, schema refusal, immutable registration, private object publication, authorization-first lookup, multipart ingestion, and complete digest verification.

A separate isolated pg_dump/pg_restore drill verifies a consumed child-Join snapshot and resumed graph execution. A physical pg_basebackup plus archived-WAL drill restores the same path at a named restore point and excludes a later write. Neither qualifies full disaster recovery or standby failover.

Production release still requires role isolation, general retention and garbage collection, reference-scale failover and recovery exercises, stale-race qualification, role-separated service deployment, and live workload qualification.