Expand description
Replica-safe PostgreSQL storage for Runlimit fixed-window policies.
PostgresLimiter implements the same anchored fixed-window model as the
in-memory backend: the first admitted check starts a window, and subsequent
checks share that window until it expires. PostgreSQL’s clock is the sole
time authority, so callers on different hosts do not need synchronized
clocks. Atomic batches use set-based lock, preflight, and update phases, so
their number of SQL phases does not grow with the batch size.
§Installation
Call PostgresLimiter::migrate before serving traffic. It can share
SQLx’s _sqlx_migrations table with application migrations only when every
participating Migrator configures
Migrator::set_ignore_missing to true.
A strict application migrator will reject Runlimit’s migration version as
unknown. The migration creates runlimit_fixed_windows in the connection’s
default schema.
MIGRATOR is the raw bundled migrator with SQLx’s strict defaults. It is
intended for an exclusively managed migration history and connection. It
does not add PostgresLimiter::migrate’s protection against returning a
possibly session-locked connection to a pool after an error or cancellation.
Applications that retain a strict host migrator should vendor the bundled
Runlimit SQL as an application-owned migration instead of invoking either
Runlimit migrator against the shared history.
§Failure semantics
Pre-commit database failures and pre-commit timeouts mean the transaction
did not commit. A
CheckError::CommitOutcomeUnknown or CheckError::CommitTimedOut error
means PostgreSQL may have committed even though the client did not receive
confirmation. CheckError::CommittedResponseInvariant means the commit
was confirmed but its response was unusable. Fail closed in all three cases,
and do not blindly retry a check that may already have consumed quota.
Dropping a check or cleanup future prevents the backend from reporting its
outcome; if cancellation races with commit, callers must likewise treat the
outcome as unknown. Prefer this backend’s configured deadline to a shorter
outer timeout.
The advisory-lock v1 domain and derivation are a cross-replica protocol.
They must not be changed in place: replicas from a rolling deployment must
calculate identical lock IDs for the same persistent counter. PostgreSQL’s
advisory-lock namespace is shared by every application in the same database.
An unrelated or deliberately held matching bigint lock therefore blocks
the affected Runlimit key until the operation deadline; use a trusted
database boundary and restrict advisory-lock privileges for unrelated roles.
§Integration tests
The database tests are opt-in:
RUNLIMIT_POSTGRES_TEST_DATABASE_URL=postgresql:///runlimit_test \
cargo test -p runlimit-postgres --test postgres -- --ignoredStructs§
- Postgres
Config - Runtime bounds for
PostgreSQLadmission work. - Postgres
Limiter - A replica-safe rate limiter backed by a
PostgreSQLpool.
Enums§
- Check
Error - Failure from a quota check.
- Maintenance
Error - Failure from bounded expired-window cleanup.
- Postgres
Config Error - Invalid
PostgreSQLbackend configuration.
Statics§
- MIGRATOR
- Raw bundled migrations required by
PostgresLimiter.