Recipe · Database

How to make AI agents schema-aware (Postgres / Supabase)

TL;DR: Out of the box, Claude Code, Cursor, and Codex know nothing about your database. Wire agentmako's DB tools once and your agent can inspect tables, RLS policies, and RPC bodies the same way it inspects code. Tools used: db_table_schema, db_rls, db_rpc, schema_usage, tenant_leak_audit, db_reef_refresh.

The scenario

You need to add a billing_status column to the organizations table, with an RLS policy that lets owners read/write but lets members read only. Then update every code site that reads from organizations so it knows about the new column. Then verify multi-tenant isolation hasn't regressed.

Connect agentmako to your database

One-time setup. From the project root:

$ agentmako connect .            # interactive, prompts for DB URL
# or for CI:
$ agentmako connect . --db-env DATABASE_URL --yes

Credentials live in your OS keychain via @napi-rs/keyring. Project config files store keychain references, not plaintext URLs. The DB tools are read-only by default.

Step 1 — inspect the current schema

{
  "tool": "db_table_schema",
  "args": { "schema": "public", "table": "organizations" }
}

Returns columns, indexes, FKs, RLS state, triggers. Now the agent (and you) know exactly what shape the table is and which columns are nullable, generated, or constrained.

Step 2 — read the existing RLS policies

{
  "tool": "db_rls",
  "args": { "schema": "public", "table": "organizations" }
}

You see all current policies. Useful before adding new ones — you don't want to introduce a policy that overlaps or contradicts an existing rule.

Step 3 — find every app-code site that reads the table

{
  "tool": "schema_usage",
  "args": { "schema": "public", "object": "organizations" }
}

Returns every call site in the codebase that touches the organizations table — Supabase .from("organizations"), raw SQL strings, RPC calls, and definition sites. This is your edit list.

Step 4 — write the migration, then refresh Reef

Write the SQL migration (column add + RLS policy add). Apply it. Then tell Mako the DB schema changed:

{
  "tool": "db_reef_refresh",
  "args": {}
}

Without this, subsequent queries to db_table_schema and schema_usage would return stale results. With it, the next call sees the new column.

Step 5 — update the app code, then audit RLS posture

Edit each call site from Step 3 to read/write the new column as needed. Then sanity-check that you haven't introduced a cross-tenant leak:

{
  "tool": "tenant_leak_audit",
  "args": {}
}

Audits tenant-keyed tables and RLS posture across the project. Flags tables where reads happen without a tenant scope, RPCs that bypass RLS via SECURITY DEFINER, and routes that touch tenant data without the expected guard.

Variations

  • RPC-heavy app: when the change touches a SECURITY DEFINER function, also call db_rpc on it. Read the function body before editing — RPC behavior is not always obvious from the call site.
  • Generated types (Supabase): after the migration, regenerate types (supabase gen types typescript ...) and re-run db_reef_refresh so Mako knows the new shape.
  • CI guardrail: add git_precommit_check to your pre-commit hook to catch staged route auth and boundary regressions before they land.

Tools used in this recipe

  • db_table_schema — columns, indexes, FKs, RLS, triggers.
  • db_rls — RLS state and policies for one table.
  • db_rpc — function signature, return shape, security, source.
  • schema_usage — find where a schema object is defined and referenced in app code.
  • tenant_leak_audit — multi-tenant RLS posture audit.
  • db_reef_refresh — replace Reef DB facts from the current schema snapshot.
  • db_ping — verify database connectivity.
  • git_precommit_check — staged auth/boundary checks.