# Databases

**Available in:** Project development and Site production, through supported database configuration. Each environment has its own data and authorization. Chats and Agents do not acquire an application database through their working File system.

A database holds structured application records such as customers, orders, or workflow state. Your application owns its schema, validation, migrations, and business permissions. Playbooks provides the governed resource and connection workflow where supported.

## Set up a development database

As a Project admin, open **Database** and choose **Add database**. Choose **Managed database** to provision Postgres. For an existing database, select its provider under **Or connect your own** and follow the connection prompts. Wait for the database to be ready before connecting the form.

For managed Postgres with TLS, configure the backend driver to trust the runtime’s `POSTGRES_CA_CERT` and verify the server certificate. For example, with Node’s `pg` driver:

```js
import { Pool } from "pg";

const env = process.env;
const pool = new Pool({
  host: env.POSTGRES_HOST,
  port: Number(env.POSTGRES_PORT),
  database: env.POSTGRES_DB,
  user: env.POSTGRES_USER,
  password: env.POSTGRES_PASSWORD,
  ssl: { ca: env.POSTGRES_CA_CERT, rejectUnauthorized: true },
});
```

Ask the Project to create a requests table with a title and status and connect an intake form to it. Open the web app in the Project’s **Browser** view and submit “Replace lobby sign”. Return to **Database**, open the requests table, and check that the saved row contains that title.

## Separate development and production

Use Project development data while building and testing. A Site's production database belongs to its production scope. Releasing code does not copy development records, select a production provider, or transfer credentials implicitly.

1. Confirm the Project or Site you are configuring.
2. Select the supported database resource or authorized provider.
3. Configure access through the trusted server-side environment.
4. Apply deliberate schema changes and verify a representative read and write.
5. Check application permissions as well as connection success.

## Plan schema changes

| Change | Review before applying |
| --- | --- |
| Add a field | Defaults and compatibility with current code |
| Change permissions | Which application users should read or write each record |
| Release new code | Compatibility with the existing production schema |
| Remove data | Review retained records and recovery before deletion |
| Rename a field | Update readers and writers that use its old name |

A successful database connection does not establish correct application authorization. Test that one user cannot read or modify another user's records where the application requires that separation.

## Recover deliberately

A code rollback does not reverse a database migration. Before a consequential data change, identify the affected records and the available recovery mechanism. Do not use production data as disposable development material.

Database capacity and operations follow applicable usage rules. Review [Usage](/docs/billing/usage), and use [Storage](/docs/services/storage) for objects that are better stored as files rather than relational records.

## Example: store customer requests

An intake application might store a request title, status, creator, and creation time. Define which users may read and update each record, then validate those rules on the server as well as in the interface.

Before releasing a new required field, consider existing records and running code. Use [Project development](/docs/projects/development) to verify the change and [Site releases](/docs/sites/releases) to plan production compatibility.

## Describe the requirement in a Project

> Store each request with a title, status, creator, and creation time. Only authorized reviewers may change status. Explain how existing records will behave when the schema changes.

Use the [Composer](/docs/composer/prompts) to state the application behavior, then inspect reads, writes, and denied actions in the working preview. Keep real production records out of disposable examples.