Default SQLite connections to WAL

[JanJakes]

What changed

Journal mode:

• Default new SQLite connections to journal_mode = WAL.
• Skip defaulting to WAL when unavailable (e.g., on network filesystems).

Synchronous flag:

• Apply synchronous = NORMAL when WAL is used.
• Otherwise, use the SQLite default.

Other changes:

• Wire the SQLITE_JOURNAL_MODE override through the WordPress plugin connection paths.
• Accept journal_mode and synchronous in the WP_PDO_MySQL_On_SQLite driver options.
• Add connection setup tests for the defaults, overrides, invalid values, and the WAL fallback.

Why

WAL improves read/write concurrency for SQLite-backed WordPress installs, and synchronous = NORMAL avoids frequent sync to the main database. In WAL mode, NORMAL is safe. From the SQLite docs:

WAL mode is safe from corruption with synchronous=NORMAL, and probably DELETE mode is safe too on modern filesystems. WAL mode is always consistent with synchronous=NORMAL, but WAL mode does lose durability. A transaction committed in WAL mode with synchronous=NORMAL might roll back following a power loss or system crash. Transactions are durable across application crashes regardless of the synchronous setting or journal mode.

The synchronous=NORMAL setting provides the best balance between performance and safety for most applications running in WAL mode. You lose durability across power lose with synchronous NORMAL in WAL mode, but that is not important for most applications. Transactions are still atomic, consistent, and isolated, which are the most important characteristics in most use cases.

Benchmark

A local benchmark ran a WordPress-like 90% read / 10% write workload against the same database file with 4, 8, and 16 concurrent workers, comparing the trunk defaults with WAL + NORMAL (median of 3 runs, PHP 8.5.5, SQLite 3.53.0).

Workers	Config	Ops/s	p50	p95	p99
4	default	4,985	0.21 ms	3.94 ms	10.2 ms
4	WAL + NORMAL	15,982 (3.2×)	0.19 ms	0.73 ms	1.2 ms
8	default	5,249	0.24 ms	4.22 ms	22.6 ms
8	WAL + NORMAL	25,371 (4.8×)	0.20 ms	1.02 ms	1.5 ms
16	default	5,226	0.25 ms	10.25 ms	59.0 ms
16	WAL + NORMAL	30,300 (5.8×)	0.22 ms	1.43 ms	4.0 ms

This was run on an M4 MacBook Pro Max.

[adamziel]

This is super confusing. It's SYNCHRONOUS but it's NORMAL. Let's just stick to SQLite terminology and maybe even let go of constants:

Suggested change

	$synchronous = self::DEFAULT_SQLITE_WAL_SYNCHRONOUS;
	$synchronous = 'NORMAL';

Or even go super simple:

Suggested change

	$synchronous = self::DEFAULT_SQLITE_WAL_SYNCHRONOUS;
	$this->query( 'PRAGMA synchronous = NORMAL' );

The comment above explains what we're doing, I assume it's because the logic is so opaque here. I'd love to, instead, understand why we're doing this. Document the NORMAL mode inline and explain why we're defaulting to it when WAL is enabled and not otherwise and what is SQLite default value?

[JanJakes]

@adamziel Good point, thanks! Improved in a15ecdb.

[adamziel]

Suggested change

	if ( in_array( $synchronous, self::SQLITE_SYNCHRONOUS_SETTINGS, true ) ) {
	$this->query( 'PRAGMA synchronous = ' . $synchronous );
	}
	if ( in_array( $synchronous, self::SQLITE_SYNCHRONOUS_SETTINGS, true ) ) {
	$this->query( 'PRAGMA synchronous = ' . $synchronous );
	} else if ( isset( $synchronous ) ) {
	throw new PDOException( sprintf( '%s is not a valid `synchronous` PRAGMA value. ' ) );
	}

[adamziel]

Let's not accept invalid option values.

[adamziel]

Ditto for the journal mode, let's not skip that silently.

[JanJakes]

@adamziel Fixed in 8de3d1a. I used InvalidArgumentException as in the case of missing path, but not sure which is better—vs PDOException.