PDO API foundations #291

JanJakes · 2025-12-05T14:23:52Z

This PR implements foundational PDO APIs and uses them in the existing WP_SQLite_Driver class.

The changes are best understood commit-by-commit, and they include the following:

Make WP_PDO_MySQL_On_SQLite extend PDO.
Implement PDO::exec() API.
Implement PDO::query() API.
Implement PDOStatement API for in-memory data (operating on PHP arrays) as WP_PDO_Synthetic_Statement. This is required for PDO::query() that must return a PDOStatement instance.
Implement PDOStatement::fetch() and PDOStatement::fetchAll() with the most common PDO fetch modes.
Implement PDO and PDOStatement getAttribute() and setAttribute() methods.
Implement PDOStatement::setFetchMode().
Fix some PDO compatibility issues across all supported PHP versions.

Synthetic vs. proxy PDO statement

This initial work implements only a WP_PDO_Synthetic_Statement that requires the full PDO statement result set to be loaded in memory. This makes it easier to implement a gradual transition to the PDO API (the current driver loads all result sets in memory as well) and it can support all statement types, including those that are composed on the PHP side.

In a follow-up work, it should be possible to transition most statement types to a proxy-like PDO statement that would internally use PDO SQLite statements directly, without eagerly fetching all data. The proxy will be required to address incompatibilities between SQLite and MySQL statements.

Next steps

Subsequent PRs will focus on the following:

Implement more of the PDO and PDOStatement APIs.
Implement a WP_PDO_Proxy_Statement as described above.
Simplify the SQLite driver state to only store a "last result statement" instead of the current list of properties.
Use the PDO API directly and remove the temporary proxy to the "old" driver API.

Extracting smaller chunks from #291 so we can review and merge them independently. This PR includes the following changes: - Removed support for nested transactions. MySQL doesn't support them. - Implemented PDO-like APIs for start transaction, commit, and rollback. - The PDO-like APIs differ from an equivalent SQL command in that they always throw an exception in scenarios when a transaction was already started or not yet started (depending on the method), irrespective of the `ATTR_ERRMODE` setting. - Polyfill `PDO::inTransaction()` on PHP < 8.4, where it is not reliable ([issue](https://bugs.php.net/bug.php?id=81227), [PR](php/php-src#14268)).

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php

Extracting smaller chunks from #291 so we can review and merge them independently. This PR adds `Table` column to `SHOW CREATE TABLE` statements, [as per MySQL behavior](https://onecompiler.com/mysql/447x6gea7).

Extracting smaller chunks from #291 so we can review and merge them independently. This PR renames the current `WP_SQLite_Driver` to `WP_PDO_MySQL_On_SQLite` and reintroduces the `WP_SQLite_Driver` as a simple proxy over the new renamed class. It's done in these two steps (first rename, then reintroduce) so that Git understands the rename and presents history (hopefully) accurately. The changes are better understood in a commit-by-commit view. #### `WP_PDO_MySQL_On_SQLite` vs `WP_SQLite_Driver` The "reintroduced" `WP_SQLite_Driver` is not meant to be permanent. It is a temporary proxy so we can gradually modify `WP_PDO_MySQL_On_SQLite` to support PDO APIs while not touching the driver API just yet. Once the basics of PDO API are in place, we can make all dependencies use the new class directly and then remove the `WP_SQLite_Driver`. That is, in the future, the `WP_SQLite_DB extends wpdb` will use directly the new `WP_PDO_MySQL_On_SQLite` class.

wp-includes/sqlite-ast/class-wp-pdo-proxy-statement.php

adamziel · 2025-12-18T16:26:57Z

wp-includes/sqlite-ast/class-wp-pdo-synthetic-statement.php

This implies we're always loading the full result set into memory. Do we have to do that? I worry we could blow up memory on some large queries.

Do we have to do that?

@adamziel In most cases, fortunately not. But in some, when we construct the result in PHP (things like SHOW GRANTS, etc.), we need to have a "synthetic" statement that is implementing the PDO API on top of PHP arrays.

For all statements where a MySQL statement corresponds to an SQLite statement, it will be better to use a "proxy" statement. We can't use the SQLite statement directly because some things like column metadata formats differ, but we can use a proxy to avoid loading all results into memory. I actually have a class-wp-pdo-proxy-statement.php‎ in a WIP commit, but I'll probably extract it to a follow-up PR. Here's why I think it's fine:

In the first step, we can use the synthetic statement for everything because 1) the current driver already stores everything in memory ($this->last_result, etc.), and 2) $wpdb loads everything in memory as well. So I think I can complete this PR with the "synthetic" statement, and then in the next PR, I would replace all the $this->last_something props with a single $this->last_result_statement that we would use as the proxy target.

(things like SHOW GRANTS, etc.),

I don't suppose we would ever see a 100 megabyte result set in those so that seems fine.

In the first step, we can use the synthetic statement for everything because 1) the current driver already stores everything in memory ($this->last_result, etc.), and 2) $wpdb loads everything in memory as well. So I think I can complete this PR with the "synthetic" statement, and then in the next PR, I would replace all the $this->last_something props with a single $this->last_result_statement that we would use as the proxy target.

That sounds good. For Playground, the database is in memory anyway so it's not a big deal. It will matter when a larger site wants to adapt this driver, and perhaps we're reasonably close to having a technical ability to do it with all the MySQL queries we support. Not a huge priority, but it would be nice to briefly document in a docstring that yes, this is possible and here's what needs to happen technically.

