Databases group the tables in your workspace. Every table belongs to exactly one database, and table names are unique within their database — so two databases in the same workspace can each have their own leads table.
Open Databases in the workspace sidebar to see them. Each database lists its tables, and you can create, rename, and delete empty databases from the same view.
If you used tables before databases existed: your tables were moved into a database named Default, the sidebar entry changed from "Tables" to "Databases", and old table links redirect to the new pages. Your tables' data, schemas, and workflow references are unchanged.
Creating a Database
- Open Databases from the workspace sidebar
- Click New database
- Name it (up to 50 characters), optionally adding a description and color
Database access follows catalog permissions. Reading and querying use database:read and database:query; creating and renaming use database:create and database:update. The seeded Editor and Workspace Admin roles include the mutation permissions by default, and custom roles can grant them separately.
Deleting a Database
Open the database's context menu and choose Delete. You need database:delete, and the database must contain no tables. When tables remain, Delete is disabled and its tooltip explains that all tables must be deleted first. The server checks the condition again before deletion.
Database deletion is available through the signed-in dashboard. Chat, user/API-key MCP, scheduled Sub Agents and workflow tools cannot delete databases, including empty ones. An explicitly authorized workload identity can archive an empty logical database through the separate configuration contract with database:delete, an exact ID/revision, retry key and confirmation; see workload database/table configuration. Table and row deletion use their own permissions.
The Default Database
Every workspace has a fallback database — its oldest active one, named Default unless you've renamed it. Anything created without an explicit database lands there:
- Tables created through the public API, which doesn't take a database parameter
- Tables created by workflow tools or assistants that don't specify a database
"Default" is just a name: you can rename the database freely, and the fallback continues to target the workspace's oldest active database.
Listing Tables Through the API
GET /api/v1/tables?workspaceId=... lists tables across the workspace's databases. Omit both limit and cursor to receive the full list. To request pages, set limit from 1 to 100 and pass the response's top-level nextCursor unchanged as cursor on the next request. A cursor without an explicit limit uses a page size of 50. nextCursor: null marks the end, and data.totalCount is the count across the complete list. Invalid limits or cursors return 400.
Listing requires workspace table-read permission. Creating through the public API requires table-create permission and places the new table in the fallback database. API-key workspace and organization restrictions still apply.
Tables in a Database
- Open a database and click New table to create a table inside it
- Table names must be unique within their database, not across the workspace
- Move a table to another database in the same workspace from the table's context menu — the move fails if the target database already has a table with that name
Querying a Database
You can run read-only queries against a database's tables from workflows using a SQL-like syntax:
SELECT * FROM leads WHERE status = "active" ORDER BY created_at DESC LIMIT 100Queries support WHERE conditions combined with AND, plus ORDER BY, LIMIT, and OFFSET — see the Database block reference for the full operator table. Queries never modify data; writes go through the Table block.
SQL Console
Each database page opens with a SQL Console for exploring its tables. It is separate from the Database block's query operation and supports a larger subset of SQL. You can write a query in three ways:
- Query controls: build the statement step by step. Pick the FROM table, then add SELECT fields or aggregates, WHERE filters, up to 3 JOINs, ORDER BY, and LIMIT. The generated SQL appears in the editor as you go.
- SQL editor: edit the SQL directly. The console accepts one plain
SELECTstatement of up to 5,000 bytes.DISTINCTandHAVINGare not supported. - Ask AI for a query: describe what you want in plain language. The console generates a query that you can apply and run.
Select Run to execute the query. The console returns at most 1,000 rows (100 by default) and cancels any statement that runs longer than 5 seconds. It is read-only and requires database:query on the database.
Ask AI for a query uses the workspace's available Chat models. If the requested model loses its provider key or is blocked by the deployment, generation resolves to the default Chat model. Provider, organization access, and reasoning-effort checks still apply. See Model and Reasoning Effort.
Using Databases in Workflows
The Database block gives workflows four operations:
| Operation | What it does |
|---|---|
| List Databases | List the workspace's databases with table counts |
| Create Database | Create a database on the fly |
| List Tables in Database | List the tables inside one database |
| Query Database | Run a read-only query against a table |
Row-level reads and writes (insert, update, upsert, delete) stay on the Table block. See the Database block reference for inputs and outputs.
Limits
- 50 databases per workspace
- Database names up to 50 characters, descriptions up to 500
- Table counts and row caps are unchanged and remain per workspace — see Tables limits