reliant forge db query, which reads as a role forge generates from your migrations, inside a READ ONLY transaction, and records every call.
The seam is that your migrations are the schema. forge generate decides, column by column, what the read-only role forge_ro may select, and the migrator applies those grants after every migration run. Safe migrations explains how the grants converge.
Before you begin
- A Forge project with a database, deployed to a hosted environment: Deploy a Go API with managed Postgres.
- Forge v1.6.1 or later in the project (
reliant forge --version). - The organization’s
db:querygrant. Owners and admins hold it. - An agent that runs commands as you. In a Reliant chat, the agent’s shell is signed in as you, so its queries are recorded under your name.
1
Decide every credential-like column
Lint refuses a column whose name looks like a credential until someone decides it. This table has an Mark it secret in the migration. If the column has already shipped, write a new migration instead:
api_key:terminal
Output
db/migrations/20261120090758_create_tasks.up.sql
forge:readable <why> grants a column that only looks like a credential. A credential in a column with a neutral name, such as config, needs forge:secret even though lint can’t spot it. Re-run lint; it ends ✅ All 1 gating linters passed.2
Generate the grants and ship them
terminal
db/grants/readonly/public.tasks_gen.sql
3
Tell your agent how to read production
Add the rule to the instructions your agent loads: the project’s
reliant.md memory file in Reliant, or AGENTS.md in another harness:reliant.md
--json gives the agent ok, exit_code, columns and rows to parse. reliant forge agent skill load db/query is the full reference, and agents in a Forge project can load it themselves.4
Run a query against production
terminal
Output
forge_ro; you hold no database password. The footer names the live release and the audit record.5
Verify the boundary holds
Ask for what the agent must not get. Each of these exits 1:
The last write got past forge’s text check and Postgres refused it. Naming the readable columns works:
select id, title, owner from tasks limit 5 returns rows.6
Check the record
terminal
Output (trimmed)
BY is the account that ran the query: here, the person whose chat the agent ran in. The control plane’s audit log keeps each statement in full, with its reason.What this does not do
- It never writes. Data fixes belong in a migration or application code, reviewed like any change.
- On dev it reads as your app’s own role.
db query devconnects with the devDATABASE_URL(current_userispostgres), so secret columns are readable there. To check the role before you ship, ask Postgres:select has_column_privilege('forge_ro', 'tasks', 'api_key', 'SELECT')returnedfalseon the local stack. - It doesn’t let an unattended run into an audited environment. Production is
auditedby default, which admits people only. An organization automation token is refused. A machine token works only on an environment whosedata_accessisopen, and only with thedb:queryscope. See Managed Postgres. - The forge MCP server has no query tool. An agent in another harness needs a shell with
reliant forgesigned in. - It caps each query: one at a time per person per environment, 30 a minute, 200 rows by default (10,000 at most) and a 5-second timeout (30 at most).
Troubleshooting
this environment is audited: confirm_env_id must equal the environment id
this environment is audited: confirm_env_id must equal the environment id
Pass
--confirm-env <env>, the environment name again, and --reason "<why>". Both are required on any environment that isn’t local or ephemeral.permission denied for table tasks
permission denied for table tasks
The query touched a column
forge_ro can’t read: a forge:secret column, an undecided credential-like one, or any column through select *. Name the readable columns. To make a column readable, mark it forge:readable <why> in a migration and deploy.exit 2
exit 2
Forge could not look, so treat the result as not answered, never as no rows.
env prod does not exist on its control plane yet means nothing is deployed there; credential_missing in --json means the environment’s read-only role isn’t provisioned yet.Next steps
How Forge keeps migrations safe
The read-only role, convergent grants and rollback floors.
Managed Postgres
Data access policy, backups and restore.
Debug production with an AI agent
Pair the rows with logs, traces and errors.
Deploy a Go API
Ship the database this guide queries.