# Database

List, create, and query workspace databases

Databases group the tables in your workspace. Every table belongs to exactly one database, and table names are unique within their database. The Database block lets workflows discover databases and their tables, create databases on the fly, and run read-only queries with a SQL-like syntax.

**Why Use the Database Block?**

* **Organize tables**: Group related tables together (e.g., a CRM database holding `leads`, `accounts`, and `contacts`)
* **Discover from workflows**: List databases and tables without hardcoding IDs
* **Query without filter objects**: Run read-only `SELECT` queries instead of building MongoDB-style filters

**The Default database**: every workspace has a fallback database — its oldest active one, named `Default` unless renamed. Tables created before databases existed were moved into it, and API or tool calls that omit a database target it.

For creating and managing databases from the UI, see the [Databases guide](/tables/databases). For row-level reads and writes, use the [Table block](/tools/table).

## Query Syntax

The **Query Database** operation accepts a single read-only statement:

```sql
SELECT * FROM table_name
  [WHERE condition [AND condition ...]]
  [ORDER BY column [asc|desc]]
  [LIMIT n] [OFFSET n]
```

| Element              | Supported                                                          |
| -------------------- | ------------------------------------------------------------------ |
| Projection           | `SELECT *` only — no column lists                                  |
| Tables               | One table per query — no joins                                     |
| `WHERE` operators    | `=`, `!=`, `<>`, `>`, `>=`, `<`, `<=`, `LIKE`, `ILIKE`, `CONTAINS` |
| Combining conditions | `AND` only — no `OR`                                               |
| `ORDER BY`           | A single column, `asc` or `desc`                                   |
| Literals             | Single- or double-quoted strings, numbers, `true`, `false`, `null` |

Examples:

```sql
SELECT * FROM leads WHERE status = "active" LIMIT 100
```

```sql
SELECT * FROM orders WHERE total >= 100 ORDER BY created_at DESC LIMIT 50
```

Queries are strictly read-only — invalid or unsupported syntax returns a parse error. Use the [Table block](/tools/table) to insert, update, or delete rows.

## Notes

* Up to 50 databases per workspace; database names are limited to 50 characters
* Viewing and querying require `database:read` and `database:query`; creating a database requires `database:create`
* `table_list` lists active tables by default; set **Table Status** to Archived or All to include tables that were deleted (archived) and can still be restored
* `table_query_database` is read-only — use the [Table block](/tools/table) for inserts, updates, upserts, and deletes
* Renaming and deleting databases is done from the [Databases UI](/tables/databases), not from this block

## Usage Instructions

Work with workspace databases as table containers. List databases, create databases, list tables inside a database, or run read-only database queries.

## Tools

### `table_list_databases`

List table databases in the workspace with table counts

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |

#### Output

| Parameter    | Type    | Description                 |
| ------------ | ------- | --------------------------- |
| `success`    | boolean | Whether operation succeeded |
| `databases`  | array   | List of databases           |
| `totalCount` | number  | Total number of databases   |

### `table_create_database`

Create a database for grouping workspace tables

#### Input

| Parameter     | Type   | Required | Description                     |
| ------------- | ------ | -------- | ------------------------------- |
| `name`        | string | Yes      | Database name                   |
| `description` | string | No       | Optional database description   |
| `color`       | string | No       | Optional hex color like #6B7280 |

#### Output

| Parameter  | Type    | Description                  |
| ---------- | ------- | ---------------------------- |
| `success`  | boolean | Whether database was created |
| `database` | json    | Created database metadata    |
| `message`  | string  | Status message               |

### `table_list`

List all tables in the workspace, optionally filtered to a single database

#### Input

| Parameter    | Type   | Required | Description                                                      |
| ------------ | ------ | -------- | ---------------------------------------------------------------- |
| `databaseId` | string | No       | Database ID to list tables from. When omitted, lists all tables. |
| `scope`      | string | No       | Which tables to list: 'active' (default), 'archived', or 'all'.  |

#### Output

| Parameter    | Type    | Description                 |
| ------------ | ------- | --------------------------- |
| `success`    | boolean | Whether operation succeeded |
| `tables`     | array   | List of tables              |
| `totalCount` | number  | Total number of tables      |

### `table_query_database`

Run a read-only SELECT \* query against one table in a database

#### Input

| Parameter    | Type   | Required | Description                                                                                |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `databaseId` | string | Yes      | Database ID                                                                                |
| `query`      | string | Yes      | Read-only query, for example: SELECT \* FROM table\_name WHERE status = "active" LIMIT 100 |

#### Output

| Parameter    | Type    | Description                |
| ------------ | ------- | -------------------------- |
| `success`    | boolean | Whether query succeeded    |
| `table`      | json    | Queried table metadata     |
| `rows`       | array   | Query result rows          |
| `rowCount`   | number  | Number of rows returned    |
| `totalCount` | number  | Total rows matching filter |
| `limit`      | number  | Limit used in query        |
| `offset`     | number  | Offset used in query       |
