Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(migration): restore the main database in the quick rollback
Yudhi Armyndharis0fcbcb8b4504
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex 6f33a1873..5d5e13260 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -586,6 +586,17 @@ curl -H "X-API-Key: $API_KEY" http://localhost:2785/api/health> start on 0.23.5. Restoring both directories from that backup returns every session to its previous> pairing.+> Rolling back past 0.23.6 loses API key chat scopes: an older image does not enforce `allowedChats`.+> The restore in step 2 returns every key to its state at backup time, so keys revoked since then work+> again; revoke them again. Changing only the image tag, or `helm rollback`, keeps the current+> `main.sqlite`, and the older image's schema sync then drops the `allowedChats` column. If 0.24.0 or+> later last booted that file, the next upgrade refuses to boot, naming `api_keys.allowedChats`, until+> `main.sqlite` is restored, which brings the scopes back, or the column's ledger row is deleted, after+> which the column comes back empty (every chat). A file whose ledger lacks that migration (0.23.6 and+> 0.23.7 on their default `MAIN_DATABASE_SYNCHRONIZE`) is not detected and boots with the column+> empty. Revoke every chat-scoped key before such a rollback. See the warning in+> [14 - Migration Guide: Rollback Procedures](./14-migration-guide.md#146-rollback-procedures).+---### Runbook: Database Backupdiff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex 0ae038b5c..03769c0d1 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -873,15 +873,21 @@ echo "π Rolling back to v${TARGET_VERSION}..."# 1. Stop currentdocker compose down-# 2. Restore database+# 2. Restore the databases, both from the same backup. The main DB (API keys, audit log) is always+# SQLite, whatever the data store is. Stale journal files go first, as scripts/restore.sh does,+# so SQLite cannot replay them into the restored file.echo "π₯ Restoring database..."if [ -f "$BACKUP_DIR/database.sql" ]; then# PostgreSQLpsql -h "$DATABASE_HOST" -U "$DATABASE_USERNAME" -d "$DATABASE_NAME" < "$BACKUP_DIR/database.sql"else# SQLite+ rm -f ./data/openwa.sqlite-{wal,shm,journal}cp "$BACKUP_DIR/openwa.sqlite" ./data/fi+rm -f ./data/main.sqlite-{wal,shm,journal}+cp "$BACKUP_DIR/main.sqlite" ./data/+[ -f "$BACKUP_DIR/.api-key" ] && cp "$BACKUP_DIR/.api-key" ./data/# 3. Restore auth sessions (SESSION_DATA_PATH + BAILEYS_AUTH_DIR)echo "π₯ Restoring auth sessions..."@@ -905,10 +911,15 @@ sleep 10curl -f http://localhost:2785/api/health && echo "β Rollback successful"```+The main DB and `.api-key` must come from the same backup as the data store. Restoring `main.sqlite`+returns every API key to its state at backup time: keys created since then are gone, and keys revoked+since then work again, so revoke those again after the rollback.+> [!TIP]> For an archive produced by `scripts/backup.sh`, follow> [11 - Runbook: Restore from Backup](./11-operational-runbooks.md#runbook-restore-from-backup)-> instead. It also restores the Main DB (`main.sqlite`), which the script above does not touch, and+> instead. It restores the databases, `.api-key`, the auth state, media and plugin state from the+> archive, but not the host `.env` or compose file, which step 4 above covers, and> it runs `scripts/restore.sh` from the image against the production compose named volume> (`openwa-data`) or the Helm PVC. A host run of `./scripts/restore.sh`, like the copies into `./data`> above, reaches only a bare-metal install or `docker-compose.dev.yml`, which bind-mounts `./data`;@@ -951,6 +962,24 @@ flowchart TD> A session first paired on the newer image is not in that backup and must be paired again either way.> Baileys sessions are unaffected.+> [!WARNING]+> A rollback to a release older than 0.23.6 loses API key chat scopes. Those images do not know+> `allowedChats`, so while one runs, a chat-scoped key reaches every chat of the sessions it is+> allowed. Restoring `main.sqlite` from a backup taken before the upgrade, as the script above and+> [11 - Runbook: Version Upgrade](./11-operational-runbooks.md#runbook-version-upgrade) do, avoids the+> rest of this. Keeping the current `main.sqlite` (changing only the image tag, or `helm rollback`,+> which keeps the volume) does not: at its first boot the older image's schema sync drops the+> `allowedChats` column. Upgrading again then stops boot with a `MainSchemaMismatchError` naming+> `api_keys.allowedChats`, because the migrations ledger that 0.24.0 and later write still records the+> column's migration. To recover, restore `main.sqlite` from the backup taken before the rollback,+> which brings the chat scopes back with it, or delete that ledger row as+> [05 - Database Design, section 5.6](./05-database-design.md#56-migration-strategy) shows, after which+> the column comes back empty, which means every chat. Before such a rollback, revoke every key that has+> `allowedChats` (`POST /api/auth/api-keys/:id/revoke`) and issue new ones after upgrading again.+> Starting the older image with `MAIN_DATABASE_SYNCHRONIZE=false` keeps the column and its values for+> the next upgrade (the compose file forwards it since 0.14.5), but the older image still does not+> enforce them.+## 14.7 Environment Migration### Development β Stagingdiff --git a/src/common/migration-guide-rollback.spec.ts b/src/common/migration-guide-rollback.spec.tsnew file mode 100644index 000000000..95ca27dec--- /dev/null+++ b/src/common/migration-guide-rollback.spec.ts@@ -0,0 +1,26 @@+import { readFileSync } from 'node:fs';+import { join } from 'node:path';++/**+ * The Quick Rollback script in docs/14 copies the host `.env` and `docker-compose.yml` back from its+ * backup directory. An archive from `scripts/backup.sh` carries neither, so the TIP that sends such an+ * archive to the restore runbook must not promise the same files as that script.+ */+describe('docs/14 rollback TIP', () => {+ const root = join(__dirname, '..', '..');+ const read = (path: string): string => readFileSync(join(root, path), 'utf8');++ it('does not claim the archive restores the host .env or compose file', () => {+ const staged = [...read('scripts/backup.sh').matchAll(/"\$STAGE\/([^"]+)"/g)].map(match => match[1]);+ expect(staged).toContain('main.sqlite');+ expect(staged).not.toContain('.env');+ expect(staged).not.toContain('docker-compose.yml');++ const guide = read('docs/14-migration-guide.md');+ const start = guide.indexOf('> For an archive produced by `scripts/backup.sh`');+ expect(start).toBeGreaterThan(-1);+ const tip = guide.slice(start, guide.indexOf('\n\n', start)).replace(/\n> /g, ' ');+ expect(tip).not.toMatch(/same files/);+ expect(tip).toMatch(/not the host `\.env` or compose file/);+ });+});