# PostgreSQL

> Provision and manage PostgreSQL databases on Tarout

# PostgreSQL

PostgreSQL is a powerful, open-source relational database, and it is the database engine Tarout offers today. Every managed database runs PostgreSQL 16.

## Creating a PostgreSQL Database

1. Navigate to **Databases → New Database**.
2. Choose a plan tier.
3. Optionally enter a name and description. If you leave the name blank, Tarout generates one.
4. Click **Create Database**.

There is no version picker, and you do not set credentials: Tarout generates the database name, user, and password.

From the CLI:

```bash
tarout db create my-db
```

## Connection

Copy the connection string from the database detail page. From the CLI, `tarout db info <db> --json` returns it as `externalConnectionString` (the plain `tarout db info` output masks the password). Every value is filled in for you, in this shape:

```bash
postgresql://<user>:<password>@<host>:<port>/<database>?sslmode=require
```

External connections always use TLS, and `sslmode=require` encrypts them. To also verify the server certificate, download the CA certificate from the database page and replace `sslmode=require` with:

```bash
sslmode=verify-full&sslrootcert=/path/to/tarout-postgres-ca.pem
```

## Using with Your Application

When the database is attached to an app on Tarout (for example with `tarout db attach <db> <app-id>`), `DATABASE_URL`, `DIRECT_DATABASE_URL`, `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, and `PGDATABASE` are written into the app's environment for you.

For an app hosted anywhere else, set the connection string you copied as an environment variable:

```bash
DATABASE_URL="<connection string copied from the dashboard>"
```

### Prisma

```prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```

### Node.js (pg)

```javascript
import pg from "pg";
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});
```

## Changing Tiers

Move to another tier from the dashboard, or with the CLI:

```bash
tarout db upgrade <db> --plan standard
tarout db downgrade <db> --plan starter
```

An upgrade that carries a charge opens a checkout page first. Changing tiers copies your data to the new tier. The database stays readable but is read-only while the copy runs, so writes fail until it finishes. A downgrade applies immediately and is not refunded.

## Monitoring

The database page shows the database size, the number of tables with each table's size and row count, active connections, and the cache hit rate. `tarout db analytics <db>` prints the size, connections, and cache hit rate. Per-query metrics are not available.

## Backups

- **Host backups (by Tarout)** - The shared database hosts are backed up daily for disaster recovery. Only Tarout can restore them, and only for a whole host, not for a single database.
- **Your backups (in your storage)** - Schedule backups of this database to your own S3-compatible bucket. Available for databases on paid tiers (Starter, Standard, Pro).

To set up your own backups:

1. Add a destination under **Settings → Backup destinations**.
2. On the database's **Backups** tab, create a schedule: pick the destination, a cron schedule, and optionally how many of the newest files to keep.
3. From the same tab, run a backup on demand or restore from a saved file.

The files land in your own bucket, so you can download them with any S3 tool.

The same flow from the CLI:

```bash
tarout destinations create --name <name> --provider s3 --bucket <bucket> \
  --region <region> --endpoint <https-url> --access-key <key> --secret-key <secret>
tarout destinations list
tarout backups create --postgres-id <db-id> --destination-id <destination-id> \
  --database <database-name> --schedule "0 2 * * *" --keep 7
tarout db backups <db>                               # list this database's schedules
tarout backups run <backup-id>                       # run a backup now
tarout backups files <destination-id>                # list saved files
tarout backups download-url <destination-id> <file>  # signed download link
```

`--database` is the database name shown by `tarout db info <db>`. Restoring a backup is available from the dashboard only.

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md