Struct PostgresStore 

pub struct PostgresStore { /* private fields */ }

Fixture reset is available only in the opt-in test_support module, never as a method on a normal store handle.

fn reset(store: &PostgresStore) {
    let _ = store.truncate_all();
}

Query-plan inspection, which refreshes database statistics, is likewise absent from the operational handle:

fn explain(store: &PostgresStore) {
    let _ = store.explain_active_lease_sum(AccountId(1));
}

The same holds for the two sweep plans (GL-65):

fn explain_sweep(store: &PostgresStore) {
    let _ = store.explain_reclaim_due_leases(jiff::Timestamp::UNIX_EPOCH, 256);
}

fn explain_rollover(store: &PostgresStore) {
    let _ = store.explain_due_periods("daily", 0, 256);
}

Implementations

impl PostgresStore

pub async fn connect( url: &str, policy: GrantPolicy, ) -> Result<Arc<Self>, StoreError>

Connect with default pool bounds and run pending migrations.

pub async fn connect_with( url: &str, policy: GrantPolicy, pool_config: PoolConfig, ) -> Result<Arc<Self>, StoreError>

Connect and run pending migrations (versioned under ./migrations, tracked by sqlx’s _sqlx_migrations table — review finding GL-11).

Note the limits of what a pool bound can promise: acquire_timeout covers waiting for a connection, including establishing one, but a query already in flight on a healthy connection is bounded only by a server-side statement_timeout. Callers must still bound their own calls (INVARIANTS.md GL-18).

pub async fn balance(&self, account: AccountId) -> Result<CostUnits, StoreError>

pub async fn usage_recorded( &self, account: AccountId, ) -> Result<CostUnits, StoreError>

pub async fn conservation( &self, account: AccountId, ) -> Result<Option<Conservation>, StoreError>

Trait Implementations

impl AdminStore for PostgresStore

