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

# Store bot data with Paige's built-in project database

> Every Paige project includes a dedicated Postgres database. Create tables, manage data, and read or write from your bot code — all without external setup.

Every Paige project comes with a dedicated Postgres database provisioned automatically at project creation. There is nothing to configure — your bot code connects to it through the built-in `dbServices.js` service, and you can view and manage the data directly from the Paige dashboard. The database is isolated per project, so tables and data in one project are never accessible to another.

## What the database is used for

Your bot can store and retrieve any data it needs during conversations. Common use cases include:

<CardGroup cols={2}>
  <Card title="Contact profiles" icon="user">
    Store names, preferences, and other details collected from contacts during conversations.
  </Card>

  <Card title="Conversation state" icon="message-circle">
    The system tables `contacts`, `conversations`, and `messages` are maintained automatically to power the conversations dashboard.
  </Card>

  <Card title="Booking and order data" icon="calendar-check">
    Persist appointment bookings, order details, or service requests submitted via Flows or conversational intake.
  </Card>

  <Card title="Bot configuration" icon="settings">
    Store dynamic settings like business hours, menu options, or pricing that your bot reads at runtime.
  </Card>
</CardGroup>

## System tables

Paige automatically creates and maintains three system tables in every project database:

| Table           | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `contacts`      | One row per unique phone number that has messaged the bot               |
| `conversations` | One row per conversation, linked to a contact; stores the current state |
| `messages`      | Every inbound and outbound message, linked to a conversation            |

<Warning>
  You cannot drop or modify the system tables (`contacts`, `conversations`, `messages`). They are managed by Paige and power the conversations dashboard.
</Warning>

## Creating and managing tables

You can create custom tables from the **Database** section of the dashboard or by asking the AI agent.

### From the dashboard

The dashboard lets you:

* View all tables and browse their data
* Create a new table with custom columns
* Add columns to an existing table
* Insert, edit, and delete rows
* Clear all rows from a table
* Drop a custom table

### Via the Code Agent

The [Code Agent](/agents/code-agent) has full access to your database schema and can create and modify tables as part of building your bot. When you describe a feature that requires data storage, the agent will create the necessary tables before writing the bot code that references them.

You can ask it to create tables, add columns, query rows, or seed test data — all in plain language, without leaving the chat.

## Supported column types

When creating tables, you can use the following column types:

`text`, `varchar`, `integer`, `bigint`, `numeric`, `boolean`, `date`, `timestamptz`, `uuid`, `jsonb`, `serial`

<Tip>
  Use `jsonb` for flexible, semi-structured data — for example, storing a contact's form submission as a single column rather than normalising every field into its own column.
</Tip>

## Reading and writing from bot code

Your bot code connects to the project database automatically — no connection string or configuration required. The starter template includes a database service with pre-built helper functions for common operations (looking up contacts, recording conversations, inserting rows), and you can also write direct queries when you need more control.

Ask the AI agent to write the database access code for you. For example:

> "When a user submits the booking flow, save the booking to a `bookings` table with their name, service, date, and phone number."

The agent will create the table if it doesn't exist and write the code to insert the row.

<Note>
  Your bot code always connects to the same database visible in the dashboard. Any rows inserted by the bot appear immediately in the data browser, and any changes you make in the dashboard are visible to the bot on the next query.
</Note>