Databases

Group your workspace tables into databases

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

  1. Open Databases from the workspace sidebar
  2. Click New database
  3. 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 100

Queries 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 SELECT statement of up to 5,000 bytes. DISTINCT and HAVING are 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:

OperationWhat it does
List DatabasesList the workspace's databases with table counts
Create DatabaseCreate a database on the fly
List Tables in DatabaseList the tables inside one database
Query DatabaseRun 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

Common Questions

Every table belongs to a database, but you don't have to think about it: the Default database is created for you, and anything that doesn't specify a database lands there.
Yes, if they're in different databases. Within one database, table names are unique.
Existing table IDs are untouched, and tables created through the public API still land in the fallback database. The list endpoint accepts optional limit and cursor parameters; callers that omit both still receive the complete list.
Yes. Open the database and use the SQL Console at the top of the page. Build the query with the structured controls, edit the SQL directly, or ask the AI to generate one, then click Run. The console is read-only.
Yes, within the same workspace, from the table's context menu. The move fails if the target database already contains a table with the same name.
Anyone whose effective roles grant database:create or database:update for the workspace. Reading and querying are separate permissions, so custom roles can be narrower.
Yes, from its context menu in the dashboard with database:delete permission, or through an explicitly granted workload configuration operation. Active tables block cleanup. Ordinary Chat, user/API-key MCP, scheduled Sub Agents and workflow tools cannot delete databases.
No. Databases are a flat, single level of organization — a database contains tables, never other databases.

On this page