Crate runledger_postgres 

PostgreSQL persistence layer for Runledger durable execution.

This crate owns the SQLx-backed storage and query helpers used by the runtime and application crates. The main entrypoint is the jobs module, which exposes APIs for:

• queueing, claiming, heartbeating, and completing jobs
• listing admin/job log data and runtime configuration
• enqueueing and querying workflow runs and steps
• applying or validating the bundled Runledger schema migrations

Typical consumers share a DbPool with runledger-runtime, then call the exported jobs functions from application setup, admin APIs, or tests.

Security Boundary

This crate is a persistence layer, not an authentication or authorization layer. Public job and workflow APIs that accept organization_id, idempotency keys, workflow IDs, job IDs, or metadata expect those values to come from a trusted service boundary. HTTP or RPC handlers should derive organization scope from authenticated claims or server-side policy, not from untrusted request parameters alone.

QueryError::client_message and QueryError::code are the stable values intended for public error responses. Detailed internal context remains available through QueryError::internal_message for server-side diagnostics. Public formatting keeps raw SQLx details sanitized. The standard error source chain and QueryError::source_arc are available for trusted server-side diagnostics. Runtime lifecycle, workflow mutation, and idempotent enqueue APIs are designed for PostgreSQL’s default READ COMMITTED transaction isolation so they can observe rows committed after lock waits or uniqueness conflicts. Release-sensitive, workflow-append, and keyed-enqueue paths validate this before running because their correctness depends on second reads after waits or conflicts.

For simple embedding, call migrate_after_idempotency_cutover during startup:

let pool = sqlx::PgPool::connect("postgres://localhost/runledger").await?;
runledger_postgres::migrate_after_idempotency_cutover(&pool).await?;

For deployments that manage DDL elsewhere, call ensure_schema_compatible_after_idempotency_cutover instead to fail fast if the schema is missing, drifted, or still has keyed legacy rows without idempotency request snapshots. That check is read-only, but it expects the database to retain SQLx migration history in _sqlx_migrations and, when available, Runledger-owned migration state in runledger_migration_history.

Modules

jobs

Structs

FrameworkConstraintSpec

QueryError

Enums

Error

QueryErrorCategory

SchemaCompatibilityError

Statics

MIGRATOR

Functions

classify_framework_constraint

classify_query_error

classify_query_error_with_constraint_classifier

ensure_schema_compatibleDeprecated

Validate that the target database’s SQLx migration history matches the bundled Runledger migrations.

ensure_schema_compatible_after_idempotency_cutover

Validate that the target database’s SQLx migration history matches the bundled Runledger migrations.

has_framework_constraint_classifier

migrateDeprecated

Apply the bundled Runledger schema migrations to a PostgreSQL pool.

migrate_after_idempotency_cutover

Apply the bundled Runledger schema migrations to a PostgreSQL pool, then enforce the idempotency snapshot cutover.

Type Aliases

DbPool

DbTx

Result