Workspace database

A Supabase-style database that ships with every workspace and is callable as agent tools.

Every agntdata workspace gets its own database — a dedicated Supabase project provisioned the first time you ask for it. Your agents can read and write to it through MCP tools, your code can hit it via a REST surface, and the dashboard’s Database tab gives you a Supabase-Studio-style table browser + SQL editor.

This is the durable state layer for your agents. Use it for the things you want to outlive a single session: enriched leads, processed emails, ticket states, cached lookups, anything you’d otherwise jam into a spreadsheet.

Workspace databases are not the same as the Supabase connection under Connections → Supabase. That connection is a BYOK proxy onto your own Supabase organization’s management API. The workspace database is provisioned and managed by agntdata, billed against your plan’s database allowance, and isolated per workspace.

What the agent sees

When workspace_db.enabled is set on a deployed agent’s config, the MCP gateway emits a family of agnt_db_* tools that the agent can call:

Tool	Purpose
agnt_db_list_tables	Catalog of tables with row counts and column types.
agnt_db_list_extensions	Installed Postgres extensions (pgvector, pg_trgm, etc.).
agnt_db_list_migrations	History of named migrations applied to the workspace DB.
agnt_db_select	Filtered read with predicates and column projection.
agnt_db_execute_sql	Arbitrary read SQL (SELECT, EXPLAIN).
agnt_db_insert	Append rows with type coercion.
agnt_db_upsert	Upsert by conflict target.
agnt_db_update	Update by predicate.
agnt_db_delete	Delete by predicate.
agnt_db_load_csv	Stream a CSV into a table — type inference, dedup, batched upsert.
agnt_db_apply_migration	Named DDL (CREATE TABLE, ALTER, index creation).

The agent’s tool list is gated by the agent’s config:

• read_only: true strips the write and DDL tools.
• allow_apply_migration: false strips agnt_db_apply_migration.

Migrations applied via agnt_db_apply_migration are appended to a migrations table inside the workspace DB itself, so the agent can audit what’s been done and avoid replaying the same DDL twice.

Calling the database from your code

The same operations are exposed at REST under /v1/db/* and authenticated with a regular workspace API key. They’re the right choice when you want to hit the workspace DB from your own backend — agents inside agntdata should use the MCP tools instead so per-agent workspace_db policies, allowlists, and audit attribution stay in force.

curl -X POST "https://api.agntdata.dev/v1/db/select" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"table":"leads","where":{"status":"qualified"},"limit":50}'

The Database tab

The dashboard’s Database page is a thin wrapper around the workspace DB:

• Tables — browse rows, filter, sort, and export to CSV or JSON.
• SQL editor — run ad-hoc SELECT queries with syntax highlighting and result-set paging.
• Schema — see columns, types, and indexes at a glance.

Provisioning happens on demand: open the page in a new workspace and you’ll see a provisioning state while we spin up the underlying Supabase project. It usually takes 30–90 seconds. The dashboard polls status from workspace_databases_public (the safe projection — no encrypted secrets) until it flips to active.

How provisioning works

A workspace’s database is a dedicated Supabase project inside agntdata’s Supabase organization. The encrypted connection material (DB password, service-role key) lives in workspace_databases, gated by RLS — the dashboard only ever reads the safe workspace_databases_public view, so credentials never leave the server.

Limits depend on your plan:

Plan	Workspace databases
Build	1
Launch	3
Scale	20

When you hit the limit, the database tab in additional workspaces shows an upgrade nudge instead of provisioning a new project.

Security model

• Workspace isolation — each workspace is its own Supabase project. There is no shared schema and no cross-workspace queries.
• Service-role-only writes from the API server. The workspace_databases row’s encrypted columns are decrypted only inside the agntdata API, never sent to clients.
• Per-agent allowlists. A deployed agent’s workspace_db.allowed_tables config (if set) restricts which tables the agent’s tools can touch — useful when you want one agent to write to leads but never read your audit_log.
• DDL audit trail. Every agnt_db_apply_migration call writes to agnt_db_audit with the agent id, the SQL text, and the result.

Next steps

Tools & MCP gateway

The full deployed-agent tool surface, including how to enable workspace DB tools per agent.

Knowledge base

For text-search RAG over files and URLs (vs. structured rows in the DB).

Supabase connection

BYOK proxy onto your own Supabase org — distinct from the workspace DB.

Sessions

Where DB writes are attributed back to a specific agent run.