Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
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.mdindex 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 Strategydiff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex 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 `DATis copied under a read lock, and an app write that meets it waits for the copy to end, failing if thecopy outlasts the 30 s busy timeout. The SQLite driver waits synchronously, so while a write waits thewhole 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.mdindex 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 afixed 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.shindex 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/nullelsediff --git a/src/database/main-connection.ts b/src/database/main-connection.tsindex 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;