Module sql 

Available on crate feature serve and (crate features serve-history-postgres or serve-history-sqlite) only.

Shared SQL run-history machinery for the Postgres and SQLite backends (Phase 5, #127). Both backends are identical except for the connection setup and the placeholder dialect ($n vs ?), so the schema, prepared-statement text, pure helpers, and the entire RunHistory impl live here once and are instantiated for each concrete sqlx pool via the impl_sql_history! macro.

Portability: every column is TEXT (timestamps are stored as fixed-width RFC3339 with nanosecond precision + Z, which sorts lexicographically in chronological order, so keyset pagination and expiry comparisons work without any database date type — and thus without the sqlx chrono feature). The whole RunRecord is serialized into the body column (the source of truth on read); the dedicated columns exist only for filtering, ordering, and expiry.

Idempotency lives in a separate faucet_serve_idem table whose key primary key is the required unique index (spec §10/§11). The claim is atomic via INSERT … ON CONFLICT DO NOTHING plus an optimistic, expiry-guarded takeover UPDATE, mirroring the memory backend’s shard-locked semantics.

Structs

Stmts

Prepared-statement text for a backend, built once per dialect at connect time.

Enums

Dialect

SQL placeholder dialect.

Constants

CLAIM_ATTEMPTS

Bounded retry count for the atomic idempotency claim (handles a claim being purged concurrently between the insert attempt and the read-back) and for the read-max-then-insert paths (template versions, launch-log seqs).

DDL

DDL run at connect time. Valid verbatim on both Postgres and SQLite (only TEXT columns, IF NOT EXISTS, and standard indexes).

Functions

decode_body

decode_json

encode_body

encode_json

Generic body (de)serialization for the catalog tables (#279).

fmt_ts

Fixed-width RFC3339 (nanoseconds + Z) — lexicographically sortable.

is_expired

True when a claim timestamped claimed_at (RFC3339) is older than window. An unparseable or future timestamp is treated as not expired (safe: it won’t be silently re-claimed).

pad_seq

Zero-pad a run-log sequence to a fixed 20 digits (the width of u64::MAX) so it sorts lexically = numerically as a TEXT column (#529).

parse_status

parse_ts

Inverse of fmt_ts. An unparseable value falls back to now rather than failing the read: a single corrupt timestamp must not make a whole template or audit row unusable, and every caller uses the value for display/ordering only.

retry_backoff

Sleep before a read-max-then-insert retry (no-op on the first attempt).

threshold

RFC3339 timestamp window before now (the purge / expiry threshold).

unpad_seq

Inverse of pad_seq; a malformed value falls back to 0.