Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(migration): list the batched session delete in the upgrade hazards

Yudhi Armyndharis22e9de5a9f0f
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index 61e70f193..62c609ad0 100644
--- a/docs/14-migration-guide.md
+++ b/docs/14-migration-guide.md
@@ -889,6 +889,7 @@ skips: check `pg_index.indisvalid` and drop the invalid index before building it
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `next` | The first boot rewrites every legacy `messages.type` value in one `UPDATE`, inside the transaction of the other pending migrations: on PostgreSQL about a minute per million legacy rows, with the port closed. Only a database whose conversion kept being cancelled on `0.25.0` still holds a large backlog | Count them with `SELECT count(*) FROM messages WHERE type IN ('chat', 'buttons_response', 'list_response', 'template_button_reply', 'ptt', 'vcard', 'multi_vcard')`; above a few million, run the migrations first (section 14.5), or raise `startupProbe.failureThreshold` to cover about a minute per million legacy rows (measured with twelve indexes on the table) on top of the index builds |
| `next` | A production boot refuses a `METRICS_TOKEN` that is the `.env.example` placeholder or a weak value the other secrets are checked against (`test`, `change-me`, `changeme`, `password`, `secret`, `admin`, `demo` and a few more), trimmed and case-insensitive | Set a long random token, or unset `METRICS_TOKEN` to keep `/api/metrics` disabled (it answers `404`); there is no length floor, so a short value that is not on the list still boots |
+| `next` | A session delete removes its messages, outbox rows and delivery failures in batches (2000 rows on SQLite, 500 on PostgreSQL): on SQLite 300,000 to 600,000 messages take about 20 to 60 s, against about 10 s on `0.25.0`, which froze the whole process. A failure part-way leaves the session with fewer rows | Give the delete a client or proxy timeout that covers a large session, and repeat it after a failure: the repeat finishes the job |
| `0.25.0` | Once teardown begins (SIGTERM, SIGINT, `POST /api/infra/restart`) every request except `/api/health`, `/api/health/*`, the dashboard's HTML pages and CORS preflights answers `503` with `Connection: close`, `GET /api/infra/health` included | Probe `/api/health/live` for liveness that survives teardown, and retry a `503` once the instance is up again |
| `0.25.0` | `stop_grace_period` (Docker) and `terminationGracePeriodSeconds` (Kubernetes) go from 45 to 75 s, and a stop that runs 67 s past the shutdown delay exits with status 1 instead of 137 | Raise a pinned 45 s value to at least 75 s, plus the excess of `SHUTDOWN_DELAY_MS` over 3 s and of `WEBHOOK_SHUTDOWN_DRAIN_MS` over 5 s; on Helm upgrade with `--reset-then-reuse-values` (3.14 or later) or `-f values.yaml`, since plain `--reuse-values` keeps the 0.24.0 defaults; a container that drops all capabilities and starts as root must add `KILL` to the capabilities 0.24.0 shipped, or a stop never reaches the app; update exit-code alerts |
| `0.25.0` | `400` instead of `201` or `200` for a phone number WhatsApp reports as unregistered (Baileys; `503` when the lookup gets no answer) and for `vote-poll` with no matching option text (whatsapp-web.js) | Handle `400` (`POLL_OPTION_NOT_FOUND` carries `validOptions`) and `503` on these routes; an empty `options` list still clears a vote |