# Databases

Group your workspace tables into databases

Databases group the [tables](/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](/self-hosting/entra-workload-identities#logical-database-and-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](/api-reference/\(generated\)/tables), 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:

```sql
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](/tools/database) for the full operator table. Queries never modify data; writes go through the [Table block](/tools/table).

## 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 **JOIN**s, **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](/chat#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](/tools/table). See the [Database block reference](/tools/database) 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](/tables#limits)

## Common Questions

**Do I have to use databases?**

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.

**Can two tables have the same name?**

Yes, if they're in different databases. Within one database, table names are unique.

**Did my existing API integrations break?**

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.

**Can I query a database without building a workflow?**

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.

**Can I move a table between databases?**

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.

**Who can create or rename databases?**

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.

**Can I delete an empty database?**

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.

**Can databases be nested?**

No. Databases are a flat, single level of organization — a database contains tables, never other databases.
