Policies

A policy profile is the named bundle of rules PgBeam enforces for an agent credential. Access mode, allowlists, masking, budgets, and timeouts.

A policy profile is a named bundle of rules attached to one or more credentials. It is the single place you decide what a principal can do: read-only or read-write, which tables and columns it can touch, which rows it can see, which columns are masked, and how much it can run. Policies stream to the data planes and hot-reload, so a change takes effect on the next query without restarting anything.

Policies apply to agent credentials and to human credentials alike. Every rule below works the same whether an AI agent or a person runs the statement. See human and passthrough connections for applying policies beyond per-agent credentials.

What a policy contains

Rule	What it controls	Page
Access mode	Read-only or read-write, plus per-statement-type rules.	Read-only
Table allowlist	The schemas and tables the principal may read or write.	Allowlists
Column allowlist	The columns within an allowed table the principal may select.	Allowlists
Row filters	A `WHERE` predicate that scopes a table to a slice of rows.	Row-level policies
Masking rules	Columns redacted, nulled, or hashed in flight.	Masking
Query budgets	Queries per window, max rows per result, statement timeout.	Budgets
Approvals	Hold writes or DDL until a human approves them.	Approvals
Migration linting	Warn or block dangerous DDL (locks, rewrites, unsafe drops).	Safe migrations
Sandbox target	Route writes to a throwaway branch or roll them back.	Sandbox writes

Create and attach a policy

pgbeam policies create analytics-readonly \
  --mode read-only \
  --allow public.orders,public.users \
  --mask users.email=hash \
  --budget 5000/day --max-rows 1000

pgbeam agents attach analytics-bot --policy analytics-readonly

Go to Policies, create a profile, set the rules, then attach it to one or more agents from the Agents tab.

curl -X POST https://api.pgbeam.com/v1/projects/{projectId}/policies \
  -H "X-API-Key: pbo_..." \
  -d '{
    "name": "analytics-readonly",
    "mode": "read-only",
    "allow": ["public.orders", "public.users"],
    "mask": [{"column": "users.email", "kind": "hash"}],
    "budget": {"queries_per_day": 5000, "max_rows": 1000}
  }'

Enforcement model

PgBeam parses every statement a principal sends and checks it against the attached policy before forwarding it. Enforcement fails closed: unparseable SQL, unknown statement types, COPY, and multi-statement batches containing any blocked statement are rejected with an LLM-readable reason.

Hot reload

Policy changes stream to the data planes and apply on the next query. You do not need to rotate the credential or reconnect the principal.

Human and passthrough connections

A policy can bind to more than a per-agent credential. Every credential carries a principal_type: agent for an AI agent's credential, human for a person's. The rules are identical; the field records who is connecting so the audit log and anomaly baselines can tell agents and people apart.

You can also apply policies to connections that are not per-principal credentials at all:

Scope	What it covers
Project default policy	A baseline policy applied to every connection on the project, including your application's passthrough connection.
Per-database policy	A policy that overrides the project default for one database.
Per-credential policy	The policy attached to a single agent or human credential.

The most specific scope wins: a per-credential policy overrides a per-database policy, which overrides the project default. Leave the project default unset to keep passthrough connections unrestricted, the original PgBeam behavior, and opt individual credentials into policies one at a time.

Turning the gateway into a database firewall

Set a project default policy to enforce row filters, masking, or read-only rules on every connection, not just agents. Your own application can then read through the same guardrails an agent does, scoped per database where you need a different rule.

Policies

What a policy contains

Create and attach a policy

Enforcement model

Human and passthrough connections

Related

On this page