Fix site boot failure when the SQLite database is left in WAL mode

[wojtekn]

Related issues

• Fixes Site fails to start with "Cannot escape data without an active database connection" fatal error #4565
• Related to STU-2279
• Windows CI failing intermittently

How AI was used in this PR

Claude Code diagnosed the crash from the issue's stack trace, confirmed the WAL theory against real site databases and by polling journal mode during a live start, wrote the fix and its tests, and verified that each new test fails against the pre-fix code. I reviewed the analysis and the change myself.

Proposed Changes

Sites could stop booting entirely, failing with a fatal that names the wrong subsystem:

PHP Fatal error: Uncaught RuntimeException: Cannot escape data without an active database connection.

The real failure is the database connection, not escaping. Since sqlite-database-integration v3.0.0 the driver connects in WAL journal mode by default, and WAL is persisted in the database file header — so any boot that writes to the database leaves it in WAL, not just an import.

WAL needs a shared-memory index (the -shm file), which SQLite coordinates through file locks. SQLite's WAL support is compiled into PHP-WASM, but the locks underneath it are not real: @php-wasm/node emulates them on the host, with separate implementations per platform. The POSIX one delegates to flock/fcntl, while the Windows one maps onto real LockFileEx/UnlockFileEx calls that are released only during orderly cleanup. A lock outliving its process — or contention between the outgoing and incoming server across a restart — makes reopening a WAL database fail intermittently with "database is locked".

That failure is then swallowed: wpdb::bail() only calls wp_die() when show_errors is on, and it defaults to off. WordPress carries on booting with $wpdb->dbh still null and crashes several frames later inside esc_sql(), where the SQLite driver's _real_escape() throws instead of degrading the way core's does. That mismatch is what turns a recoverable connection failure into a hard fatal, and why the reported error points nowhere near the cause.

Studio already had the conversion that prevents this, but it only ran after an import — written when imports really were the only way a database ended up in WAL. The v3.0.0 default silently widened the problem to every site without widening the guard. This runs it on every Playground start, which explains the "worked for two days, then failed permanently" reports: normal use flipped the database to WAL, and the header kept it there.

Separately, stopping a server could return while the process was still alive. When the graceful stop timed out, the SIGKILL fallback returned without waiting for the process to actually exit, while still reporting "WordPress server stopped". Callers restart immediately afterwards, and on Windows the dying process's handle on the SQLite file made that restart fail to connect. This is the likely cause of the intermittent CLI E2E Tests on windows failures on applies a changed admin password to WordPress, which stops and restarts a site back to back.

Native PHP is deliberately left alone: it runs the platform's own SQLite against real OS locks, with no emulation layer in between, so WAL works there as it does anywhere else. The conversion is gated to the Playground runtime for that reason.

Testing Instructions

The underlying failure is Windows-only and intermittent, so CI on this PR is the real test — particularly the CLI E2E Tests on windows job.

To verify the conversion on any platform:

1. Start a site, then stop it.
2. Confirm the database is in WAL mode:

   node -e "const{DatabaseSync}=require('node:sqlite');const d=new DatabaseSync(process.env.HOME+'/Studio/<site>/wp-content/database/.ht.sqlite',{readOnly:true});console.log(d.prepare('PRAGMA journal_mode').get().journal_mode)"

3. Start the site again and confirm it serves its homepage and a DB-backed endpoint such as /?rest_route=/wp/v2/posts.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

🤖 Generated with Claude Code

[wpmobilebot]

📊 Performance Test Results

Comparing b461fe3 vs trunk

app-size

Metric	trunk	b461fe3	Diff	Change
App Size (Mac)	1456.80 MB	1456.84 MB	+0.05 MB	⚪ 0.0%

site-editor

Metric	trunk	b461fe3	Diff	Change
load	1209 ms	1202 ms	7 ms	⚪ 0.0%

site-startup

Metric	trunk	b461fe3	Diff	Change
siteCreation	7518 ms	7525 ms	+7 ms	⚪ 0.0%
siteStartup	3373 ms	3367 ms	6 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)