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

# Database

> Keep records such as orders, leads and tickets in a small database that belongs to your agent, with tables, a rows grid, SQL and CSV import.

A Database store is a small database that belongs to one agent. Use it for records: customers, orders, bookings, tickets. Workflows, conversation flows and coworkers of the agent add, find and change rows, and you can look at the same rows yourself on the store's page.

Add one with **Add → Database** under an agent, and give it a name such as "CRM" or "Orders".

> [!NOTE]
>
> Databases are available where the database service runs for your workspace. If **Database** isn't in the **Add** menu, it isn't switched on for you yet.

## Tables

The store opens on its **Tables** list, with each table's row count. Click **Add a table** to make one, then use the designer to set its columns.

| Column option | What it does |
| - | - |
| **Name** | The column's name |
| **Type** | Text, Integer, Real number, Boolean, Date, Date & time or JSON. Each keeps a SQLite type, shown under the column: Real number is SQLite REAL, a floating-point number, not an exact decimal; Boolean is kept as 0 or 1; Date, Date & time and JSON are kept as text |
| **Required** | A row can't be saved without a value |
| **Unique** | No two rows may hold the same value |
| **Default** | The value used when a row doesn't give one |

Every table also gets an `id` (a number made for you), `created_at` and `updated_at`. You can't change those. Add an index on the columns you search by, so lookups stay quick.

Adding, renaming or removing a column, or renaming or removing a table, asks you to confirm and shows what uses it.

## Rows

Open a table to see its rows in a grid. You can:

* **Filter and sort** by a column
* **Edit** a cell in place
* **Add** and **delete** rows
* **Page** through long tables. The grid loads a page at a time

## Import and export CSV

**Import CSV** adds the rows of a file to a table. Files can be up to 10 MiB. **Export CSV** downloads the table's rows. A cell that starts with `=`, `+`, `-` or `@` is exported with a leading quote, so a spreadsheet doesn't run it as a formula.

## SQL console

The **SQL console** runs one SQL statement and shows the result as a grid. It starts in read-only mode. Switch to write mode to change data, and every write asks you to confirm first.

```sql theme={null}
SELECT status, COUNT(*) AS orders
FROM orders
GROUP BY status;
```

Good to know:

* One statement at a time.
* Results are cut off after a limit, and the grid says so.
* A query that runs too long is stopped.
* Attaching other databases, loading extensions and changing the database's settings are refused.
* Schema changes and writes are recorded in the agent's audit log.

## In each environment

