> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Let AI agents query production data read-only

> Give an AI agent audited, read-only SQL access to production with forge db query: Postgres withholds secret columns, refuses writes and every query is recorded.

By the end of this guide an AI agent can answer questions from your production database with one command, and Postgres, not a prompt, stops it from writing anything or reading a credential. The agent runs [`reliant forge db query`](https://docs.reliantlabs.io/reference/cli#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](https://docs.reliantlabs.io/deep-dives/safe-migrations.md#the-read-only-role-and-secret-columns) 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](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md).
* Forge v1.6.1 or later in the project (`reliant forge --version`).
* The organization's `db:query` grant. 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 `api_key`:

```bash terminal theme={null}
reliant forge lint --db-grants
```

```text Output theme={null}
❌ db-grants — 1 error
   ✗ db/migrations/20261120090758_create_tasks.up.sql:14 [forge-db-grants-undecided] tasks.api_key looks like a credential and nobody decided it: forge_ro cannot read it
```

Mark it secret in the migration. If the column has already shipped, write a new migration instead:

```sql db/migrations/20261120090758_create_tasks.up.sql theme={null}
COMMENT ON COLUMN tasks.api_key IS 'forge:secret';
```

`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**

```bash terminal theme={null}
reliant forge generate
```

The table's row in the read-only grants leaves the secret out:

```sql db/grants/readonly/public.tasks_gen.sql theme={null}
('public', 'tasks', ARRAY['created_at', 'done', 'id', 'owner', 'title', 'updated_at']::text[])
--   public.tasks: api_key  (forge:secret, withheld)
```

Commit, then cut and deploy a release as in [Deploy a Go API](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md). The migration job applies the grants before the new release serves.

**3. Tell your agent how to read production**

Add the rule to the instructions your agent loads: the project's [`reliant.md` memory file](https://docs.reliantlabs.io/settings/memories) in Reliant, or `AGENTS.md` in another harness:

```markdown reliant.md theme={null}
Read production data only with:
  reliant forge db query prod "<one SELECT>" --confirm-env prod --reason "<why>" --json
Prefer aggregates and LIMIT. Exit 1 means the query was refused; exit 2 means it was not answered.
```

`--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**

```bash terminal theme={null}
reliant forge db query prod "select current_user" \
  --confirm-env prod --reason "docs guide verification"
```

```text Output theme={null}
current_user
forge_ro
(1 row, 4 ms; release v6.5.0; audit e2cd93ae-bef7-4b70-b971-dae365824e5b)
```

The platform runs the query inside the environment as `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:

| Query | Refused with |
| - | - |
| `select api_key from tasks` | `permission denied for table tasks` |
| `select * from tasks` | `permission denied for table tasks` |
| `select row_to_json(t) from tasks t` | `permission denied for table tasks` |
| `update tasks set done = true` | `only SELECT, WITH, TABLE, VALUES, SHOW and EXPLAIN statements are allowed; got UPDATE` |
| `with x as (update tasks set done = true returning id) select count(*) from x` | `this connection is read-only: cannot execute SELECT in a read-only transaction` |
| any query without `--confirm-env prod --reason` | `this environment is audited: confirm_env_id must equal the environment id` |

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**

```bash terminal theme={null}
reliant forge obs changes prod
```

```text Output (trimmed) theme={null}
TIME            KIND       WHAT                                              BY
11-20 09:14:45  activity   query database database guides-sandbox-dbquery    you@example.com
11-20 09:14:22  activity   query database database guides-sandbox-dbquery    you@example.com
11-20 09:09:43  promotion  promoted v6.5.0                                   you@example.com
```

`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 dev` connects with the dev `DATABASE_URL` (`current_user` is `postgres`), 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')` returned `false` on the local stack.
* It doesn't let an unattended run into an audited environment. Production is `audited` by default, which admits people only. An organization automation token is refused. A machine token works only on an environment whose `data_access` is `open`, and only with the `db:query` scope. See [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md#read-the-data-safely).
* The [forge MCP server](https://docs.reliantlabs.io/hosting/observability/agents.md#it-speaks-mcp) has no query tool. An agent in another harness needs a shell with `reliant forge` signed 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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [card] [How Forge keeps migrations safe](https://docs.reliantlabs.io/deep-dives/safe-migrations.md)
>
> The read-only role, convergent grants and rollback floors.

> [card] [Managed Postgres](https://docs.reliantlabs.io/hosting/managed-postgres.md)
>
> Data access policy, backups and restore.

> [card] [Debug production with an AI agent](https://docs.reliantlabs.io/guides/observability/debug-production-with-ai-agent.md)
>
> Pair the rows with logs, traces and errors.

> [card] [Deploy a Go API](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md)
>
> Ship the database this guide queries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.