Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: state the fixed SQLite busy timeout and its event-loop cost

Yudhi Armyndharis1a1b4a9b65f1
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.md
index 7d3d3cf1b..e30a6d6d4 100644
--- a/docs/03-system-architecture.md
+++ b/docs/03-system-architecture.md
@@ -1436,11 +1436,12 @@ return {
> **Note:** OpenWA does not currently apply SQLite-specific concurrency hardening. There is **no**
> `journal_mode = WAL` PRAGMA, no `SqliteWriteQueueService`, and no application-level write
-> serialization in the source. SQLite is used with TypeORM's defaults, so its standard
-> single-writer behavior applies. For high write-concurrency or multi-session deployments, use
-> PostgreSQL (`DATABASE_TYPE=postgres`). `MAX_CONCURRENT_SESSIONS` (default `0`, unlimited) caps
-> concurrent sessions on any database. Cross-dialect schema differences are handled at migration
-> time (see below), not by a runtime optimizations layer.
+> serialization in the source. SQLite is used with TypeORM's defaults apart from a fixed 30 s busy
+> timeout (`SQLITE_BUSY_TIMEOUT_MS`), so its standard single-writer behavior applies. For high
+> write-concurrency or multi-session deployments, use PostgreSQL (`DATABASE_TYPE=postgres`).
+> `MAX_CONCURRENT_SESSIONS` (default `0`, unlimited) caps concurrent sessions on any database.
+> Cross-dialect schema differences are handled at migration time (see below), not by a runtime
+> optimizations layer.
#### Migration Strategy
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index ec5f140c1..d1e5414d6 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -634,14 +634,14 @@ SQLite file (`main.sqlite` on every deployment, plus the data database with `DAT
is copied under a read lock, and an app write that meets it waits for the copy to end, failing if the
copy outlasts the 30 s busy timeout. The SQLite driver waits synchronously, so while a write waits the
whole gateway stalls with it (API, WebSocket, engine events, health probes), not only that write; run
-the backup in a quiet window, or stop the container for a large database.
-Engine authentication state (`sessions/`, `baileys/`) is copied while the engines write
-it, so a restored session can need re-pairing; for a copy that is consistent by construction, stop
-the sessions first (`POST /api/sessions/:id/stop`), or stop the container and archive the volume.
-A stopped session stays down across restarts, even with `AUTO_START_SESSIONS=true`, so start each
-one again with `POST /api/sessions/:id/start` once the backup is copied. From 0.24.0 the stop is
-recorded in the backed-up database, so a restore of that archive keeps the session stopped too; an
-archive taken on 0.23.7 or earlier records no stop.
+the backup in a quiet window, or stop the container for a large database. Engine authentication
+state (`sessions/`, `baileys/`) is copied while the engines write it, so a restored session can need
+re-pairing; for a copy that is consistent by construction, stop the sessions first
+(`POST /api/sessions/:id/stop`), or stop the container and archive the volume. A stopped session
+stays down across restarts, even with `AUTO_START_SESSIONS=true`, so start each one again with
+`POST /api/sessions/:id/start` once the backup is copied. From 0.24.0 the stop is recorded in the
+backed-up database, so a restore of that archive keeps the session stopped too; an archive taken on
+0.23.7 or earlier records no stop.
**Prerequisites:**
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 36c2c9be2..21e3967ac 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1105,7 +1105,8 @@ sqlite3 ./data/openwa.sqlite "PRAGMA journal_mode=WAL;"
There is no `DATABASE_SQLITE_BUSY_TIMEOUT`-style env knob — both SQLite connections wait a
fixed 30 s on a lock (`SQLITE_BUSY_TIMEOUT_MS`, matching `scripts/backup.sh`'s `.timeout 30000`)
before failing with `SQLITE_BUSY`, and `better-sqlite3` waits synchronously, so the whole gateway
-stalls for as long as a write waits. If locks persist under concurrent sessions, migrate to PostgreSQL.
+stalls for as long as a write waits. If locks persist under concurrent sessions, migrate to
+PostgreSQL.
**When to Migrate to PostgreSQL:**
diff --git a/scripts/backup.sh b/scripts/backup.sh
index b45bf58aa..758a3382a 100755
--- a/scripts/backup.sh
+++ b/scripts/backup.sh
@@ -181,9 +181,10 @@ backup_sqlite() {
if command -v sqlite3 >/dev/null 2>&1; then
# The app writes in rollback-journal mode, and a bare .backup gave up on the first lock it met and
# restarted after every outside write, so a busy gateway never got a backup. The read transaction
- # lets the copy finish in one pass, but it blocks every app write until the copy ends, and a write
- # that outlasts the app's SQLite busy timeout fails. The busy timeout here waits out a commit, and
- # -init /dev/null keeps the operator's sqlite3 rc file out of the run.
+ # lets the copy finish in one pass, but it blocks every app write, and with it the app's event
+ # loop, until the copy ends, and a write that outlasts the app's SQLite busy timeout fails. The
+ # busy timeout here waits out a commit, and -init /dev/null keeps the operator's sqlite3 rc file
+ # out of the run.
sqlite3 -init /dev/null -cmd ".timeout 30000" "$src" \
"BEGIN" "SELECT count(*) FROM sqlite_master" ".backup '$dest'" "COMMIT" >/dev/null
else
diff --git a/src/database/main-connection.ts b/src/database/main-connection.ts
index 6d32002de..2bb1a40df 100644
--- a/src/database/main-connection.ts
+++ b/src/database/main-connection.ts
@@ -20,6 +20,7 @@ export class MainSchemaMismatchError extends Error {
* How long a runtime SQLite write waits on a lock before failing with SQLITE_BUSY. scripts/backup.sh
* holds a read transaction for each file's whole online copy and blocks writes until it ends, so
* this matches the backup's own `.timeout 30000` instead of better-sqlite3's 5 s default.
+ * better-sqlite3 waits synchronously, so the wait blocks the event loop.
*/
export const SQLITE_BUSY_TIMEOUT_MS = 30_000;