Extract SQLite connection management to WP_SQLite_Connection

Author: JanJakes

tests/WP_SQLite_Driver_Metadata_Tests.php

@@ -31,10 +31,8 @@ public static function setUpBeforeClass(): void {
 	public function setUp(): void {
 		$this->sqlite = new PDO( 'sqlite::memory:' );
 		$this->engine = new WP_SQLite_Driver(
-			array(
-				'connection' => $this->sqlite,
-				'database'   => 'wp',
-			)
+			new WP_SQLite_Connection( array( 'pdo' => $this->sqlite ) ),
+			'wp'
 		);
 	}
 

tests/WP_SQLite_Driver_Query_Tests.php

@@ -43,10 +43,8 @@ public function setUp(): void {
 
 		$this->sqlite = new PDO( 'sqlite::memory:' );
 		$this->engine = new WP_SQLite_Driver(
-			array(
-				'connection' => $this->sqlite,
-				'database'   => 'wp',
-			)
+			new WP_SQLite_Connection( array( 'pdo' => $this->sqlite ) ),
+			'wp'
 		);
 
 		$translator = $this->engine;
@@ -458,7 +456,7 @@ public function testRecoverSerialized() {
 		);
 		$option_name          = 'serialized_option';
 		$option_value         = serialize( $obj );
-		$option_value_escaped = $this->engine->get_pdo()->quote( $option_value );
+		$option_value_escaped = $this->engine->get_connection()->quote( $option_value );
 		/* Note well: this is heredoc not nowdoc */
 		$insert = <<<QUERY
 		INSERT INTO `wp_options` (`option_name`, `option_value`, `autoload`)
@@ -484,7 +482,7 @@ public function testRecoverSerialized() {
 		++$obj ['two'];
 		$obj ['pi']          *= 2;
 		$option_value         = serialize( $obj );
-		$option_value_escaped = $this->engine->get_pdo()->quote( $option_value );
+		$option_value_escaped = $this->engine->get_connection()->quote( $option_value );
 		/* Note well: this is heredoc not nowdoc */
 		$insert = <<<QUERY
 		INSERT INTO `wp_options` (`option_name`, `option_value`, `autoload`)

tests/WP_SQLite_Driver_Tests.php

@@ -32,10 +32,8 @@ public function setUp(): void {
 		$this->sqlite = new PDO( 'sqlite::memory:' );
 
 		$this->engine = new WP_SQLite_Driver(
-			array(
-				'connection' => $this->sqlite,
-				'database'   => 'wp',
-			)
+			new WP_SQLite_Connection( array( 'pdo' => $this->sqlite ) ),
+			'wp'
 		);
 		$this->engine->query(
 			"CREATE TABLE _options (

tests/WP_SQLite_Driver_Translation_Tests.php

@@ -57,16 +57,14 @@ function wp_get_db_schema() {
 	public function setUp(): void {
 		$this->sqlite = new PDO( 'sqlite::memory:' );
 		$this->engine = new WP_SQLite_Driver(
-			array(
-				'connection' => $this->sqlite,
-				'database'   => 'wp',
-			)
+			new WP_SQLite_Connection( array( 'pdo' => $this->sqlite ) ),
+			'wp'
 		);
 
 		$builder = new WP_SQLite_Information_Schema_Builder(
 			'wp',
 			WP_SQLite_Driver::RESERVED_PREFIX,
-			array( $this->engine, 'execute_sqlite_query' )
+			$this->engine->get_connection()
 		);
 
 		$this->reconstructor = new WP_SQLite_Information_Schema_Reconstructor(
@@ -76,7 +74,7 @@ public function setUp(): void {
 	}
 
 	public function testReconstructTable(): void {
-		$this->engine->get_pdo()->exec(
+		$this->engine->get_connection()->query(
 			'
 			CREATE TABLE t (
 			  id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -90,8 +88,8 @@ public function testReconstructTable(): void {
 			)
 		'
 		);
-		$this->engine->get_pdo()->exec( 'CREATE INDEX idx_score ON t (score)' );
-		$this->engine->get_pdo()->exec( 'CREATE INDEX idx_role_score ON t (role, priority)' );
+		$this->engine->get_connection()->query( 'CREATE INDEX idx_score ON t (score)' );
+		$this->engine->get_connection()->query( 'CREATE INDEX idx_role_score ON t (role, priority)' );
 		$result = $this->assertQuery( 'SELECT * FROM information_schema.tables WHERE table_name = "t"' );
 		$this->assertEquals( 0, count( $result ) );
 
@@ -126,7 +124,7 @@ public function testReconstructTable(): void {
 
 	public function testReconstructWpTable(): void {
 		// Create a WP table with any columns.
-		$this->engine->get_pdo()->exec( 'CREATE TABLE wp_posts ( id INTEGER )' );
+		$this->engine->get_connection()->query( 'CREATE TABLE wp_posts ( id INTEGER )' );
 
 		// Reconstruct the information schema.
 		$this->reconstructor->ensure_correct_information_schema();
@@ -176,18 +174,18 @@ public function testReconstructWpTable(): void {
 	}
 
 	public function testReconstructTableFromMysqlDataTypesCache(): void {
-		$pdo = $this->engine->get_pdo();
+		$connection = $this->engine->get_connection();
 
-		$pdo->exec( self::CREATE_DATA_TYPES_CACHE_TABLE_SQL );
-		$pdo->exec( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'id', 'int unsigned')" );
-		$pdo->exec( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'name', 'varchar(255)')" );
-		$pdo->exec( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'description', 'text')" );
-		$pdo->exec( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'shape', 'geomcollection')" );
-		$pdo->exec( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 't__idx_name', 'KEY')" );
-		$pdo->exec( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 't__idx_description', 'FULLTEXT')" );
-		$pdo->exec( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 't__idx_shape', 'SPATIAL')" );
+		$connection->query( self::CREATE_DATA_TYPES_CACHE_TABLE_SQL );
+		$connection->query( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'id', 'int unsigned')" );
+		$connection->query( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'name', 'varchar(255)')" );
+		$connection->query( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'description', 'text')" );
+		$connection->query( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 'shape', 'geomcollection')" );
+		$connection->query( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 't__idx_name', 'KEY')" );
+		$connection->query( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 't__idx_description', 'FULLTEXT')" );
+		$connection->query( "INSERT INTO _mysql_data_types_cache (`table`, column_or_index, mysql_type) VALUES ('t', 't__idx_shape', 'SPATIAL')" );
 
-		$this->engine->get_pdo()->exec(
+		$connection->query(
 			'
 			CREATE TABLE t (
 				id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -197,9 +195,9 @@ public function testReconstructTableFromMysqlDataTypesCache(): void {
 			)
 		'
 		);
-		$this->engine->get_pdo()->exec( 'CREATE INDEX t__idx_name ON t (name)' );
-		$this->engine->get_pdo()->exec( 'CREATE INDEX t__idx_description ON t (description)' );
-		$this->engine->get_pdo()->exec( 'CREATE INDEX t__idx_shape ON t (shape)' );
+		$connection->query( 'CREATE INDEX t__idx_name ON t (name)' );
+		$connection->query( 'CREATE INDEX t__idx_description ON t (description)' );
+		$connection->query( 'CREATE INDEX t__idx_shape ON t (shape)' );
 
 		$this->reconstructor->ensure_correct_information_schema();
 		$result = $this->assertQuery( 'SHOW CREATE TABLE t' );
@@ -224,7 +222,7 @@ public function testReconstructTableFromMysqlDataTypesCache(): void {
 	}
 
 	public function testDefaultValues(): void {
-		$this->engine->get_pdo()->exec(
+		$this->engine->get_connection()->query(
 			"
 			CREATE TABLE t (
 				col1 text DEFAULT abc,

tests/WP_SQLite_Information_Schema_Reconstructor_Tests.php

@@ -14,6 +14,7 @@
 require_once __DIR__ . '/../wp-includes/sqlite/class-wp-sqlite-token.php';
 require_once __DIR__ . '/../wp-includes/sqlite/class-wp-sqlite-pdo-user-defined-functions.php';
 require_once __DIR__ . '/../wp-includes/sqlite/class-wp-sqlite-translator.php';
+require_once __DIR__ . '/../wp-includes/sqlite-ast/class-wp-sqlite-connection.php';
 require_once __DIR__ . '/../wp-includes/sqlite-ast/class-wp-sqlite-configurator.php';
 require_once __DIR__ . '/../wp-includes/sqlite-ast/class-wp-sqlite-driver.php';
 require_once __DIR__ . '/../wp-includes/sqlite-ast/class-wp-sqlite-driver-exception.php';

tests/bootstrap.php

@@ -8,17 +8,16 @@
 require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-token.php';
 require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-parser.php';
 require_once __DIR__ . '/../../wp-includes/sqlite/class-wp-sqlite-pdo-user-defined-functions.php';
+require_once __DIR__ . '/../../wp-includes/sqlite-ast/class-wp-sqlite-connection.php';
 require_once __DIR__ . '/../../wp-includes/sqlite-ast/class-wp-sqlite-configurator.php';
 require_once __DIR__ . '/../../wp-includes/sqlite-ast/class-wp-sqlite-driver.php';
 require_once __DIR__ . '/../../wp-includes/sqlite-ast/class-wp-sqlite-driver-exception.php';
 require_once __DIR__ . '/../../wp-includes/sqlite-ast/class-wp-sqlite-information-schema-builder.php';
 require_once __DIR__ . '/../../wp-includes/sqlite-ast/class-wp-sqlite-information-schema-reconstructor.php';
 
 $driver = new WP_SQLite_Driver(
-	array(
-		'path'     => ':memory:',
-		'database' => 'wp',
-	)
+	new WP_SQLite_Connection( array( 'path' => ':memory:' ) ),
+	'wp'
 );
 
 $query = "SELECT * FROM t1 LEFT JOIN t2 ON t1.id = t2.t1_id WHERE t1.name = 'abc'";

tests/tools/dump-sqlite-query.php

@@ -0,0 +1,157 @@
+<?php declare(strict_types = 1);
+
+/*
+ * The SQLite connection uses PDO. Enable PDO function calls:
+ * phpcs:disable WordPress.DB.RestrictedClasses.mysql__PDO
+ */
+
+/**
+ * SQLite connection.
+ *
+ * This class configures and encapsulates the connection to an SQLite database.
+ * It requires PDO with the SQLite driver, and currently, it is only a simple
+ * wrapper that leaks some of the PDO APIs (returns PDOStatement values, etc.).
+ * In the future, we may abstract it away from PDO and support SQLite3 as well.
+ */
+class WP_SQLite_Connection {
+	/**
+	 * The default timeout in seconds for SQLite to wait for a writable lock.
+	 */
+	const DEFAULT_SQLITE_TIMEOUT = 10;
+
+	/**
+	 * The supported SQLite journal modes.
+	 *
+	 * See: https://www.sqlite.org/pragma.html#pragma_journal_mode
+	 */
+	const SQLITE_JOURNAL_MODES = array(
+		'DELETE',
+		'TRUNCATE',
+		'PERSIST',
+		'MEMORY',
+		'WAL',
+		'OFF',
+	);
+
+	/**
+	 * The PDO connection for SQLite.
+	 *
+	 * @var PDO
+	 */
+	private $pdo;
+
+	/**
+	 * A query logger callback.
+	 *
+	 * @var callable(string, array): void
+	 */
+	private $query_logger;
+
+	/**
+	 * Constructor.
+	 *
+	 * Set up an SQLite connection.
+	 *
+	 * @param array $options {
+	 *     An array of options.
+	 *
+	 *     @type string|null $path         Optional. SQLite database path.
+	 *                                     For in-memory database, use ':memory:'.
+	 *                                     Must be set when PDO instance is not provided.
+	 *     @type PDO|null    $pdo          Optional. PDO instance with SQLite connection.
+	 *                                     If not provided, a new PDO instance will be created.
+	 *     @type int|null    $timeout      Optional. SQLite timeout in seconds.
+	 *                                     The time to wait for a writable lock.
+	 *     @type string|null $journal_mode Optional. SQLite journal mode.
+	 * }
+	 *
+	 * @throws InvalidArgumentException When some connection options are invalid.
+	 * @throws PDOException             When the driver initialization fails.
+	 */
+	public function __construct( array $options ) {
+		// Setup PDO connection.
+		if ( isset( $options['pdo'] ) && $options['pdo'] instanceof PDO ) {
+			$this->pdo = $options['pdo'];
+		} else {
+			if ( ! isset( $options['path'] ) || ! is_string( $options['path'] ) ) {
+				throw new InvalidArgumentException( 'Option "path" is required when "connection" is not provided.' );
+			}
+			$this->pdo = new PDO( 'sqlite:' . $options['path'] );
+		}
+
+		// Throw exceptions on error.
+		$this->pdo->setAttribute( PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION );
+
+		// Configure SQLite timeout.
+		if ( isset( $options['timeout'] ) && is_int( $options['timeout'] ) ) {
+			$timeout = $options['timeout'];
+		} else {
+			$timeout = self::DEFAULT_SQLITE_TIMEOUT;
+		}
+		$this->pdo->setAttribute( PDO::ATTR_TIMEOUT, $timeout );
+
+		// Return all values (except null) as strings.
+		$this->pdo->setAttribute( PDO::ATTR_STRINGIFY_FETCHES, true );
+
+		// Configure SQLite journal mode.
+		$journal_mode = $options['journal_mode'] ?? null;
+		if ( $journal_mode && in_array( $journal_mode, self::SQLITE_JOURNAL_MODES, true ) ) {
+			$this->query( 'PRAGMA journal_mode = ' . $journal_mode );
+		}
+	}
+
+	/**
+	 * Execute a query in SQLite.
+	 *
+	 * @param  string $sql   The query to execute.
+	 * @param  array $params The query parameters.
+	 * @throws PDOException  When the query execution fails.
+	 * @return PDOStatement  The PDO statement object.
+	 */
+	public function query( string $sql, array $params = array() ): PDOStatement {
+		if ( $this->query_logger ) {
+			( $this->query_logger )( $sql, $params );
+		}
+		$stmt = $this->pdo->prepare( $sql );
+		$stmt->execute( $params );
+		return $stmt;
+	}
+
+	/**
+	 * Returns the ID of the last inserted row.
+	 *
+	 * @return string The ID of the last inserted row.
+	 */
+	public function get_last_insert_id(): string {
+		return $this->pdo->lastInsertId();
+	}
+
+	/**
+	 * Quote a value for use in a query.
+	 *
+	 * @param  mixed  $value The value to quote.
+	 * @param  int    $type  The type of the value.
+	 * @return string        The quoted value.
+	 */
+	public function quote( $value, int $type = PDO::PARAM_STR ): string {
+		return $this->pdo->quote( $value, $type );
+	}
+
+	/**
+	 * Get the PDO object.
+	 *
+	 * @return PDO
+	 */
+	public function get_pdo(): PDO {
+		return $this->pdo;
+	}
+
+	/**
+	 * Set a logger for the queries.
+	 *
+	 * @param callable(string, array): void $logger A query logger callback.
+	 */
+	public function set_query_logger( callable $logger ): void {
+		$this->query_logger = $logger;
+	}
+}