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. Single checks
use the same separate logical-key, counter-row, and capacity-shard lock
phases so every statement that tests row absence starts after the logical
key lock has been acquired.
PostgresLimiter implements runlimit_core::Limiter for async generic
adapters.
The optional serde feature enables validated PostgresConfig loading
and the corresponding runlimit-core policy and response metadata.
§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 versions as
unknown. The first 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 application-owned migrations, in order, using
CREATE_RUNLIMIT_FIXED_WINDOWS_SQL and
SET_RUNLIMIT_FIXED_WINDOWS_FILLFACTOR_SQL followed by
BOUND_RUNLIMIT_FIXED_WINDOW_CARDINALITY_SQL instead of invoking either
Runlimit migrator against the shared history.
§Storage capacity
Every counter belongs to one of CAPACITY_SHARD_COUNT persistent shards.
The migration-maintained ledger enforces
HARD_MAX_ROWS_PER_SHARD even for older replicas, while
PostgresConfig::maximum_rows_per_shard lets current replicas fail closed
at a lower operational bound. A full shard denies only new storage keys;
existing rows remain usable and active rows are never evicted. Expiry alone
does not release a row. Capacity becomes reusable only after
PostgresLimiter::cleanup_expired commits its deletion.
§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.
Once the database has produced a denial, an explicit rollback failure or
deadline cannot replace that valid decision; the connection is discarded so
closing it rolls back the non-mutating denied transaction.
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 acquisition and
operation budgets 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.
The persisted capacity-shard derivation is likewise a cross-replica
protocol: it XORs the leading bytes of the policy fingerprint and opaque
subject key. Changing the derivation or shard count requires a new storage
protocol and migration.
§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.
Constants§
- BOUND_
RUNLIMIT_ FIXED_ WINDOW_ CARDINALITY_ SQL - SQL for the additive
20260726000000_bound_runlimit_fixed_window_cardinalitymigration. - CAPACITY_
SHARD_ COUNT - Number of stable capacity shards used by
PostgreSQLstorage. - CREATE_
RUNLIMIT_ FIXED_ WINDOWS_ SQL - SQL for the immutable
20260723000000_create_runlimit_fixed_windowsmigration. - HARD_
MAX_ ROWS_ PER_ SHARD - Database-enforced maximum number of fixed-window rows in one capacity shard.
- SET_
RUNLIMIT_ FIXED_ WINDOWS_ FILLFACTOR_ SQL - SQL for the additive
20260725000000_set_runlimit_fixed_windows_fillfactormigration.
Statics§
- MIGRATOR
- Raw bundled migrations required by
PostgresLimiter.