> Markdown export: /developers/upgrades-and-backups.md
> HTML: /developers/upgrades-and-backups
---
description: Operator checklist for Postgres backups, upgrades, and safe environment variable changes.
audience: operator
---

# Upgrades & backups

> **In plain terms:** How to back up your Postgres database before upgrades and safely apply new Eigen Mesh releases on a self-hosted deployment.

## Who this is for

- **Operators** running self-hosted Docker deployments in production
- **Contributors** planning maintenance windows for key rotation

## Backups

Eigen Mesh stores all durable state in PostgreSQL (relational data, pgvector embeddings, Apache AGE graph). **Back up the database volume** before upgrades or key rotation.

### Docker Compose

```sh
# Stop writes (optional, for consistent snapshot)
docker compose stop app

# Dump from running db container
docker compose exec db pg_dump -U eigen -Fc eigen > eigen-backup-$(date +%Y%m%d).dump

docker compose start app
```

Restore:

```sh
docker compose exec -T db pg_restore -U eigen -d eigen --clean --if-exists < eigen-backup-YYYYMMDD.dump
```

### What to back up

| Asset | Location |
|-------|----------|
| Database | Postgres volume (`pgdata` in compose) |
| Secrets | `.env` or hosting dashboard (store securely offline) |
| Custom compose overrides | Your fork or deployment notes |

## Upgrading

1. **Back up** the database (above).
2. **Pull** the latest eigen repository release or commit.
3. **Review** release notes for breaking env var or migration changes.
4. **Rebuild and restart:**
   ```sh
   docker compose up -d --build
   ```
5. **Apply schema** if release includes migrations:
   ```sh
   docker compose exec app npx drizzle-kit push --force
   docker compose exec app node scripts/apply-rls.mjs
   ```
6. **Verify** `/api/health` and a test capture.

## Environment variable changes

| Change | Risk | Procedure |
|--------|------|-----------|
| `ORIGIN` domain change | OAuth callbacks break | Update OAuth app callback URLs; redeploy |
| `TENANT_MASTER_KEY` rotation | Decrypt failures | Re-encryption migration — [Tenant envelope encryption](/developers/tenant-envelope-encryption) |
| LLM gateway switch | Capture/search failures until keys valid | Update vars; test capture before announcing |
| `POSTGRES_PASSWORD` change | App can't connect | Update `DATABASE_URL`, `DATABASE_ADMIN_URL`, and Postgres role passwords together |

## Consolidation cron

After upgrades, confirm pg_cron schedule still points to `CONSOLIDATION_INTERNAL_URL`. If the app container name or network changed, update env and re-run cron bootstrap from the eigen repo.

## Next steps

- [Troubleshooting](/developers/troubleshooting)
- [Environment variables](/developers/environment-variables)
- [What is Eigen Mesh?](/developers/what-is-eigenmesh)
- [Overview & quick start](/developers/getting-started)