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)).

adamziel · 2025-12-18T10:48:01Z

tests/WP_PDO_MySQL_On_SQLite_PDO_API_Tests.php

+	}
+
+	public function test_connection(): void {
+		$driver = new WP_PDO_MySQL_On_SQLite( 'mysql-on-sqlite:path=:memory:;dbname=WordPress;' );


nice ❤️

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.

adamziel · 2025-12-18T16:25:58Z

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

+ */
+
+/**
+ * Some PDOStatement methods are not compatible across different PHP versions.


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

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

+	) {
+		$this->pdo                = $pdo;
+		$this->sqlite_column_meta = $sqlite_column_metadata;
+		$this->rows               = $rows;


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.

…Statement

…h modes

JanJakes · 2025-12-20T08:50:23Z

@adamziel I rebased this on all the extracted changes, and made the changeset a bit clearer and easier to understand. More details in the updated PR description.

adamziel · 2025-12-20T11:16:43Z

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

+	 * @var array<int, mixed>
+	 */
+	private $pdo_attributes = array(
+		PDO::ATTR_STRINGIFY_FETCHES => PHP_VERSION_ID < 80100 ? true : false,


let's document the rationale behind this condition

adamziel · 2025-12-20T12:00:30Z

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

+		}
+
+		$args = array();
+		foreach ( explode( ';', $dsn_parts[1] ) as $arg ) {


let's scrutinize this and make double sure we're doing it in the same way as php-src does, e.g. I wonder if mysql:dbname=testdb; host=127.0.0.1 with an extra space is also a correct dsn.

adamziel · 2025-12-20T12:01:55Z

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

+			$args[ $arg_parts[0] ] = $arg_parts[1] ?? null;
+		}
+
+		$path    = $args['path'] ?? ':memory:';


We're exploding by :, so for a DSN such as new PDO('mysql-on-sqlite::memory:') we'll get an empty string as $dsn_parts[1]. Let's add a thorough test suite for parsing the DSN string, it's such a small part that's so important to get right.

adamziel · 2025-12-20T12:46:28Z

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

+			$arg_colno = $fetch_mode_args[0];
+		} elseif ( PDO::FETCH_CLASS === $fetch_mode ) {
+			if ( $arg_count < 3 ) {
+				throw new ArgumentCountError(


pdo_stmt.c doesn't seem to check the number of args for this mode – would it tolerate more? Or is it either 3 or 4 args still?

adamziel · 2025-12-20T12:47:47Z

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

+			}
+			$arg_class            = $fetch_mode_args[0];
+			$arg_constructor_args = $fetch_mode_args[1] ?? array();
+		} elseif ( PDO::FETCH_INTO === $fetch_mode ) {


I've stumbled upon this weird comment in pdo_stmt.c:

default: /* No support for PDO_FETCH_INTO which takes 2 args??? */

I'm not sure if we need to do anything with it. Does PHP actually support FETCH_INTO? 😅

adamziel · 2025-12-20T12:49:59Z

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

+			// arguments are ignored, and the argument count is not validated.
+			$fetch_mode = PDO::FETCH_BOTH;
+		} elseif ( PDO::FETCH_COLUMN === $fetch_mode ) {
+			if ( 3 !== $arg_count ) {


Is it 3 because of the extra query arg at the beginning? I've noticed fetchAll() expects up to 2:

if (ZEND_NUM_ARGS() > 2) { zend_string *func = get_active_function_or_method_name(); zend_argument_count_error("%s() expects at most 2 argument for the fetch mode provided, %d given", ZSTR_VAL(func), ZEND_NUM_ARGS()); zend_string_release(func); RETURN_THROWS(); }

adamziel · 2025-12-20T12:51:40Z

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

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


There's also PDO::FETCH_DEFAULT that pdo_stmt.c seems to rely on

Also PDO::FETCH_KEY_PAIR. Let's identify all of those and at least document the unsupported ones (and throw an explicit error when they're used). Ditto for flags.

adamziel · 2025-12-20T12:55:01Z

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

+	 */
+	#[ReturnTypeWillChange]
+	public function fetch(
+		$mode = 0, // PDO::FETCH_DEFAULT (available from PHP 8.0)


Ah, that's why we don't use that constant by name in the other file. Maybe we can refer to our own set of constants that's always consistently defined across all PHP versions? That way we won't need to wonder whether a specific 0 has a special constant-related meaning.

adamziel · 2025-12-20T12:57:00Z

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

+		if ( null === $cursorOrientation ) {
+			$cursorOrientation = PDO::FETCH_ORI_NEXT;
+		}
+		if ( null === $cursorOffset ) {


This will only be null if someone explicitly overrides the default 0 value. It would read slightly more natural if the signature said $cursorOffset = null and then we'd correct nulls to 0s here. I suppose we can't do that because of the parent method signature?

adamziel · 2025-12-20T12:59:13Z

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

+		 */
+
+		/**
+		 * With PHP < 8.1, the "PDO::ATTR_STRINGIFY_FETCHES" value of "false"


Great find!

adamziel · 2025-12-20T12:59:36Z

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

+			case PDO::FETCH_CLASS:
+				throw new RuntimeException( "'PDO::FETCH_CLASS' mode is not supported" );
+			case PDO::FETCH_INTO:
+				throw new RuntimeException( "'PDO::FETCH_INTO' mode is not supported" );


Ah, there we go throwing for unsupported modes. That takes care of my other comment.

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

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

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 5f4f9d7 to 99bd716 Compare December 19, 2025 15:28

JanJakes added 8 commits December 19, 2025 16:54

Make WP_PDO_MySQL_On_SQLite extend PDO, add a dummy WP_PDO_Synthetic_…

2d1522c

…Statement

Implement PDO::exec() API

be0828b

Implement and use PDOStatement fetch() and fetchAll() with basic fetc…

93e7c37

…h modes

Implement PDO and PDOStatement getAttribute() and setAttribute()

3bfefa8

Use the PHP default for PDO::ATTR_STRINGIFY_FETCHES

631a572

Add a fix for PDO::ATTR_STRINGIFY_FETCHES=false with PHP < 8.1

e6780f3

Implement PDOStatement::setFetchMode()

90fc34f

Respect PDO::query() fetch mode arguments

4b0869d

JanJakes force-pushed the pdo-api branch from 99bd716 to 4b0869d Compare December 19, 2025 15:55

JanJakes changed the title ~~WIP PDO API~~ PDO API foundations Dec 20, 2025

JanJakes marked this pull request as ready for review December 20, 2025 08:45

JanJakes requested a review from adamziel December 20, 2025 08:49

adamziel reviewed Dec 20, 2025

View reviewed changes

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

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

Uh oh!

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 Dec 20, 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JanJakes commented Dec 5, 2025 •

edited

Loading

JanJakes Dec 18, 2025 •

edited

Loading

JanJakes commented Dec 20, 2025 •

edited

Loading

adamziel Dec 20, 2025 •

edited

Loading