When the agent has more than one [environment](https://docs.cogniagent.ai/features/environments.md), such as Production and Demo, a Database is one of two kinds:

* **Separate in each environment**: each environment has its own rows. Work in Demo never reads or writes Production's rows. Every new Database is separate.
* **The same in every environment**: one set of rows that every environment reads and changes.

Either way, the **tables are the same in every environment**, so a step that names a column finds it wherever the agent runs.

Workflows, conversation flows, coworkers, the [API](https://docs.cogniagent.ai/api/stores.md#environments) and AI assistants use the rows of the environment the agent runs in. A Database another agent shares with yours always reaches that agent's Production rows.

### The store's page

A separate Database's page has a pill for each environment at the top, with its size. It opens on Production and marks the one the agent runs in. The line under the pills says whose rows you see: "Showing Demo's rows. The agent runs in Production. Tables are the same in every environment." The rows, the SQL console, **Import CSV**, **Export CSV** and the size act on the environment you picked.

A Database that is the same in every environment says **The same in every environment** instead: "Every environment reads and changes these rows."

When you add an environment, you pick for each separate Database whether it starts with the tables and no rows, or a copy of another environment's rows. See [Add an environment](https://docs.cogniagent.ai/features/environments.md#add-an-environment). While Demo's rows are being copied, could not be copied, or are not set up, the page says so in place of the tables, with **Retry** or **Set up**. Until they are ready, the agent can't switch to Demo, and work in Demo that uses the Database is refused: "Leads has no rows in Demo yet."

### One set of tables

The table designer says **Changes apply to every environment**: "Each environment has its own rows, and the tables are the same in all of them. A change is tried on every environment's rows first; if any would refuse it, nothing changes."

* **A change that any environment's rows refuse is refused for all.** A unique column over duplicate emails in Demo, for example: "Demo's rows refuse this change, so no environment changed: UNIQUE constraint failed: leads.email."
* **A change that deletes data asks first**, and lists what each environment loses: "It applies to every environment. Each one loses:"
* **A change waits for a copy.** While Demo's rows are still being copied, the tables can't change: "Demo's rows in Leads are still being copied. Change the tables once they are ready."

### Not up to date

A change reaches Production first, then each other environment. One that has not taken it yet shows **Behind** on its pill, and its page says "Demo's tables are not up to date": "A change to the tables has not reached Demo yet. It catches up by itself, and Start and a switch to Demo wait for it." Click **Retry** to catch it up now. If something stops it, the page says what to fix first, such as "The workspace's storage is full. Free up space, then Retry."

A switch to Demo, and **Start** while the agent runs in Demo, first try to catch the tables up. While they are still behind, both are refused: "Leads: Demo's tables are not up to date. Retry on the Leads page."

### Reset from Production

When Demo's tables no longer match Production's, its pill says **Tables differ**, and its page says "Demo's tables differ from Production's". Reset them from Production with one of two buttons:

* **Copy Production's rows**: Demo gets a copy of Production's tables and rows.
* **Tables only**: Demo gets Production's tables with no rows.

The confirm, "Reset Demo's tables from Production?", says what goes: Demo's own rows go to the Trash with its database, where they stay 30 days. When **Retry** keeps failing for tables that are behind, the page offers the same reset as a second way out.

### Change it

Click **Rows per environment**, beside the pills or the shared line. It works as for a [File Store](https://docs.cogniagent.ai/features/file-stores.md#change-it), only while the agent is stopped or runs in Production:

* **To separate** (**Give each environment its own rows**): Production keeps its rows. Each other environment starts with **Tables only** or a **Copy of Production**.
* **To the same** (**Use one set of rows**): Production keeps its rows. Each other environment's own rows go to the Trash. The dialog lists them first, such as "Demo: 3 tables, 120 rows, 1 MB".

## Use it in your agent

> [card] [Workflows](https://docs.cogniagent.ai/nodes/actions/database.md)
>
> The Database step inserts, gets, finds, updates and deletes rows, or runs SQL.

> [card] [Conversation flows](https://docs.cogniagent.ai/conversation-flows/build/capabilities.md#data-stores)
>
> An actor gets **Data stores**, read or read & write.

> [card] [Coworkers](https://docs.cogniagent.ai/cowork/capabilities/data-stores.md)
>
> Tools to list tables, query rows and, after asking you, change them.

> [card] [Your own app](https://docs.cogniagent.ai/api/stores.md)
>
> Expose the database to read or change its rows over the API or MCP.

## Size and backups

A database holds a modest amount of data, and a cap applies to each database and to your workspace's total storage. It is made for the records of one agent, not for a data warehouse. Each environment's rows count toward that storage, and a copy that would take the workspace above 80% of its limit is refused.

Deleting a Database moves it to a trash, in every environment, and it is erased after 30 days.

## Sharing and installing

When someone installs a shared agent, the Database is copied with its tables, and with **Include contents** its rows, from the environment you share from. The copy has only Production, and those rows become its Production rows. See [Include contents](https://docs.cogniagent.ai/features/sharing-agents.md#include-contents). If the database service is unavailable at that moment, the install finishes anyway, and **Finish installation** lists the database as not set up, with a **Retry setup** button. See [Sharing agents](https://docs.cogniagent.ai/features/sharing-agents.md#finish-installation).

## Common questions

> [accordion] Can another agent use my database?
>
> Yes, when you share it. Open its **Manage access** and turn on **Other agents**, at **Read** or **Read & write**: their items then pick it under **Shared by other agents**, with no key. They always reach your Production rows, and can change them only while they run in Production. Your app or an AI assistant uses an endpoint key. See [Use a store another agent shares](https://docs.cogniagent.ai/features/data-stores.md#use-a-store-another-agent-shares) and [Agent data API](https://docs.cogniagent.ai/api/stores.md).

> [accordion] Can the API change my tables?
>
> No. Outside callers read and change rows, but tables and columns change only on the store's page.

> [accordion] Should I use SQL or the Database step?
>
> Use the step's insert, get, find, update and delete for everyday work. Use SQL for a join, a total or a one-off fix. Values always go in as parameters, never pasted into the statement.

## Next steps

> [card] [Database step](https://docs.cogniagent.ai/nodes/actions/database.md)
>
> Every operation, with examples.

> [card] [Data stores](https://docs.cogniagent.ai/features/data-stores.md)
>
> Variable groups and File Stores too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.