> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/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_status` | Database lifecycle state (provisioning / active / failed / paused) and readiness. |
| `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.
```bash theme={null}
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
The full deployed-agent tool surface, including how to enable workspace DB tools per agent.
For semantic search over files and live URLs (vs. structured rows in the DB).
BYOK proxy onto your own Supabase org — distinct from the workspace DB.
Where DB writes are attributed back to a specific agent run.