# Postgres

> Managed Postgres instances per environment — connection links, psql, credentials, backups, plans

URL: https://pier.run/docs/resources/postgres

```yaml title="pier.yaml"
environments:
  prod:
    postgres:
      - name: main
        targets:
          - name: primary
            version: "17"
            plan: pg-s
            bootstrap_default_database: app
            replicas: 1
```

```bash
pier ls pg
```

```text title="output"
                                   
 NAME VERSION PLAN STATUS  UPDATED 
                                   
 main 17      pg-s running 1m ago  
                                   

```

A Postgres resource is one instance per environment, provisioned with a version, a
[plan](/docs/plans) and a default database. Apps in the same environment reach it
through a [link](/docs/vars) (`from: postgres.main.url`); `pier psql` or a credential for
any client reaches it from outside. Storage grows with the data and is not a configuration
key.

## Configuration

| Key                                    | Meaning                                                       |
| -------------------------------------- | ------------------------------------------------------------- |
| `targets[].version`                    | Major version (`"17"`); required                              |
| `targets[].plan`                       | Size — `pg-s` … `pg-2xl`, [Plans](/docs/plans)                |
| `targets[].bootstrap_default_database` | Database created with the instance; the link's `.database`    |
| `targets[].replicas`                   | Instances (1 by default); more for read replicas and failover |
| `targets[].max_storage_gb`             | Cap on automatic storage growth                               |

Exactly one target per environment: a second Postgres is a second resource.

## Commands

| Command                                                               | Does                                            |
| --------------------------------------------------------------------- | ----------------------------------------------- |
| `pier add pg`, `pier set pg main`, `pier rm pg main`                  | declare, change, remove                         |
| `pier psql main [-- <psql args>]`                                     | your local `psql` with a session credential     |
| `pier pg credentials main [--uri]`                                    | credentials for any client; `--uri` is pipeable |
| `pier pg databases main`, `pier pg tables main`, `pier pg query main` | inspect without psql                            |
| `pier backups ls main`, `pier backups create main`                    | backups                                         |
| `pier restart main`                                                   | restart the instance                            |
| `pier logs main`, `pier monitor main`                                 | server log, connections, storage                |
| `pier pg plans`                                                       | the plan table                                  |

## Behaviour

* **Links resolve at start**: an app's `DATABASE_URL` is filled in when its target starts;
  a plan change or credential rotation does not change `pier.yaml`.
* Credentials minted by `pier psql` and `pier pg credentials` carry your workspace role
  and expire after an hour.
* Backups are taken continuously (point-in-time) and on demand; a removed instance stays
  restorable from [trash](/docs/concepts#trash) for 30 days.
* A `version` change re-creates the instance; a plan change restarts it.

## Tasks

[Add Postgres to an app](/docs/guides/add-postgres-to-an-app) · [Use Postgres from your laptop](/docs/guides/use-postgres-locally) ·
[Run database migrations](/docs/guides/run-database-migrations) · [Set up a staging environment](/docs/guides/set-up-a-staging-environment)