fn create_account<'life0, 'async_trait>( &'life0 self, config: AccountConfig, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, CreateAccountError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn deposit<'life0, 'async_trait>( &'life0 self, account: AccountId, units: CostUnits, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, AllocateError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn set_budget_schedule<'life0, 'async_trait>( &'life0 self, account: AccountId, schedule: Option<BudgetSchedule>, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, BudgetError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Give an account a periodic allowance, or take it away.

fn account_view<'life0, 'async_trait>( &'life0 self, account: AccountId, ) -> Pin<Box<dyn Future<Output = Result<Option<AccountView>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

One account’s administrative state, or None if no such account (GL-121).

fn roll_due_periods<'life0, 'async_trait>( &'life0 self, now: Timestamp, limit: NonZeroUsize, ) -> Pin<Box<dyn Future<Output = Result<RolloverBatch, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Cross the period boundary for up to limit accounts that are past it: expire each closed period’s unspent allowance and deposit the next one, one transaction per batch.

fn set_account_status<'life0, 'async_trait>( &'life0 self, account: AccountId, status: AccountStatus, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<StatusChange>, SetStatusError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Set an existing account’s administrative status, in one transaction: the ledger’s status, and a republication of every live snapshot of that account carrying the new status at generation + 1.

fn set_capacity_class<'life0, 'async_trait>( &'life0 self, account: AccountId, class: CapacityClass, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<StatusChange>, SetStatusError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Set an existing account’s execution-capacity class, in one transaction: the ledger’s class, and a republication of every live snapshot of that account carrying the new class at generation + 1 (GL-99).

fn publish_snapshot<'life0, 'async_trait>( &'life0 self, principal: Principal, snapshot: PublishableSnapshot, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, PublishSnapshotError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Publish a principal’s compiled snapshot.

fn remove_snapshot<'life0, 'async_trait>( &'life0 self, principal: Principal, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

impl KeyDirectory for PostgresStore

fn credential_activity<'life0, 'life1, 'async_trait>( &'life0 self, keys: &'life1 [KeyId], ) -> Pin<Box<dyn Future<Output = Result<Vec<CredentialActivity>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Inspect requested keys in input order, including repeated IDs and retired keys. Every input has one explicit result or the read fails. This operator read uses O(keys.len()) output memory; backends bound individual queries internally. Multiple chunks need not share an instant.

fn insert_key<'life0, 'async_trait>( &'life0 self, record: KeyRecord, ) -> Pin<Box<dyn Future<Output = Result<(), KeyError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Record a minted credential. The caller has already generated the secret and computed its digest; this stores what remains.

fn revoke_key<'life0, 'async_trait>( &'life0 self, key_id: KeyId, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<Revocation, KeyError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Retire one credential, reporting whether it was live.

fn revoke_key_audited<'life0, 'async_trait>( &'life0 self, key_id: KeyId, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<Revocation>, KeyError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Retire a credential and capture its actual owner, key and predecessor under the mutation lock. A repeated revocation returns equal states.

fn publish_key_snapshot<'life0, 'async_trait>( &'life0 self, account: AccountId, key: KeyId, snapshot: PublishableSnapshot, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, KeySnapshotError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Publish snapshot for the principal of account’s credential key, resolved inside the store (GL-143).

fn remove_key_snapshot<'life0, 'async_trait>( &'life0 self, account: AccountId, key: KeyId, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, KeySnapshotError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Withdraw the snapshot of account’s credential key, tombstoning it as AdminStore::remove_snapshot does. Allowed for a revoked credential: revocation does not withdraw its snapshot, and withdrawal is the safe direction.

fn active_keys<'life0, 'async_trait>( &'life0 self, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<Vec<KeyRecord>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Unbounded operator read of every credential valid at now. Serving instances use KeySource pages and an owned, bounded drain instead. Retained for existing direct-store lifecycle tooling; no hidden page cap.

fn account_keys<'life0, 'async_trait>( &'life0 self, account: AccountId, after: Option<KeyId>, limit: NonZeroUsize, ) -> Pin<Box<dyn Future<Output = Result<Vec<KeySummary>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

One account’s credentials, ordered by key_id, for an operator listing (GL-121).

fn insert_key_within<'life0, 'async_trait>( &'life0 self, record: KeyRecord, max_active: NonZeroUsize, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<(), KeyError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Record a credential only if the account holds fewer than max_active live ones, counting and inserting indivisibly (GL-121).

fn insert_key_within_audited<'life0, 'async_trait>( &'life0 self, record: KeyRecord, max_active: NonZeroUsize, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<AdminReceipt<()>, KeyError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Bounded issuance with lifecycle evidence captured under the mutation lock. HTTP administrators must use this receipt rather than synthesize history.

impl KeySource for PostgresStore

fn active_keys_page<'life0, 'async_trait>( &'life0 self, now: Timestamp, after: Option<KeyId>, limit: NonZeroUsize, ) -> Pin<Box<dyn Future<Output = Result<KeyPage, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Read active records in strictly increasing key-id order. Direct stores use now; HTTP servers choose their own clock and return it as as_of. Reads must be coherent with the returned revision, including for an empty result. Never return a partial successful page after a failure.

impl LeaseAllocator for PostgresStore

fn acquire<'life0, 'async_trait>( &'life0 self, account: AccountId, requested: CostUnits, ttl: SignedDuration, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<Allocation, AllocateError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Atomically debit a grant from the account. The granted size follows the backend’s GrantPolicy and may be smaller than requested; the fencing token comes from a strictly increasing per-account sequence. It remains a capability for this lease only; allocating a newer token does not invalidate another active lease.

fn release<'life0, 'async_trait>( &'life0 self, lease_id: LeaseId, fencing_token: FencingToken, unspent: CostUnits, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<(), AllocateError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Graceful return: require the stored (lease_id, fencing_token) pair, credit unspent back, and close the lease. Callers should flush usage first when possible; events arriving after release are accepted only when they fit its provisional settlement loss.

fn consolidate<'life0, 'async_trait>( &'life0 self, lease_id: LeaseId, fencing_token: FencingToken, unspent: CostUnits, requested: CostUnits, needed: CostUnits, ttl: SignedDuration, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<Allocation, AllocateError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Atomically return an active lease’s unspent units and re-grant against the restored balance: release followed by acquire, in one transaction, for the same account the lease names.

fn reclaim_expired_batch<'life0, 'async_trait>( &'life0 self, now: Timestamp, limit: NonZeroUsize, ) -> Pin<Box<dyn Future<Output = Result<ReclaimBatch, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Settle at most limit active leases whose TTL (plus the policy’s reclaim grace) has lapsed and whose holder never released them.

fn reclaim_expired<'life0, 'async_trait>( &'life0 self, now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<Vec<ReclaimedLease>, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Settle every currently expired lease through bounded transactions.

impl SnapshotSource for PostgresStore

fn principals<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<Principal>>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Tombstones included, for the reason MemoryStore::principals gives: forgetting a revoked principal is how one gets resurrected.

A primary-key scan, so no new index — the table holds one row per principal, not per request, and ORDER BY makes the result stable so a caller diffing two enumerations sees real changes rather than storage order.

fn snapshot<'life0, 'async_trait>( &'life0 self, principal: Principal, ) -> Pin<Box<dyn Future<Output = Result<SnapshotResolution, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetch the authoritative state for a principal. Revocation is distinct from never-known so pull, lag recovery, and restart preserve the generation watermark required for anti-resurrection semantics. Reads used to reconstruct reclaimed local history must be linearizable against durable publications/tombstones. Start a new source operation; an earlier cached response or lagging replica cannot establish that principal’s forgotten generation floor. Return an error if this authority is unavailable. MemoryStore and primary PostgresStore reads supply this ordering; HTTP deployments must preserve it end to end.

fn subscribe(&self) -> Receiver<SnapshotPush>

Subscribe to pushes. A lagging receiver may miss updates; the contract is that a fresh snapshot() fetch after a lag error observes at least the newest generation.

impl StoreHealth for PostgresStore

fn ping<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

impl UsageSink for PostgresStore

fn ingest<'life0, 'life1, 'async_trait>( &'life0 self, events: &'life1 [UsageEvent], _now: Timestamp, ) -> Pin<Box<dyn Future<Output = Result<IngestReport, IngestError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Record a batch. Idempotent on request_id; every event must match its stored (lease_id, account_id, fencing_token) capability before lease state and accounting capacity are checked. Partial acceptance is normal — the report says what happened.