vps/runbooks/vaultwarden-sqlite-to-postgres.md

# Runbook: Vaultwarden SQLite → Postgres (us2)

Target: [us2.wsvc.info](../hosts/us2.wsvc.info.md)  
Upstream: [Using the PostgreSQL Backend](https://github.com/dani-garcia/vaultwarden/wiki/Using-the-PostgreSQL-Backend) · [docs/vaultwarden-upstream.md](../docs/vaultwarden-upstream.md)

**Done on 2026-08-01** for this host. Keep this as the replay checklist. This
is an exceptional, destructive migration procedure: it is intentionally not
automated by the routine Ansible reconciliation playbook.

## Summary of what we did

1. Backup `vw-data` + `.env` → `backups/pre-pg-migrate-<timestamp>/`
2. Baseline counts from SQLite (then: users=1, ciphers=1327)
3. Drop/recreate empty Postgres DB; pin image `vaultwarden/server:1.37.1`
4. Set compose `DATABASE_URL=postgresql://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}`
5. Start VW once → diesel schema → stop
6. `pgloader` **data only** (exclude `__diesel_schema_migrations`) with CAST bigint→integer
7. Remaining intentional bigints: `attachments.file_size`, `twofactor.last_used`, `twofactor_duo_ctx.exp`
8. Align `config.json` SMTP **587/starttls**, `ip_header=X-Forwarded-For`, `DOMAIN` without trailing slash
9. Rotate `DB_PASS` / `PGWEB_PASS`; `pgweb` behind compose `profiles: [debug]`
10. Move live sqlite file to `backups/sqlite-cold/` (cold only)
11. After VW recreate, **restart Traefik** so Docker provider picks up the router

## Critical pitfalls

- `config.json` overrides `.env` (admin wins). Fix SMTP there or via `/admin`.
- SMTP password drift: if `.env` AUTH works but VW mail fails with `535`, sync `vw-data/config.json` (+ `.smtp-credentials`) to the mailbox password — do not assume env alone is enough.
- From this network, **mx2:465 times out**; use **587 + starttls**.
- After recreating `vaultwarden`, Traefik may 404 until `docker restart traefik`.
- pgloader needs a **writable** directory for the sqlite file (CANTOPEN if mount is awkward).
- After pgloader, wrong integer types → silent “wrong password”; see [Discussion #7134](https://github.com/dani-garcia/vaultwarden/discussions/7134).
- Do not commit `.env` or load files with passwords into git.

## Rollback

1. `docker compose stop vaultwarden`
2. Restore `vw-data` from `backups/pre-pg-migrate-*` (including sqlite)
3. Remove `DATABASE_URL` from compose `environment`
4. `docker compose up -d vaultwarden` && `docker restart traefik`