Skip to main content

Crate reliar_store_postgres

Crate reliar_store_postgres 

Source
Expand description

reliar-store-postgres is Reliar’s PostgreSQL provider: the schema, the explicit migrate API, and PostgresOutboxStore — the only crate where an sqlx/Postgres type appears (ADR 0002).

§Quickstart

use reliar_store_postgres::{PostgresOutboxStore, migrate};
use reliar_outbox::OutboxEnqueue;
use reliar_core::Message;
use sqlx::postgres::PgPoolOptions;

#[derive(serde::Serialize, serde::Deserialize)]
struct OrderPlaced {
    order_id: String,
}

impl Message for OrderPlaced {
    const TYPE: &'static str = "orders.placed";
    const VERSION: u16 = 1;
}

let database_url = std::env::var("DATABASE_URL")?;
let pool = PgPoolOptions::new().connect(&database_url).await?;

// Run once, out of band — never implicitly at startup.
migrate(&pool, Default::default()).await?;

let store = PostgresOutboxStore::new(pool.clone()).await?;

let mut tx = pool.begin().await?;
store.enqueue(&mut tx, OrderPlaced { order_id: "ord_1".into() }).await?;
tx.commit().await?;

// Hand `store` to an `OutboxDispatcher` to publish what was just enqueued.

§MSRV

This crate declares rust-version = "1.94", six releases above the workspace floor (1.88): sqlx 0.9 requires it. Pure crates (reliar-core, reliar-outbox) stay reachable on 1.88 for hosts bringing their own store (ADR 0025).

§Features

§search_path setup

Every Reliar object lives in one configurable schema, reliar by default, with unprefixed table names (outbox). sqlx::query! checks SQL at compile time, so every identifier in every statement is a static, unqualified literal — the schema is resolved at connection time through search_path, never compiled in (ADR 0017).

  • The host puts reliar first on the connection URL: ?options=-c%20search_path%3Dreliar,public.
  • Behind a transaction-mode pooler that drops startup options (some reject the parameter outright with 08P01), use a server-side default instead: ALTER ROLE <app> SET search_path = reliar, public. This is the portable mechanism — verify it against your own pooler build/version rather than assuming: PgDog (ghcr.io/pgdogdev/pgdog:v0.1.46, the pooler this crate’s suite runs behind) was found to pass the options parameter through to the upstream server instead of dropping it, so the URL-options path above works unmodified behind it too, with no ALTER ROLE required — but a different pooler, or a different PgDog configuration, could behave either way.
  • PostgresOutboxStore::connect/PostgresOutboxStore::new verify once at construction that the unqualified name outbox resolves to the configured schema, and fail fast — naming the configured schema, the observed search_path, and the ALTER ROLE remedy — rather than surprise-failing on the first acquire.
  • migrate does not depend on the caller’s search_path: it creates the schema itself and qualifies its own bookkeeping table name (ADR 0018).

§PostgreSQL version floor

PostgreSQL 18 or later is a hard requirement, with no older-version fallback (ADR 0015, amended by ADR 0041 / human decision #47). PostgresOutboxStore::connect and migrate each check the connected server’s server_version_num against MIN_SERVER_VERSION_NUM — once per entry point, never per pooled connection — and fail with PostgresStoreError::UnsupportedServerVersion / MigrateError::UnsupportedServerVersion below it, naming the required and detected version. There is no conditional DDL, no uuidv7() substitute, and no degraded mode.

§Guarantees

  • Migrations never run implicitly. migrate is the only entry point, and it is idempotent and safe under concurrent callers.
  • The claim is one statement. PostgresOutboxStore’s acquire (via reliar_outbox::OutboxStore) uses a FOR UPDATE SKIP LOCKED claim that commits before the call returns; no network I/O ever happens while a Reliar transaction is open (ADR 0006).
  • Enqueuing joins the caller’s own transaction — PostgresOutboxStore implements reliar_outbox::OutboxEnqueue directly, no facade type in between, and atomicity is visible in the signature — and performs no I/O beyond the one INSERT (plus, opt-in, a search_path wrap).

Structs§

JsonSerializerjson
The default Serializer: JSON via serde_json. Ships behind the default json feature; disable it to supply a different wire format (ADR 0010).
MigrateOptions
Where migrate creates Reliar’s schema and its bookkeeping table.
PostgresOutboxSettings
What is provider-specific about the outbox. Everything portable lives in reliar_outbox::OutboxSettings.
PostgresOutboxStore
Reliar’s PostgreSQL outbox provider. Cheap to clone into an AppState — it wraps a PgPool; no outer Arc required. The connection pool stays the host’s: Reliar never owns or reads a DATABASE_URL.

Enums§

EnqueueError
crate::PostgresOutboxStore’s reliar_outbox::OutboxEnqueue::enqueue_envelope failures. Enqueuing runs on the host’s write path, where the host decides whether to retry its own transaction, so this implements Classify on the same rules as PostgresStoreError rather than making the host re-derive which SQLSTATEs are worth retrying.
MigrateError
migrate’s failure. Provider-owned, not a re-export of sqlx::migrate::MigrateError: a rejected schema identifier has no variant in sqlx’s own type to report it as, since that check happens before any sqlx::migrate code runs at all.
PostgresStoreError
A failure of a crate::PostgresOutboxStore OutboxStore/OutboxDeadLetters call — never a property of one row’s content. Row-content problems surface as reliar_outbox::PoisonedRows instead (ADR 0008).
SettingsError
Why a *Settings::from_env call failed. OutboxSettings::from_env (reliar-outbox) was the first caller; every provider’s own from_env returns this same type, so a host wiring several from_env calls handles one error type for the whole family.

Constants§

MIN_SERVER_VERSION_NUM
The floor this crate enforces, in PostgreSQL’s own server_version_num encoding (major * 10_000 + minor) — 180_000 for PostgreSQL 18.0. Public so a host can state the same requirement in its own preflight without hard-coding the number (ADR 0041). There is no older-version fallback: a server below this reports crate::PostgresStoreError::UnsupportedServerVersion or crate::MigrateError::UnsupportedServerVersion, never a degraded mode.

Functions§

migrate
Applies Reliar’s migrations. Never invoked implicitly. pool must reach a PostgreSQL 18 or later server — a hard requirement, with no older-version fallback, checked here as the first statement on this function’s dedicated connection (ADR 0041 / human decision #47): a server below the floor returns MigrateError::UnsupportedServerVersion before the schema is created or any migration file runs.