Skip to content

Conversation

@fang-ling
Copy link

Motivation

SQLite journal mode has an impact on performance, concurrency, and durability characteristics. Exposing this as a configuration option allows users to:

  • Enable WAL (write-ahead log) for better concurrency and throughput
  • Match journal mode to deployment requirements (e.g. embedded, ephemeral, or high-performance workloads)
  • Avoid relying on external PRAGMA setup

Modifications

  1. Introduces a new SQLiteConfiguration.JournalMode enum covering all supported SQLite journal modes:
  • DELETE: Delete journal mode (SQLite default). Journal file is deleted after each transaction.
  • WAL: WAL (Write-Ahead Logging) mode. Provides better concurrency and performance.
  • TRUNCATE: Truncate journal mode. Journal file is truncated to zero length instead of deleted.
  • PERSIST: Persist journal mode. Journal file is left on disk but header is overwritten.
  • MEMORY: Memory journal mode. Journal is stored in memory.
  • OFF: No journal mode. No rollback capability (dangerous).
  1. Adds a journalMode property to SQLiteConfiguration with a default of .delete during the initialization, preserving existing behavior.
  2. Automatically applies the configured journal mode when a connection is opened via:
PRAGMA journal_mode = <mode>

Additionally, tests have been added to verify that each supported journal mode is correctly applied and that the journal mode configuration works alongside foreign key enforcement.

This change is fully backward-compatible and opt-in.

Future directions

SQLite has an experimental wal2 journal mode under active development. With the introduction of the JournalMode enum, supporting wal2 in the future would be a straightforward, non-breaking extension once it becomes stable and widely available.

@fang-ling fang-ling requested a review from gwynne as a code owner January 10, 2026 04:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant