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

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 app-code sites that read the table

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

Returns exact definition sites and direct app-code references such as Supabase .from("organizations") calls and raw SQL strings. For RPC-mediated or transitive paths, follow with trace_rpc, route_context, or flow_map.

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, Reef-backed schema and usage tools can keep serving stale facts. With a live database binding, make sure the schema snapshot itself is live-fresh before treating the result as proof of production database state.

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 exact schema-object definitions and direct app-code references.
tenant_leak_audit — multi-tenant RLS posture audit.
db_reef_refresh — persist DB schema facts from the current schema snapshot into Reef.
db_ping — verify database connectivity.
git_precommit_check — staged auth/boundary checks.