feat(database): add walMode config option

[eumaninho54]

Summary

SQLite's default journal mode blocks reads while a write is in progress (exclusive lock on the whole file). The native sync engine writes to SQLite in the background — sometimes across multiple pages of a sync session — while the JS side may be reading through useQuery at the same time. Without WAL, those background writes can make the UI's queries wait until the write commits.

WAL (Write-Ahead Logging) mode fixes this: writes are appended to a separate .wal file instead of overwriting the database in place, so concurrent reads keep seeing a consistent snapshot without blocking on an in-flight write.

This was already being turned on unconditionally in SQLiteConnection's constructor (PRAGMA journal_mode=WAL), with no way to opt out and no visibility for the consumer. This PR turns it into a first-class, documented option on Database.configure(), in the same spirit as an ORM config option — not something the developer has to know to enable by running a raw PRAGMA themselves (which is how expo-sqlite currently does it).

Changes

• IConfigureProps.walMode?: boolean (TS-facing, default true) — new option on Database.configure({...}).
• ConfigureParams.walMode?: boolean — added to the Nitro spec type (src/specs/types/ConfigureParams.ts) and regenerated via nitrogen (nitrogen/generated/shared/c++/ConfigureParams.hpp).
• ConfigureDb.class.ts — defaults walMode to true when calling the native bridge if the caller didn't pass it.
• SQLiteConnection(path, walMode = true) — only runs PRAGMA journal_mode=WAL when walMode is true; otherwise leaves SQLite's own default journal mode untouched. Default behavior is unchanged (WAL was already always-on before).
• DatabaseManager::open(dbName, walMode = true) and HybridSalveDatabase::configure — thread the option from the JS-facing configure() call down to the connection.

Test plan

• npm run test:native — 73 test cases / 200 assertions (was 69/196), including two new suites:
  • cpp/tests/database/SQLiteConnectionWalModeTests.cpp — asserts PRAGMA journal_mode is wal by default and stays non-wal when walMode: false is passed directly to SQLiteConnection.
  • Two new cases in cpp/tests/database/HybridSalveDatabaseTests.cpp exercising the full path end-to-end through the JSI bridge (db.configure({ walMode: false }) → db.execute('PRAGMA journal_mode', [])).
• npm test (Jest) — 84 tests passing, no regressions.
• npx tsc --noEmit — no type errors.

Summary by CodeRabbit

• New Features

  • Added an optional walMode configuration setting for database connections.
  • WAL mode is enabled by default, with the option to disable it when configuring the database.

• Tests

  • Added coverage verifying default WAL behavior and explicitly disabled WAL mode.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 845a6a85-8800-4e98-ba43-f8f736062c7d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/wal-mode-config

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cpp/database/DatabaseManager.cpp`:
- Around line 7-10: Update SQLiteConnection initialization used by
DatabaseManager::open to explicitly set the journal mode when walMode is false,
selecting the non-WAL mode instead of leaving an existing database in WAL mode.
Preserve the current WAL setup when walMode is true.

In `@cpp/database/SQLiteConnection.cpp`:
- Around line 19-21: Update the SQLite initialization logic around the walMode
setting to explicitly switch an existing database back to DELETE when walMode is
false, including the required coordination and error handling for the
journal-mode change. Preserve WAL configuration when walMode is true, and add a
regression test that reopens the same database with walMode disabled and
verifies WAL is no longer active.
- Around line 19-21: Update the WAL initialization in SQLiteConnection to
capture the result of the `PRAGMA journal_mode=WAL` execution, read the returned
journal mode, and throw when it is not `wal`; do not silently continue in DELETE
mode.

In `@cpp/tests/database/HybridSalveDatabaseTests.cpp`:
- Around line 199-206: Update the assertion in the walMode-disabled test around
HybridDatabaseHarness::run to require the exact SQLite default journal-mode
result, "delete", rather than merely checking that the result is not "wal".

In `@cpp/tests/database/SQLiteConnectionWalModeTests.cpp`:
- Around line 14-18: Update the assertion in the SQLiteConnection(walMode=false)
test to require that the journal mode is exactly "delete", rather than merely
checking it is not "wal". Keep the existing query and result extraction
unchanged.

In `@src/database/classes/ConfigureDb/types/IConfigureProps.ts`:
- Around line 10-16: Update the walMode documentation in IConfigureProps to
describe WAL as reducing read/write contention and generally allowing concurrent
access, without guaranteeing that reads are never blocked. Preserve the existing
purpose, option name, and default value.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c114c3aa-657d-4a65-9590-2c041993a339

📥 Commits

Reviewing files that changed from the base of the PR and between 5a809ef and 38aefb9.

⛔ Files ignored due to path filters (1)

• nitrogen/generated/shared/c++/ConfigureParams.hpp is excluded by !**/generated/**

📒 Files selected for processing (10)

• cpp/database/DatabaseManager.cpp
• cpp/database/DatabaseManager.hpp
• cpp/database/HybridSalveDatabase.cpp
• cpp/database/SQLiteConnection.cpp
• cpp/database/SQLiteConnection.hpp
• cpp/tests/database/HybridSalveDatabaseTests.cpp
• cpp/tests/database/SQLiteConnectionWalModeTests.cpp
• src/database/classes/ConfigureDb/ConfigureDb.class.ts
• src/database/classes/ConfigureDb/types/IConfigureProps.ts
• src/specs/types/ConfigureParams.ts