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

# plamotrack backups: database dump and restore guide

> How to back up and restore your plamotrack collection using pg_dump and pg_restore. Covers all three restore scenarios and what survives each.

Your collection lives in a Postgres database inside the Docker stack. There are two ways to back it up: a PostgreSQL dump (full fidelity, required for proper restores) and the CSV archive export in the app (great for a human-readable copy you can open in a spreadsheet). Always back up before upgrading.

## Quick backup from the app

Go to **Settings → Data management → Export** and download the ZIP archive. This is a CSV export — it's human-readable and can be imported back into plamotrack. For a complete database backup that preserves sessions, access tokens, and MCP client links, use the `pg_dump` method below.

## Database backup with pg\_dump

Run the following command from your plamotrack directory. The dump file is a portable Postgres archive.

```bash theme={null}
docker compose exec -T db sh -c \
  'exec pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' \
  > plamotrack-$(date +%F).dump
```

<Note>
  A backup is two things: the dump file **and** your `.env`. Keep them together. The `.env` holds the secrets (your database password and, in OIDC mode, `MCP_OAUTH_SIGNING_KEY`) that make the backup fully restorable.
</Note>

## Restoring a dump

Restore into an empty database — `pg_restore` will not merge cleanly into a populated one.

<Steps>
  <Step title="Tear down the current stack (removes the database volume)">
    ```bash theme={null}
    docker compose down -v
    ```

    <Warning>
      `docker compose down -v` deletes the `db-data` volume, which **is** your collection. Without `-v` the volume survives and `down` is safe. Take a backup first regardless.
    </Warning>
  </Step>

  <Step title="Start the database and wait for it to be ready">
    ```bash theme={null}
    docker compose up -d db --wait
    ```
  </Step>

  <Step title="Restore the dump">
    ```bash theme={null}
    docker compose exec -T db sh -c \
      'exec pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' \
      < plamotrack-2026-08-10.dump
    ```
  </Step>

  <Step title="Start everything back up">
    ```bash theme={null}
    docker compose up -d --build --wait
    ```
  </Step>
</Steps>

## What survives a restore

What comes back depends on which half of the backup you restore and which `.env` you pair it with.

| You restore                           | Collection | Browser sessions  | Access tokens | Linked MCP clients           |
| ------------------------------------- | ---------- | ----------------- | ------------- | ---------------------------- |
| Dump + same `.env`                    | ✅ intact   | ✅ still signed in | ✅ still valid | ✅ still linked               |
| Dump + different `.env`               | ✅ intact   | ✅ still signed in | ✅ still valid | ⚠️ clients re-authorise once |
| Dump taken before a client was linked | ✅ intact   | ✅ still signed in | ✅ still valid | ⚠️ that client re-authorises |

<Warning>
  Never run `docker compose down -v` unless you intend to delete the database. The `-v` flag deletes Docker volumes including your Postgres data. Running `docker compose down` without `-v` is safe — the volume survives.
</Warning>