pg_risk

pg_risk is a Rust/pgrx PostgreSQL extension for deterministic, auditable policy decisions over financial and operational requests. It evaluates exact amount, rolling-volume, count, balance, exposure, hold, destination, reconciliation, and FX-quote rules without moving funds or calling a network.

PostgreSQL 14–18, Rust 1.96+, and pgrx 0.19.2 are supported.

Build and install

cargo install cargo-pgrx --version 0.19.2 --locked
cargo pgrx init --pg18=/path/to/pg_config
./install.sh --pg-config /path/to/pg_config

CREATE EXTENSION pg_risk;

The extension has no hard dependency on another RustedBytes extension. If an optional extension is installed later, enable its adapter explicitly:

SELECT risk_enable_pg_ledger();
SELECT risk_enable_pg_fx();
SELECT risk_enable_pg_money();
SELECT risk_enable_pg_cryptocurrency();
SELECT risk_enable_pg_reconcile();
SELECT risk_enable_pg_crypto();

For large pg_ledger accounts, remove first-request synchronization latency by warming the exact metric cache during deployment:

SELECT * FROM risk_ledger_cache_refresh(:'ledger_account_id');

Basic use

SELECT risk_subject_create('CUSTOMER', 'customer-123', 'retail') AS customer_id \gset
SELECT risk_policy_create(
    name      => 'retail-withdrawal',
    operation => 'WITHDRAWAL',
    segment   => 'retail'
) AS policy_id \gset

SELECT risk_rule_create(
    policy_id => :'policy_id',
    name      => 'daily-usd-50k',
    rule_kind => 'ROLLING_VOLUME_LIMIT',
    config    => '{"asset":"USD","window":"24 hours","max_units":"5000000"}'
);

SELECT * FROM risk_check(
    subject_id      => :'customer_id',
    operation       => 'WITHDRAWAL',
    input_amount    => 'USD 1000',
    idempotency_key => 'withdrawal:request-456'
);

risk_check persists an immutable decision and its complete policy snapshot. risk_evaluate returns the same shape without persisting. Exact amounts are stored as integer smallest units; USDT@ethereum and USDT@tron remain different assets.

Strict checks first lock the subject and operation, then sorted ledger-account and exposure-group scopes selected by applicable rules. This serializes cross-asset requests that converge on the same output balance as well as shared exposure requests before history is read. The decision does not execute a ledger transaction or FX quote; perform that operation in the same database transaction after an allowed decision.

See API, rules, architecture, concurrency, and security.

Development

cargo fmt --all -- --check
cargo clippy --all-targets --no-default-features --features pg18 -- \
  -D warnings -W clippy::pedantic
./ci/test-extension.sh "$(cargo pgrx info pg-config 18)"