reliar-store-postgres 0.9.0

//! `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
//!
//! `PostgresOutboxStore::new` is the default-type-param constructor, gated on the default
//! `json` feature; without it this block still shows the shape but is not compiled.
#![cfg_attr(not(feature = "json"), doc = "```ignore")]
#![cfg_attr(feature = "json", doc = "```no_run")]
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! 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());
//!
//! 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.
//! # Ok(())
//! # }
//! ```
//!
//! # 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
//!
//! - `json` (**default**) — [`PostgresOutboxStore<JsonSerializer>`]'s default type parameter
//!   and the [`PostgresOutboxStore::new`]/[`PostgresOutboxStore::with_settings`] convenience
//!   constructors (forwards `reliar-core/json`). Not hard-enabled: a deployment supplying its
//!   own [`reliar_core::Serializer`] should not have to pull in `serde_json`. Under
//!   `--no-default-features`, [`PostgresOutboxStore::with_serializer`] is the only constructor.
//! - `serde` (off by default) — `Serialize`/`Deserialize` on [`PostgresOutboxSettings`],
//!   `#[serde(default, deny_unknown_fields)]` so a typo'd config key is a hard error, durations
//!   as integer milliseconds. `serde` itself is always a dependency regardless of this feature —
//!   it also drives the crate's private `MetadataRest` JSONB contract (ADR 0012), which is not
//!   feature-gated.
//!
//! # `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.
//! - **Reliar does not verify this at startup** (ADR 0047). Constructing a store issues no
//!   query; a `search_path` that does not resolve `outbox`/`inbox` surfaces at the first store
//!   call as [`PostgresOutboxError::NotMigrated`]/[`PostgresInboxError::NotMigrated`], whose
//!   message names both the `migrate()` and the `ALTER ROLE` remedy. Reliar never sets
//!   `search_path` on a pool it does not own — not at construction, not per call.
//! - [`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
//!
//! **Requirements: PostgreSQL 18 or later.** Reliar does not check the server version; behaviour
//! on older servers is undefined. Neither a store constructor nor [`migrate`] issues a version
//! probe: a server below the floor is unsupported and fails at whichever statement first needs a
//! PostgreSQL 18 feature (`uuidv7()`, in practice) — there is no conditional DDL, no substitute,
//! and no degraded mode (ADR 0015, ADR 0047 Amendment B).
//!
//! # Guarantees
//!
//! - **Migrations never run implicitly.** [`migrate`] is the only entry point, and it is
//!   idempotent and safe under concurrent callers.
//! - **A store constructor performs no I/O** (ADR 0047) — no query, no connection, no schema or
//!   version check; it can run inside a `OnceLock`, a `Default` impl, or a synchronous `main()`.
//! - **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`.

#![cfg_attr(docsrs, feature(doc_cfg))]
#![forbid(unsafe_code)]
#![warn(missing_docs)]

mod connection;
mod duration_serde;
mod error;
mod inbox;
mod migrate;
mod outbox;
mod records;
mod settings;

pub use inbox::{PostgresInboxError, PostgresInboxStore};
pub use migrate::{MigrateError, MigrateOptions, migrate};
pub use outbox::{EnqueueError, PostgresOutboxError, PostgresOutboxStore};
pub use reliar_core::SettingsError;
pub use settings::{PostgresInboxSettings, PostgresOutboxSettings};

#[cfg(feature = "json")]
#[cfg_attr(docsrs, doc(cfg(feature = "json")))]
pub use reliar_core::JsonSerializer;

// The README's Usage block drives `PostgresOutboxStore::new`, the default-type-param
// constructor that only exists under `json`; gate the whole module rather than editing static
// markdown to carry a per-block cfg_attr.
#[cfg(all(doctest, feature = "json"))]
mod readme_doctests;