Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(session): state the batch sizes of the session delete

Yudhi Armyndharis3e24039f02f0
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index dc5a6e61b..af93d3159 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1286,7 +1286,7 @@ Delete a session.
**Response** `204` — empty body (`@HttpCode(204)`, returns void). A `findOne` lookup runs first, so a missing id yields `404`.
-The delete first removes the session's messages, webhook outbox rows and webhook delivery-failure records in batches (2000 rows on SQLite, 500 on PostgreSQL) that are not atomic with the rest: a failure part-way (a database error, a timeout, a restart) leaves the session in place with fewer rows, and repeating the delete finishes it. It then removes, in one transaction, the session's message batches, chat states, received statuses, webhooks, templates, stored Baileys messages, automation rules, integration dead-letter rows and send idempotency claims together with the session itself, then purges its on-disk auth data. It keeps the audit log, the LID mappings, and the integration conversation mappings (so a re-paired session keeps its provider conversations); ingress dedup rows age out on their own after `INGRESS_DEDUP_RETENTION_DAYS` (default 7).
+The delete first removes the session's messages, webhook outbox rows and webhook delivery-failure records in batches (on SQLite up to 2000 rows, each sized to about 150 ms; 500 rows on PostgreSQL) that are not atomic with the rest: a failure part-way (a database error, a timeout, a restart) leaves the session in place with fewer rows, and repeating the delete finishes it. It then removes, in one transaction, the session's message batches, chat states, received statuses, webhooks, templates, stored Baileys messages, automation rules, integration dead-letter rows and send idempotency claims together with the session itself, then purges its on-disk auth data. It keeps the audit log, the LID mappings, and the integration conversation mappings (so a re-paired session keeps its provider conversations); ingress dedup rows age out on their own after `INGRESS_DEDUP_RETENTION_DAYS` (default 7).
**Errors:** `401` missing/invalid key · `403` key not scoped to this session, or key role below OPERATOR · `404` session not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; on a `409` the row is **not** deleted and no hook/auth-purge runs — retry after cleanup settles), or, on a multi-node deployment, another node currently holds this session's live engine (no `code`; nothing is deleted; send the delete to the owning node) · `503` the session could not be claimed for the delete because the database did not answer (nothing is deleted; retry)
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index b738369c0..d0b997586 100644
--- a/docs/14-migration-guide.md
+++ b/docs/14-migration-guide.md
@@ -889,7 +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 |
+| `next` | A session delete removes its messages, outbox rows and delivery failures in batches (about 150 ms, at most 2000 rows, on SQLite; 500 rows on PostgreSQL): on SQLite it takes three to four times as long as the one statement of `0.25.0`, which froze the 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 |
| `next` | `restore.sh` stops before it copies anything, naming the key, when a path from the archive's own `.env.generated` leads out of the data directory | Set that key in the environment or `./.env` to restore there; the default paths and a leftover `./uploads` restore as before |
| `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 |