# PostgreSQL recipe

URL: https://briq.cloud/cookbook/postgres

> A PostgreSQL database with a persistent volume. Optional pgvector.

Tags: database, sql

Guides:

- [Give Claude Code a database](https://briq.cloud/docs/guides/give-claude-code-a-database.md): Let the agent run migrations, seed data and test queries against a real Postgres.
- [Run tests against real services](https://briq.cloud/docs/guides/run-tests-against-real-services.md): Replace mocks with a real Postgres and Redis for the duration of a test run.
- [Connect to a database from outside](https://briq.cloud/docs/guides/connect-to-a-database-from-outside.md): A briq's database reachable from psql, a BI tool or an app elsewhere, over TLS, with a normal connection string.

## Run it

MCP:

```ts
briq_run({
  recipe: "postgres",
  params: {
    "version": "16",
    "extensions": [],
    "size": "small",
    "diskGb": 2
  },
  wait: true
})
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "postgres",
    "params": {
      "version": "16",
      "extensions": [],
      "size": "small",
      "diskGb": 2
    },
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "DATABASE_URL": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

## Parameters

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `version` | enum | 15, 16, 17 | "16" | — |
| `extensions` | enum[] | pgvector | [] | — |
| `size` | enum | nano, small, medium, large | "small" | — |
| `diskGb` | number | — | 2 | Volume size, in GB |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `DATABASE_URL` | `postgres://postgres:<POSTGRES_PASSWORD>@db.<stack>.internal:5432/app` |
| `PGHOST` | `db.<stack>.internal` |
| `PGPORT` | `5432` |
| `PGUSER` | `postgres` |
| `PGPASSWORD` | `<POSTGRES_PASSWORD>` |
| `PGDATABASE` | `app` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| db | `postgres:16` | 5432 | small | 2 GB at /var/lib/postgresql/data |

## When to use it

* Migrations, seeds or an ORM schema need a real database to be checked against.
* An integration suite expects `DATABASE_URL` and you want neither mocks nor Docker.
* Vector search: `extensions: ["pgvector"]` switches to the `pgvector/pgvector` image.

## Tips

* **Run SQL inside the briq.** `DATABASE_URL` is private: `briq_files_put` a file, then
  `briq_exec` with `psql -U postgres -d app -v ON_ERROR_STOP=1 -f /file.sql`.
* **`nano`** is enough for schema checks and small fixtures.
* **Data survives stops**, so keep the briq while iterating and destroy it at the end.
* **From another briq**, use `DATABASE_URL` as is.
* **Connect from outside**: `briq_expose` port 5432 with `protocol: "postgres"` gives a connection
  string over TLS, for psql or a BI tool. See [Connect to a database from outside](https://briq.cloud/docs/guides/connect-to-a-database-from-outside).
* **No TLS inside the stack**: the connection stays on the stack's private network. An app set up
  to require SSL (`sslmode=require`, or settings written for a hosting platform, such as
  `ssl_require=True` in Django) refuses to connect: turn that requirement off in the app's settings.
* **Need a bigger database?** The volume starts small: pass `diskGb`, e.g. `params: { diskGb: 20 }`.
  Set it when the briq is created, and it counts toward your [plan's disk](https://briq.cloud/docs/cost#plans).