Read-only Enforcement
Block every write and DDL statement for an agent credential. Reads pass, writes are rejected in the wire protocol before they reach your database.
Read-only is the safest access mode for an agent. With it, PgBeam allows reads
and rejects every INSERT, UPDATE, DELETE, and DDL statement before it
reaches your database. The agent receives an LLM-readable reason, so it can
adjust instead of failing blind.
Turn it on
pgbeam policies create --name read-only --mode read_only
# → Policy profile created: pol_1a2b3c…
pgbeam agents create --name analytics-bot --policy pol_1a2b3c…A credential's policy is fixed at creation. To move an existing credential to a different policy, rotate or re-issue it against the new profile.
In the dashboard, set Access mode to Read-only on the policy profile.
What is allowed and blocked
| Statement | Read-only |
|---|---|
SELECT | Allowed |
WITH … SELECT (read-only CTE) | Allowed |
EXPLAIN of a read | Allowed |
INSERT / UPDATE / DELETE | Blocked |
CREATE / ALTER / DROP / TRUNCATE | Blocked |
COPY | Blocked |
Data-modifying CTE (WITH … UPDATE) | Blocked |
What the agent sees
A blocked write comes back as a Postgres error (SQLSTATE 42501):
ERROR: blocked by PgBeam agent policy: this credential is read-only; update is not permitted; only SELECT, SHOW, and EXPLAIN are allowedThe error is written to be read by an LLM, so an agent can correct its plan and retry within the rules.
Fails closed
A multi-statement batch is rejected if any statement in it would be blocked. Unparseable SQL and unknown statement types are rejected too. This prevents an agent from slipping a write past the parser.
Need writes sometimes?
Read-only is the right default. When an agent genuinely needs to write, read-write mode with a tight allowlist is one option. Sandbox writes let an agent write freely against an isolated, throwaway branch without touching production, and approvals hold a production write until a human signs off.