PostgreSQL Source

Use the Postgres adapter to verify proposed action values directly against a production relational system of record.

Source configuration

sources:
  billing-production:
    adapter: postgres
    host: postgres.internal
    port: 5432
    dbname: billing
    user: actionrail_reader
    password: ${env:BILLING_DB_PASSWORD}
    sslmode: verify-full
    sslrootcert: /etc/ssl/certs/postgres-ca.pem
    connect_timeout: 5
    statement_timeout_ms: 5000
    require_read_only: true

Field	Default	Constraint
host	—	Required non-empty hostname or address.
port	5432	Integer from 1 to 65535.
dbname	—	Required database name.
user	empty	Dedicated verification role.
password	empty	In the Console, exactly one ${env:VARIABLE} reference.
sslmode	require	disable, allow, prefer, require, verify-ca, or verify-full.
sslrootcert	empty	CA certificate path visible to the SDK process.
connect_timeout	5	1–300 seconds.
statement_timeout_ms	5000	1–300000 milliseconds.
require_read_only	true	Must remain true.

Use verify-full with a trusted CA in production whenever the database deployment supports it.

Rule check

Use Psycopg named parameters:

ground:
  checks:
    - source: billing-production
      query: >-
        SELECT customer_id, status, refundable_balance
        FROM orders
        WHERE order_id = %(value)s
          AND workspace_id = %(workspace_id)s
      match:
        - column: customer_id
          ctx: customer_id
        - column: status
          value: delivered
        - column: refundable_balance
          op: gte
          arg: amount

Available bindings include %(value)s, scalar tool arguments, and scalar trusted-context fields.

Defense in depth

For each check, ActionRail:

1. opens a new Psycopg connection with application_name=actionrail;
2. applies the configured connection and statement timeouts;
3. forces the transaction into PostgreSQL read-only mode;
4. executes the parameterized query;
5. rolls back and closes the connection even after an error.

The database role is still the primary authorization boundary. Create a dedicated SELECT-only role limited to the schemas, tables, views, and rows required for verification. Do not reuse an application writer or database-owner credential.

Consider exposing purpose-built read views that contain only the fields a grounding rule needs.

Driver installation

For a self-contained local driver:

python -m pip install "psycopg[binary]>=3.2,<4"

Production environments can use a system-linked Psycopg/libpq build. The SDK raises a clear driver error if no usable Psycopg 3 implementation is available.

Performance guidance

• Index every lookup key used by a grounding query.
• Return only the fields used by match conditions.
• Keep the default statement timeout or lower it for interactive agents.
• Avoid locks and long-running analytical queries.
• Monitor Source failures and pending agent calls during database incidents.

Grounding runs synchronously in the action gate. Database latency is therefore part of consequential tool-call latency.