From ca5e52b8edd138d41da5d06ae9aa4955b0f7517c Mon Sep 17 00:00:00 2001 From: Charlie Tonneslan Date: Sun, 17 May 2026 16:03:38 -0400 Subject: [PATCH] docs: mention WAL mode for concurrently written databases Per #2024. Immutable mode is the right answer when the file won't change; WAL mode is the right answer when something else is writing to the file while Datasette is reading it. Add a small section in performance.rst that points at the sqlite WAL docs and the TIL Simon already wrote, with the one-liner sqlite3 incantation to flip a file into WAL mode. Closes #2024. Signed-off-by: Charlie Tonneslan --- docs/performance.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/performance.rst b/docs/performance.rst index 4427757c..ffda7106 100644 --- a/docs/performance.rst +++ b/docs/performance.rst @@ -24,6 +24,19 @@ To open a file in immutable mode pass it to the datasette command using the ``-i When you open a file in immutable mode like this Datasette will also calculate and cache the row counts for each table in that database when it first starts up, further improving performance. +.. _performance_wal_mode: + +WAL mode for concurrent writers +------------------------------- + +If a database file is being written to by another process while Datasette serves reads from it, you should enable SQLite's `write-ahead logging `__ (WAL) mode on the file. By default SQLite uses rollback journaling, which takes a database-wide lock during writes and can cause Datasette's read queries to fail with ``database is locked`` errors when those writes happen. + +You can flip a database into WAL mode once with the ``sqlite3`` CLI:: + + sqlite3 data.db 'PRAGMA journal_mode=WAL;' + +The setting is persistent: once a database is in WAL mode it stays in WAL mode for any future connection until you explicitly switch it back. See `Simon Willison's TIL `__ for a fuller writeup. + .. _performance_inspect: Using "datasette inspect"