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

Runbook: Vaultwarden SQLite → Postgres (us2)

Target: us2.wsvc.info
Upstream: Using the PostgreSQL Backend · 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.
• 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