Simplify the MySQL-on-SQLite driver API

.github/workflows/wp-tests-phpunit-native-extension-setup.sh

@@ -149,7 +149,7 @@ if ( ! ( $parser_ast instanceof WP_MySQL_Native_Parser_Node ) ) {
 	wp_sqlite_native_parser_verification_fail( 'Native parser did not produce a native-backed AST in the WordPress PHP test container.' );
 }
 
-$driver = new WP_PDO_MySQL_On_SQLite( 'mysql-on-sqlite:path=:memory:;dbname=wp;' );
+$driver = new WP_MySQL_On_SQLite( 'mysql-on-sqlite:path=:memory:;dbname=wp;' );
 $parser = $driver->create_parser( 'SELECT 1' );
 wp_sqlite_assert_native_parser_delegate( $parser, 'WordPress PHP test container SQLite driver did not create a native parser delegate.' );
 $parser->next_query();

packages/mysql-on-sqlite/src/load.php

@@ -41,5 +41,5 @@
 require_once __DIR__ . '/sqlite/class-wp-sqlite-information-schema-exception.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-information-schema-reconstructor.php';
 require_once __DIR__ . '/sqlite/class-wp-sqlite-pdo-user-defined-functions.php';
-require_once __DIR__ . '/sqlite/class-wp-pdo-mysql-on-sqlite.php';
+require_once __DIR__ . '/sqlite/class-wp-mysql-on-sqlite.php';
 require_once __DIR__ . '/sqlite/class-wp-pdo-proxy-statement.php';

packages/mysql-on-sqlite/src/sqlite/class-wp-pdo-mysql-on-sqlite.php → packages/mysql-on-sqlite/src/sqlite/class-wp-mysql-on-sqlite.php

@@ -14,7 +14,7 @@
  *
  * The driver requires PDO with the SQLite driver, and the PCRE engine.
  */
