Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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 Backup
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index 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 current
docker 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
# PostgreSQL
psql -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 10
curl -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 β†’ Staging
diff --git a/src/common/migration-guide-rollback.spec.ts b/src/common/migration-guide-rollback.spec.ts
new file mode 100644
index 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/);
+ });
+});