> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rerun.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Databases

> Read and write the private database of an agent and the database shared by a Box.

Each agent has one private SQLite database that no other agent can read. Each Box has a second database that every agent in it reads and writes. These tools reach both, so you can lay out the tables an agent works from before it ever runs.

It is plain SQLite. Column types are `TEXT`, `INTEGER`, `REAL`, `BLOB` or `NUMERIC`.

## Agent database

### list\_tables

Structure of the agent private database: every table with its columns, types, primary keys and not-null flags.

<ParamField body="agentId" type="string" required />

### db\_query

Runs a read-only `SELECT` and returns the rows. Anything that writes is refused here.

<ParamField body="agentId" type="string" required />

<ParamField body="sql" type="string" required>
  A single `SELECT`, or `WITH … SELECT`.
</ParamField>

<ParamField body="params" type="array">
  Values bound to the `?` placeholders, in order.
</ParamField>

<ParamField body="limit" type="number">
  Maximum rows returned. Default `100`, maximum `1000`.
</ParamField>

```json Request arguments theme={"system"}
{
  "agentId": "…",
  "sql": "SELECT email, created_at FROM leads WHERE status = ? ORDER BY created_at DESC",
  "params": ["new"],
  "limit": 50
}
```

Use `?` placeholders with `params` rather than pasting values into the SQL.

### db\_execute

Changes the agent private database: `CREATE`, `ALTER`, `DROP` a table, or `INSERT`, `UPDATE`, `DELETE` rows.

<ParamField body="agentId" type="string" required />

<ParamField body="sql" type="string">
  A single statement.
</ParamField>

<ParamField body="params" type="array">
  Values bound to the `?` placeholders in `sql`, in order.
</ParamField>

<ParamField body="statements" type="object[]">
  Several statements applied atomically in one transaction. Each entry needs `sql` and may carry `params`. This is the right way to lay out a whole schema.
</ParamField>

Pass either `sql` or `statements`. The call fails if you pass neither.

```json Request arguments theme={"system"}
{
  "agentId": "…",
  "statements": [
    { "sql": "CREATE TABLE IF NOT EXISTS leads (id INTEGER PRIMARY KEY, email TEXT NOT NULL, status TEXT)" },
    { "sql": "CREATE INDEX IF NOT EXISTS leads_status ON leads (status)" }
  ]
}
```

## Box database

The same three operations, on the database every agent of one Box shares. Get the `spaceId` from [`list_spaces`](/api/tools/agents#list-spaces).

### list\_space\_tables

<ParamField body="spaceId" type="string" required />

### space\_db\_query

<ParamField body="spaceId" type="string" required />

<ParamField body="sql" type="string" required />

<ParamField body="params" type="array" />

<ParamField body="limit" type="number">
  Default `100`, maximum `1000`.
</ParamField>

### space\_db\_execute

<ParamField body="spaceId" type="string" required />

<ParamField body="sql" type="string" />

<ParamField body="params" type="array" />

<ParamField body="statements" type="object[]" />

<Warning>
  Every agent in the Box sees the result immediately. Prefer `CREATE TABLE IF NOT EXISTS`, extend with `ALTER TABLE ADD COLUMN`, and do not drop a table the agents already fill.
</Warning>