-class WP_PDO_MySQL_On_SQLite extends PDO {
+class WP_MySQL_On_SQLite extends PDO {
 	/**
 	 * The path to the MySQL SQL grammar file.
 	 */
@@ -632,8 +632,17 @@ class WP_PDO_MySQL_On_SQLite extends PDO {
 	 *
 	 * Set up an SQLite connection and the MySQL-on-SQLite driver.
 	 *
-	 * @param WP_SQLite_Connection $connection A SQLite database connection.
-	 * @param string               $db_name    The database name.
+	 * @param string      $dsn      MySQL-on-SQLite DSN containing the SQLite path and database name.
+	 * @param string|null $username Optional. Ignored by this driver.
+	 * @param string|null $password Optional. Ignored by this driver.
+	 * @param array       $options  {
+	 *     Optional driver options.
+	 *
+	 *     @type int             $mysql_version Optional. MySQL version to emulate. Default 80038.
+	 *     @type PDO|null        $pdo           Optional. Existing SQLite PDO connection.
+	 *     @type string|null     $journal_mode  Optional. SQLite journal mode. Default 'WAL'.
+	 *     @type string|int|null $synchronous   Optional. SQLite synchronous setting.
+	 * }
 	 *
 	 * @throws WP_SQLite_Driver_Exception When the driver initialization fails.
 	 */
@@ -789,11 +798,12 @@ function ( string $sql, array $params ) {
 	 *
 	 * A single MySQL query can be translated into zero or more SQLite queries.
 	 *
-	 * @param string $query              Full SQL statement string.
-	 * @param int    $fetch_mode         PDO fetch mode. Default is PDO::FETCH_OBJ.
-	 * @param array  ...$fetch_mode_args Additional fetch mode arguments.
+	 * @param string   $query              Full SQL statement string.
+	 * @param int|null $fetch_mode         Optional. PDO fetch mode. Defaults to the configured
+	 *                                     PDO::ATTR_DEFAULT_FETCH_MODE.
+	 * @param mixed    ...$fetch_mode_args Additional fetch mode arguments.
 	 *
-	 * @return mixed Return value, depending on the query type.
+	 * @return PDOStatement|false PDO statement, or false when the fetch mode is invalid on PHP < 8.1.
 	 *
 	 * @throws WP_SQLite_Driver_Exception When the query execution fails.
 	 */
@@ -1013,15 +1023,6 @@ public function beginTransaction(): bool {
 		return true;
 	}
 
-	/**
-	 * A temporary alias for back compatibility.
-	 *
-	 * @see self::beginTransaction()
-	 */
-	public function begin_transaction(): void {
-		$this->beginTransaction();
-	}
-
 	/**
 	 * PDO API: Commit a transaction.
 	 *
@@ -4211,7 +4212,7 @@ private function translate_query_expression( WP_Parser_Node $node ): string {
 		 * When the ORDER BY clause is present, we need to disambiguate the item
 		 * list and make sure they don't cause an "ambiguous column name" error.
 		 *
-		 * @see WP_SQLite_Driver::disambiguate_item()
+		 * @see WP_MySQL_On_SQLite::disambiguate_item()
 		 */
 		$disambiguated_order_list = array();
 		$order_clause             = $node->get_first_child_node( 'orderClause' );
@@ -4279,7 +4280,7 @@ private function translate_query_specification( WP_Parser_Node $node ): string {
 		 * When the GROUP BY or HAVING clause is present, we need to disambiguate
 		 * the items to ensure they don't cause an "ambiguous column name" error.
 		 *
-		 * @see WP_SQLite_Driver::disambiguate_item()
+		 * @see WP_MySQL_On_SQLite::disambiguate_item()
 		 */
 		$group_by_clause = null;
 		$having_clause   = null;
@@ -5788,7 +5789,7 @@ private function unnest_parenthesized_expression( WP_Parser_Node $node ): WP_Par
 	 *        consider column references in forms like "db.table.column".
 	 *
 	 * @param  array          $disambiguation_map The SELECT item disambiguation map (column name => array of select items).
-	 *                                            @see WP_SQLite_Driver::create_select_item_disambiguation_map()
+	 *                                            @see WP_MySQL_On_SQLite::create_select_item_disambiguation_map()
 	 * @param  WP_Parser_Node $expr               The expression AST node or subnode.
 	 * @return string|null                        The disambiguated and translated expression;
 	 *                                            null when the expression cannot be disambiguated.
@@ -5827,7 +5828,7 @@ private function disambiguate_item( array $disambiguation_map, WP_Parser_Node $e
 	 * Create a SELECT item disambiguation map from a SELECT item list for use
 	 * with the ORDER BY, GROUP BY, and HAVING clause disambiguation algorithm.
 	 *
-	 * @see WP_SQLite_Driver::disambiguate_item()
+	 * @see WP_MySQL_On_SQLite::disambiguate_item()
 	 *
 	 * @param  WP_Parser_Node $select_item_list The "selectItemList" AST node.
 	 * @return array                            The SELECT item disambiguation map (column name => array of select items).

packages/mysql-on-sqlite/src/sqlite/class-wp-sqlite-configurator.php

@@ -14,7 +14,7 @@ class WP_SQLite_Configurator {
 	/**
 	 * The SQLite driver instance.
 	 *
-	 * @var WP_PDO_MySQL_On_SQLite
+	 * @var WP_MySQL_On_SQLite
 	 */
 	private $driver;
 
@@ -35,11 +35,11 @@ class WP_SQLite_Configurator {
 	/**
 	 * Constructor.
 	 *
-	 * @param WP_PDO_MySQL_On_SQLite               $driver         The SQLite driver instance.
+	 * @param WP_MySQL_On_SQLite               $driver         The SQLite driver instance.
 	 * @param WP_SQLite_Information_Schema_Builder $schema_builder The information schema builder instance.
 	 */
 	public function __construct(
-		WP_PDO_MySQL_On_SQLite $driver,
+		WP_MySQL_On_SQLite $driver,
 		WP_SQLite_Information_Schema_Builder $schema_builder
 	) {
 		$this->driver               = $driver;
@@ -100,7 +100,7 @@ private function ensure_global_variables_table(): void {
 			sprintf(
 				'CREATE TABLE IF NOT EXISTS %s (name TEXT PRIMARY KEY, value TEXT)',
 				$this->driver->get_connection()->quote_identifier(
-					WP_PDO_MySQL_On_SQLite::GLOBAL_VARIABLES_TABLE_NAME
+					WP_MySQL_On_SQLite::GLOBAL_VARIABLES_TABLE_NAME
 				)
 			)
 		);
@@ -260,11 +260,11 @@ private function save_current_driver_version(): void {
 			sprintf(
 				'INSERT INTO %s (name, value) VALUES (?, ?) ON CONFLICT(name) DO UPDATE SET value = ?',
 				$this->driver->get_connection()->quote_identifier(
-					WP_PDO_MySQL_On_SQLite::GLOBAL_VARIABLES_TABLE_NAME
+					WP_MySQL_On_SQLite::GLOBAL_VARIABLES_TABLE_NAME
 				)
 			),
 			array(
-				WP_PDO_MySQL_On_SQLite::DRIVER_VERSION_VARIABLE_NAME,
+				WP_MySQL_On_SQLite::DRIVER_VERSION_VARIABLE_NAME,
 				SQLITE_DRIVER_VERSION,
 				SQLITE_DRIVER_VERSION,
 			)

packages/mysql-on-sqlite/src/sqlite/class-wp-sqlite-driver-exception.php

@@ -4,20 +4,20 @@ class WP_SQLite_Driver_Exception extends PDOException {
 	/**
 	 * The SQLite driver that originated the exception.
 	 *
-	 * @var WP_PDO_MySQL_On_SQLite
+	 * @var WP_MySQL_On_SQLite
 	 */
 	private $driver;
 
 	/**
 	 * Constructor.
 	 *
-	 * @param WP_PDO_MySQL_On_SQLite $driver The SQLite driver that originated the exception.
+	 * @param WP_MySQL_On_SQLite $driver The SQLite driver that originated the exception.
 	 * @param string                 $message  The exception message.
 	 * @param int|string             $code     The exception code. In PDO, it can be a string with value of SQLSTATE.
 	 * @param Throwable|null         $previous The previous throwable used for the exception chaining.
 	 */
 	public function __construct(
-		WP_PDO_MySQL_On_SQLite $driver,
+		WP_MySQL_On_SQLite $driver,
 		string $message,
 		$code = 0,
 		?Throwable $previous = null
@@ -27,7 +27,7 @@ public function __construct(
 		$this->driver = $driver;
 	}
 
-	public function getDriver(): WP_PDO_MySQL_On_SQLite {
+	public function getDriver(): WP_MySQL_On_SQLite {
 		return $this->driver;
 	}
 }

packages/mysql-on-sqlite/src/sqlite/class-wp-sqlite-driver.php

@@ -7,16 +7,16 @@
 
 /**
  * For back compatibility with dependencies that use their own loader scripts
- * (e.g., WP CLI SQLite Command), ensure the new PDO-based classes are loaded.
+ * (e.g., WP CLI SQLite Command), ensure the PDO-based classes are loaded.
  */
-require_once __DIR__ . '/class-wp-pdo-mysql-on-sqlite.php';
+require_once __DIR__ . '/class-wp-mysql-on-sqlite.php';
 require_once __DIR__ . '/class-wp-pdo-proxy-statement.php';
 
 /**
- * Deprecated: A proxy of the WP_PDO_MySQL_On_SQLite class preserving legacy API.
+ * Deprecated: A proxy of the WP_MySQL_On_SQLite class preserving the legacy API.
  *
- * This is a temporary class to preserve the legacy API for easier transition
- * to the new PDO-based API, developed in the "WP_PDO_MySQL_On_SQLite" class.
+ * This class temporarily preserves the legacy constructor and result API while
+ * consumers transition to the PDO-based WP_MySQL_On_SQLite API.
  */
 class WP_SQLite_Driver {
 	/**
@@ -38,7 +38,7 @@ class WP_SQLite_Driver {
 	/**
 	 * The MySQL-on-SQLite driver instance.
 	 *
-	 * @var WP_PDO_MySQL_On_SQLite
+	 * @var WP_MySQL_On_SQLite
 	 */
 	private $mysql_on_sqlite_driver;
 
@@ -64,7 +64,7 @@ public function __construct(
 		string $database,
 		int $mysql_version = 80038
 	) {
-		$this->mysql_on_sqlite_driver = new WP_PDO_MySQL_On_SQLite(
+		$this->mysql_on_sqlite_driver = new WP_MySQL_On_SQLite(
 			sprintf( 'mysql-on-sqlite:dbname=%s', $database ),
 			null,
 			null,
@@ -230,7 +230,7 @@ public function execute_sqlite_query( string $sql, array $params = array() ): PD
 	 * Begin a new transaction or nested transaction.
 	 */
 	public function beginTransaction(): void { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
-		$this->mysql_on_sqlite_driver->begin_transaction();
+		$this->mysql_on_sqlite_driver->beginTransaction();
 	}
 
 	/**

packages/mysql-on-sqlite/src/sqlite/class-wp-sqlite-information-schema-reconstructor.php

@@ -19,7 +19,7 @@ class WP_SQLite_Information_Schema_Reconstructor {
 	/**
 	 * The SQLite driver instance.
 	 *
-	 * @var WP_PDO_MySQL_On_SQLite
+	 * @var WP_MySQL_On_SQLite
 	 */
 	private $driver;
 
@@ -40,7 +40,7 @@ class WP_SQLite_Information_Schema_Reconstructor {
 	/**
 	 * Constructor.
 	 *
-	 * @param WP_PDO_MySQL_On_SQLite               $driver         The SQLite driver instance.
+	 * @param WP_MySQL_On_SQLite               $driver         The SQLite driver instance.
 	 * @param WP_SQLite_Information_Schema_Builder $schema_builder The information schema builder instance.
 	 */
 	public function __construct(
@@ -137,7 +137,7 @@ private function get_sqlite_table_names(): array {
 			array(
 				'_mysql_data_types_cache',
 				'sqlite\_%',
-				str_replace( '_', '\_', WP_PDO_MySQL_On_SQLite::RESERVED_PREFIX ) . '%',
+				str_replace( '_', '\_', WP_MySQL_On_SQLite::RESERVED_PREFIX ) . '%',
 			)
 		)->fetchAll( PDO::FETCH_COLUMN );
 	}
@@ -763,9 +763,9 @@ private function get_mysql_column_type( string $column_type ): string {
 	/**
 	 * Format a MySQL UTF-8 string literal for output in a CREATE TABLE statement.
 	 *
-	 * See WP_PDO_MySQL_On_SQLite::quote_mysql_utf8_string_literal().
+	 * See WP_MySQL_On_SQLite::quote_mysql_utf8_string_literal().
 	 *
-	 * TODO: This is a copy of WP_PDO_MySQL_On_SQLite::quote_mysql_utf8_string_literal().
+	 * TODO: This is a copy of WP_MySQL_On_SQLite::quote_mysql_utf8_string_literal().
 	 *       We may consider extracing it to reusable MySQL helpers.
 	 *
 	 * @param  string $utf8_literal The UTF-8 string literal to escape.

packages/mysql-on-sqlite/tests/WP_SQLite_Driver_Concurrency_Tests.php → packages/mysql-on-sqlite/tests/WP_MySQL_On_SQLite_Concurrency_Tests.php

@@ -5,7 +5,7 @@
 /**
  * Tests for concurrent access to the same SQLite database file.
  */
-class WP_SQLite_Driver_Concurrency_Tests extends TestCase {
+class WP_MySQL_On_SQLite_Concurrency_Tests extends TestCase {
 	/**
 	 * Path to the temporary SQLite database file used in file-based tests.
 	 *
@@ -109,7 +109,7 @@ public function testSetQueryOpensReadOnlyTransaction(): void {
 	public function testSetQuerySucceedsWhileAnotherConnectionHoldsWriteLock(): void {
 		// Connection A: set up the database and hold a write transaction.
 		$conn_a   = new WP_SQLite_Connection( array( 'path' => $this->db_path ) );
-		$driver_a = new WP_SQLite_Driver( $conn_a, 'wp' );
+		$driver_a = $this->create_driver( $conn_a );
 		$driver_a->query( 'CREATE TABLE t (id INT, name VARCHAR(255))' );
 		$driver_a->query( "INSERT INTO t VALUES (1, 'Alice')" );
 
@@ -124,13 +124,13 @@ public function testSetQuerySucceedsWhileAnotherConnectionHoldsWriteLock(): void
 					'timeout' => 0,
 				)
 			);
-			$driver_b = new WP_SQLite_Driver( $conn_b, 'wp' );
+			$driver_b = $this->create_driver( $conn_b );
 			$conn_b->get_pdo()->setAttribute( PDO::ATTR_TIMEOUT, 0 );
 
 			// SET writes nothing, so it must not contend for the write lock.
 			$result = $driver_b->query( "SET SESSION sql_mode = 'NO_ENGINE_SUBSTITUTION'" );
 
-			$this->assertSame( 0, $result );
+			$this->assertSame( 0, $result->rowCount() );
 		} finally {
 			$conn_a->get_pdo()->exec( 'ROLLBACK' );
 		}
@@ -139,7 +139,7 @@ public function testSetQuerySucceedsWhileAnotherConnectionHoldsWriteLock(): void
 	private function assertReadOnlyQuerySucceedsUnderWriteLock( string $query ): void {
 		// Connection A: set up the database.
 		$conn_a   = new WP_SQLite_Connection( array( 'path' => $this->db_path ) );
-		$driver_a = new WP_SQLite_Driver( $conn_a, 'wp' );
+		$driver_a = $this->create_driver( $conn_a );
 		$driver_a->query( 'CREATE TABLE t (id INT, name VARCHAR(255))' );
 		$driver_a->query( "INSERT INTO t VALUES (1, 'Alice')" );
 
@@ -154,22 +154,33 @@ private function assertReadOnlyQuerySucceedsUnderWriteLock( string $query ): voi
 					'timeout' => 0,
 				)
 			);
-			$driver_b = new WP_SQLite_Driver( $conn_b, 'wp' );
+			$driver_b = $this->create_driver( $conn_b );
 			$conn_b->get_pdo()->setAttribute( PDO::ATTR_TIMEOUT, 0 );
 
 			$result = $driver_b->query( $query );
 
-			$this->assertIsArray( $result );
-			$this->assertNotEmpty( $result );
+			$this->assertNotEmpty( $result->fetchAll() );
 		} finally {
 			$conn_a->get_pdo()->exec( 'ROLLBACK' );
 		}
 	}
 
-	private function create_in_memory_driver(): WP_SQLite_Driver {
+	private function create_in_memory_driver(): WP_MySQL_On_SQLite {
 		$pdo_class  = PHP_VERSION_ID >= 80400 ? PDO\SQLite::class : PDO::class;
 		$pdo        = new $pdo_class( 'sqlite::memory:' );
 		$connection = new WP_SQLite_Connection( array( 'pdo' => $pdo ) );
-		return new WP_SQLite_Driver( $connection, 'wp' );
+		return $this->create_driver( $connection );
+	}
+
+	private function create_driver( WP_SQLite_Connection $connection ): WP_MySQL_On_SQLite {
+		return new WP_MySQL_On_SQLite(
+			'mysql-on-sqlite:dbname=wp',
+			null,
+			null,
+			array(
+				'pdo'          => $connection->get_pdo(),
+				'journal_mode' => $connection->query( 'PRAGMA journal_mode' )->fetchColumn(),
+			)
+		);
 	}
 }