# Bot data tables

> Give a bot real tables, a private SQLite database of its own and a shared database every bot of the same environment can use, with browsing, export and cleanup from the desktop.

Files are not always the right place to keep structured information such as leads, watched prices or items already processed. Each bot can keep **real tables** instead, in two SQLite databases:

- a **private database**, only for that bot. It survives across conversations, background works and routines.
- a **shared database**, used by every bot of the same environment so they can exchange structured data. Bots on this computer share one database; bots on Neoo Cloud share another, on the Neoo Cloud machine. The two never mix.

Data tables work the same way for bots on this computer and bots on Neoo Cloud.

## The bot manages its tables itself

You don't have to create tables. A bot uses six tools:

| Tool | What it does |
| --- | --- |
| `gateway_bot_db_tables`, `gateway_bot_db_query`, `gateway_bot_db_execute` | List the tables, read rows and write to the bot's private database. |
| `gateway_bot_shared_db_tables`, `gateway_bot_shared_db_query`, `gateway_bot_shared_db_execute` | The same, on the shared database. |

Reading accepts `SELECT`, `WITH`, `EXPLAIN` and `PRAGMA table_info`. Writing accepts one statement per call (`CREATE`, `ALTER`, `DROP`, `INSERT`, `UPDATE`, `DELETE`) or an explicit transaction made of several statements, all or nothing. Values are passed as bound parameters, never pasted into the SQL. A write is applied once even if the bot retries it with the same key.

In **Plan** mode a bot can look at its tables but not change them.

### Good practice for shared tables

- Use `CREATE TABLE IF NOT EXISTS`, so bots converge on the same table instead of failing or duplicating it.
- Name tables by domain with a prefix, for example `crm_leads` or `pricing_competitors`, not `data` or `list`.
- Check `gateway_bot_shared_db_tables` first: it shows each table's columns and which bot created it.
- Never store passwords, tokens or personal secrets in a shared table. Use the Neoo Vault.

Every bot can add, change and delete **rows** of any shared table. Only the bot that **created** a table can drop it, alter it, or add an index or trigger to it. When another bot tries, the call fails with `BOT_TABLE_NOT_OWNED` and nothing changes. The creator of each table is recorded automatically.

## Browse and clean tables on the desktop

- **Actions → Data** shows the private tables of the selected bot.
- **Shared data**, at the bottom of the Bots list, opens the shared database. For a bot on Neoo Cloud it shows the database of the Neoo Cloud machine; for a bot on this computer, the database of this computer.

The list shows each table with its number of rows and, for shared tables, the bot that created it. Click a table to see its rows:

| Action | What it does |
| --- | --- |
| Search | Filters the rows that contain your text in any column. |
| Column header | Click to sort ascending, again for descending, a third time to clear. |
| Page arrows | Rows are shown 50 at a time. |
| **CSV** / **JSON** | Saves the whole table (sorted as shown, up to 100,000 rows) to a file. Text cells starting with `=`, `+`, `-` or `@` are prefixed with `'` in the CSV so a spreadsheet doesn't run them as formulas. |
| **Delete rows** | Deletes the selected rows. The first click turns into **Confirm**. |
| **Drop table** | Deletes the whole table. The first click turns into **Confirm**. You can drop any table, whoever created it. |

Changes made by a bot on this computer appear in the list right away. For a bot on Neoo Cloud, press refresh or reopen the table. Opening **Actions → Data** on a bot on Neoo Cloud wakes its machine if needed.

On a Neoo Cloud machine that hasn't been updated yet, the tab says so: the bot has no tables until its machine runs the new Neoo Connect version. A bot hosted by another computer of your account manages its tables on that computer.

## Moving a bot

- **Move to Neoo Cloud** and **Bring home** copy the bot's private database with it, so its tables are there after the move. The shared databases stay where they are: they belong to the environment, not to the bot.
- The private database travels in one encrypted message, so it is copied only if it is **8 MB or smaller**. A larger database stays where it was and the bot arrives with no tables. If the copy fails, the bot is still moved and keeps its old database on the source side.
- Moving a bot to **another computer** does not copy its tables yet.
- Exporting a bot to a file or duplicating it does not copy its tables.

## Privacy

Everything stays on the machine that hosts the bot: this computer, or the Neoo Cloud machine. Neoo's servers only relay your actions end to end encrypted and never see the rows. Deleting a bot permanently deletes its private database.

## Limits

- Private database: up to 512 MB per bot (half of the 1 GB each bot has for files). Shared database: up to 512 MB per environment. When it is full, writes fail with `BOT_DB_QUOTA_EXCEEDED`.
- A read returns at most 500 rows. Text values longer than 1,000 characters are shortened in the bot's results (the desktop view shows them in full up to 20,000 characters). A read is stopped after 5 seconds on this computer.
- An `ATTACH`, `DETACH`, `VACUUM`, `load_extension`, manual `BEGIN`/`COMMIT` or any `PRAGMA` other than reading a table's structure is refused.
- Up to 50 statements per transaction and 500 bound parameters per statement.
- On Neoo Cloud a `WITH RECURSIVE` query must contain a `LIMIT`, because that machine cannot interrupt a runaway query.
- The tables of a bot are not searchable from its memory and are not visible in the mobile app or on vatoide.com yet.

Source: https://vatoide.com/docs/bots/data