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)

…ling

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.

adamziel · 2026-01-17T00:40:49Z

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

 	public function setUp(): void {
-		$connection   = new WP_SQLite_Connection( array( 'path' => ':memory:' ) );
-		$this->driver = new WP_PDO_MySQL_On_SQLite( $connection, 'wp' );
+		$this->driver = new WP_PDO_MySQL_On_SQLite( 'mysql-on-sqlite:path=:memory:;dbname=wp;' );


I just realized PHP probably doesn't support paths such as ./mydb/one,two,three.sqlite (and so doesn't this implementation, which is absolutely fine).

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

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

+
+		// Run all tests with stringified fetch mode results, so we can use
+		// assertions that are consistent across all tested PHP versions.
+		// The "PDO::ATTR_STRINGIFY_FETCHES" mode is tested in separately.


nitpick

Suggested change

// The "PDO::ATTR_STRINGIFY_FETCHES" mode is tested in separately.

// The "PDO::ATTR_STRINGIFY_FETCHES" mode is tested separately.

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!

adamziel · 2026-01-17T00:42:48Z

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

+
+	public function test_query_fetch_default_mode_allow_any_args(): void {
+		if ( PHP_VERSION_ID < 80100 ) {
+			// On PHP < 8.1, fetch mode value of NULL is not allowed.


adamziel · 2026-01-17T00:43:44Z

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

+	}
+
+	public function test_exec(): void {
+		$result = $this->driver->exec( 'SELECT 1' );


It's really cool how easy to use this is becoming.

adamziel · 2026-01-17T00:46:30Z

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

+			 * TODO: Consider supporting non-string values on PHP < 8.1 when both
+			 *       "PDO::ATTR_STRINGIFY_FETCHES" and "PDO::ATTR_EMULATE_PREPARES"
+			 *       are set to "false". This would require emulating the behavior,
+			 *       as PDO SQLite on PHP < 8.1 seems to always return strings.


Would that be a real problem? It seems to only affect programs that perform this exact PHP_VERSION check to react differently to PDO outputs in different PHP versions.

adamziel · 2026-01-17T00:47:20Z

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

+		);
+	}
+
+	public function data_pdo_fetch_methods(): Generator {


oh! you can use a Generator as a data provider. This. Is. Amazing. Hey, @dmsnell @sirreal, I think Jan has found a solution to all our PHPCS problems in large data providers.

adamziel · 2026-01-17T00:48:23Z

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

+			throw new PDOException( 'could not find driver' );
+		}
+
+		// PDO DSN supports semicolon quoting using double semicolon sequences.


did you mean semicolon escaping?

adamziel · 2026-01-17T00:49:43Z

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

+		}
+
+		// PDO DSN supports semicolon quoting using double semicolon sequences.
+		// Replace ";;" with "\0" to preserve quoted semicolons in "explode()".


This would conflate double semicolons with legitimate \0-s in the data. Replacing explode with strspn/strcspn would take more effort but yield more reliable results in those corner cases.

Also, is ;;; treated as ;<end of data> or <end of data>;?

adamziel · 2026-01-17T00:51:15Z

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

+			// Restore quoted semicolons that were replaced with "\0".
+			$arg = str_replace( "\0", ';', $arg );
+
+			// PDO DSN allows whitespace before argument name.


any specific whitespace characters? do they overlap with what ltrim() removes, or do we need to list them all explicitly?

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 · 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 · 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 · 2026-01-17T01:02:41Z

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

+		 *     ...
+		 */
+
+		// Construct column header row ("SELECT <column-list> WHERE FALSE").


very clever!

adamziel · 2026-01-17T01:03:02Z

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

-		 * returns "0" (zero) with the SQLite driver at all times.
-		 * See: https://www.php.net/manual/en/pdostatement.rowcount.php
+		 * With 0 columns, we need to create a PDO statement that has no columns.
+		 * This can be done using a noop INSERT statement that modifies no data.


wow, clever

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 ❤️

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 added 8 commits January 16, 2026 13:33

Support whitespace in PDO DSN as per PHP PDO

caf76e8

Support semicolon quoting in PDO DSN

0859d00

Document PDO fetch modes

06f5681

Use PDO SQLite statement as a source for MySQL proxy statement

ba5b0ce

Fix test assertions for PDO::FETCH_NAMED

2d28a4e

Address differences between PDO on PHP < 8.1 and PDO on PHP >= 8.1

90f96ef

Add support for PDO::ATTR_DEFAULT_FETCH_MODE, simplify attribute hand…

717a3c8

…ling

Fix PDO compatibility issues with older PHP versions

5da4935

JanJakes force-pushed the pdo-api branch 2 times, most recently 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

adamziel reviewed Jan 17, 2026

View reviewed changes

adamziel approved these changes Jan 17, 2026

View reviewed changes

	// The "PDO::ATTR_STRINGIFY_FETCHES" mode is tested in separately.
	// The "PDO::ATTR_STRINGIFY_FETCHES" mode is tested separately.

PDO API foundations #291

Are you sure you want to change the base?

PDO API foundations #291

Conversation

JanJakes commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Synthetic vs. proxy PDO statement

Next steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JanJakes Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JanJakes commented Jan 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JanJakes commented Dec 5, 2025 •

edited

Loading

JanJakes Dec 18, 2025 •

edited

Loading

adamziel Jan 17, 2026 •

edited

Loading

adamziel Jan 17, 2026 •

edited

Loading

adamziel Jan 17, 2026 •

edited

Loading