Resolved in f7248a3, see also #291 (comment)

JanJakes · 2026-01-16T14:11:56Z

@adamziel I think this one is ready for a final round. In the end, it only needs a WP_PDO_Proxy_Statement that always wraps a real or a "dummy select" PDO SQLite statement.

I left many methods with throw new RuntimeException( 'Not implemented' );. This is on purpose—I know that just proxying to the underlying statement can implement most of them, but I want to add that with a test coverage and in a follow-up PR so that it's easier to review.

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

adamziel · 2026-01-17T00:41:29Z

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

+		$this->assertInstanceOf( PDO::class, $driver );
+	}
+
+	public function test_dsn_parsing(): void {


thank you for these tests!

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php

adamziel · 2026-01-17T00:52:52Z

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php

+
+		// Create a new SQLite connection.
+		if ( isset( $options['pdo'] ) ) {
+			$this->connection = new WP_SQLite_Connection( array( 'pdo' => $options['pdo'] ) );


Hm, so we can pass both the dsn and $options['pdo']? And the dsn is still validated and parsed in that case? Shouldn't we throw an error when both are passed here?

@adamziel This allows passing the underlying PDO SQLite instance, not the one we're parsing the options for.

While in theory, it can make some sense to support it (new WP_PDO_MySQL_On_SQLite( 'mysql-on-sqlite:dbname=test', [ 'pdo' => $my_pdo ] )), I'm not sure if we should keep it, and if we do, a better name for that option would probably make sense.

adamziel · 2026-01-17T00:57:16Z

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php

+			return $type;
+		};
+
+		if ( null === $fetch_mode ) {


Sooo, now that we delegate the logic to PDO, do we need to validate all of that here? Or could we also rely on PDO validation?

@adamziel Unfortunately, not here. We delegate the PDOStatement API to SQLite PDO, but not the PDO::query(), where we need more granular control over what queries and how many (if any) we execute.

adamziel · 2026-01-17T01:01:52Z

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php

+				 *
+				 * From MySQL documentation:
+				 *
+				 * In the absence of the SQL_CALC_FOUND_ROWS option in the most


I hope noone out there actually relies on that behavior, but some plugins probably do. Obligatory xkcd:

@adamziel True true 😬😂 I took a stab at it here: 3c8543b

I think that implementation does the > 99% case.

It's not 100%, because calling FOUND_ROWS() multiple times in a row will not necessarily give correct results. And then I also discovered this:

I also found this strange nuance:

But we never supported these edge cases anyway.

Oh wow. Good find!

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php

adamziel

I only have nitpicks. Really good work here, it's exciting to see how this is coming together. If you asked me a few years ago, I would have never guessed we'd be doing anything like this and yet here we are ❤️

Co-authored-by: Adam Zieliński <adam@adamziel.com>

JanJakes · 2026-01-19T15:35:42Z

@adamziel Thanks for the great review, as always. Another round should be ready now ✅

adamziel · 2026-01-19T17:37:21Z

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php

+			$this->quote_sqlite_identifier( $statistics_table ),
+			$this->connection->quote( $this->get_saved_db_name( $database ) ),


interesting, why do we need two quoting functions?

aha, one is for identifiers and another is for string values, and also this is no longer a prepared statement? Why ditch prepared statements here?

This would communicate the data flow right away:

$this->quote_sqlite_identifier( $statistics_table ), $this->quote_sqlite_value( $this->get_saved_db_name( $database ) );

JanJakes force-pushed the pdo-api branch 8 times, most recently from fd4cc59 to c02c987 Compare December 10, 2025 19:48

JanJakes force-pushed the pdo-api branch 9 times, most recently from 12df654 to 9e8e453 Compare December 17, 2025 12:54

This was referenced Dec 17, 2025

Improve transaction behavior compatibility, add PDO-like APIs #294

Merged

Fix missing table name column in SHOW CREATE TABLE statement #295

Merged

adamziel reviewed Dec 18, 2025

View reviewed changes

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php Show resolved Hide resolved

adamziel reviewed Dec 18, 2025

View reviewed changes

wp-includes/sqlite-ast/class-wp-pdo-mysql-on-sqlite.php Show resolved Hide resolved

JanJakes mentioned this pull request Dec 18, 2025

Bootstrap for PDO API implementation #297

Merged

JanJakes force-pushed the pdo-api branch 2 times, most recently from 5fe6619 to 4aadd4e Compare December 18, 2025 16:05

adamziel reviewed Dec 18, 2025

View reviewed changes

wp-includes/sqlite-ast/class-wp-pdo-proxy-statement.php Show resolved Hide resolved

adamziel reviewed Dec 18, 2025

View reviewed changes

JanJakes force-pushed the pdo-api branch from 4aadd4e to 5f4f9d7 Compare December 19, 2025 15:26

JanJakes force-pushed the pdo-api branch from 67a8782 to 3ce6a6c Compare January 16, 2026 12:52

Use SQLite query PDO statement as a proxy statement base when possible

f7248a3

JanJakes force-pushed the pdo-api branch from 3ce6a6c to f7248a3 Compare January 16, 2026 13:41

JanJakes requested a review from adamziel January 16, 2026 14:12