Implement a database configurator service for DB initialization and migration

JanJakes · JanJakes · commit 6a641f970419 · 2025-04-15T16:19:42.000+02:00
diff --git a/load.php b/load.php
@@ -12,6 +12,7 @@
  * @package wp-sqlite-integration
  */
 
+define( 'SQLITE_DRIVER_VERSION', '2.1.17-alpha' );
 define( 'SQLITE_MAIN_FILE', __FILE__ );
 
 require_once __DIR__ . '/php-polyfills.php';
diff --git a/tests/WP_SQLite_Driver_Metadata_Tests.php b/tests/WP_SQLite_Driver_Metadata_Tests.php
@@ -1,5 +1,6 @@
 <?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';
diff --git a/tests/WP_SQLite_Driver_Query_Tests.php b/tests/WP_SQLite_Driver_Query_Tests.php
@@ -1,5 +1,6 @@
 <?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';
diff --git a/tests/WP_SQLite_Driver_Tests.php b/tests/WP_SQLite_Driver_Tests.php
@@ -1,6 +1,7 @@
 <?php
 
 require_once __DIR__ . '/WP_SQLite_Translator_Tests.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';
diff --git a/tests/WP_SQLite_Driver_Translation_Tests.php b/tests/WP_SQLite_Driver_Translation_Tests.php
@@ -1,5 +1,6 @@
 <?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';
diff --git a/tests/bootstrap.php b/tests/bootstrap.php
@@ -14,6 +14,12 @@
 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';
 
+/*
+ * The driver version needs to be defined and set to anything other than "0.0.0"
+ * for the tests, so that the information schema and other tables are created.
+ */
+define( 'SQLITE_DRIVER_VERSION', '2.0.0-tests' );
+
 /**
  * Polyfills for WordPress functions
  */
diff --git a/tests/tools/dump-sqlite-query.php b/tests/tools/dump-sqlite-query.php
@@ -8,6 +8,7 @@
 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-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';
diff --git a/wp-includes/sqlite-ast/class-wp-sqlite-configurator.php b/wp-includes/sqlite-ast/class-wp-sqlite-configurator.php
@@ -0,0 +1,103 @@
+<?php
+
+/**
+ * SQLite database configurator.
+ *
+ * This class initializes and configures the SQLite database, so that it can be
+ * used by the SQLite driver to translate and emulate MySQL queries in SQLite.
+ *
+ * The configurator ensures that tables required for emulating MySQL behaviors
+ * are created and populated with necessary data. It is also able to partially
+ * repair and update these tables and metadata in case of database corruption.
+ */
+class WP_SQLite_Configurator {
+	/**
+	 * The SQLite driver instance.
+	 *
+	 * @var WP_SQLite_Driver
+	 */
+	private $driver;
+
+	/**
+	 * A service for managing MySQL INFORMATION_SCHEMA tables in SQLite.
+	 *
+	 * @var WP_SQLite_Information_Schema_Builder
+	 */
+	private $information_schema_builder;
+
+	/**
+	 * Constructor.
+	 *
+	 * @param WP_SQLite_Driver                     $driver                     The SQLite driver instance.
+	 * @param WP_SQLite_Information_Schema_Builder $information_schema_builder The information schema builder instance.
+	 */
+	public function __construct(
+		WP_SQLite_Driver $driver,
+		WP_SQLite_Information_Schema_Builder $information_schema_builder
+	) {
+		$this->driver                     = $driver;
+		$this->information_schema_builder = $information_schema_builder;
+	}
+
+	/**
+	 * Ensure that the SQLite database is configured.
+	 *
+	 * This method checks if the database is configured for the latest SQLite
+	 * driver version, and if it is not, it will configure the database.
+	 */
+	public function ensure_database_configured(): void {
+		$version    = SQLITE_DRIVER_VERSION;
+		$db_version = $this->driver->get_saved_driver_version();
+		if ( version_compare( $version, $db_version ) > 0 ) {
+			$this->configure_database();
+		}
+	}
+
+	/**
+	 * Configure the SQLite database.
+	 *
+	 * This method creates tables used for emulating MySQL behaviors in SQLite,
+	 * and populates them with necessary data. When it is used with an already
+	 * configured database, it will update the configuration as per the current
+	 * SQLite driver version and attempt to repair any configuration corruption.
+	 */
+	public function configure_database(): void {
+		$this->ensure_global_variables_table();
+		$this->information_schema_builder->ensure_information_schema_tables();
+		$this->save_current_driver_version();
+	}
+
+	/**
+	 * Ensure that the global variables table exists.
+	 *
+	 * This method configures a database table to store MySQL global variables
+	 * and other internal configuration values.
+	 */
+	private function ensure_global_variables_table(): void {
+		$this->driver->execute_sqlite_query(
+			sprintf(
+				'CREATE TABLE IF NOT EXISTS %s (name TEXT PRIMARY KEY, value TEXT)',
+				WP_SQLite_Driver::GLOBAL_VARIABLES_TABLE_NAME
+			)
+		);
+	}
+
+	/**
+	 * Save the current SQLite driver version.
+	 *
+	 * This method saves the current SQLite driver version to the database.
+	 */
+	private function save_current_driver_version(): void {
+		$this->driver->execute_sqlite_query(
+			sprintf(
+				'INSERT INTO %s (name, value) VALUES (?, ?) ON CONFLICT(name) DO UPDATE SET value = ?',
+				WP_SQLite_Driver::GLOBAL_VARIABLES_TABLE_NAME
+			),
+			array(
+				WP_SQLite_Driver::DRIVER_VERSION_VARIABLE_NAME,
+				SQLITE_DRIVER_VERSION,
+				SQLITE_DRIVER_VERSION,
+			)
+		);
+	}
+}
diff --git a/wp-includes/sqlite-ast/class-wp-sqlite-driver.php b/wp-includes/sqlite-ast/class-wp-sqlite-driver.php
@@ -40,6 +40,22 @@ class WP_SQLite_Driver {
 	 */
 	const RESERVED_PREFIX = '_wp_sqlite_';
 
+	/**
+	 * The name of a global variables table.
+	 *
+	 * This special table is used to emulate MySQL global variables and to store
+	 * some internal configuration values.
+	 */
+	const GLOBAL_VARIABLES_TABLE_NAME = self::RESERVED_PREFIX . 'global_variables';
+
+	/**
+	 * The name of the SQLite driver version variable.
+	 *
+	 * This internal variable is used to store the latest version of the SQLite
+	 * driver that was used to initialize and configure the SQLite database.
+	 */
+	const DRIVER_VERSION_VARIABLE_NAME = self::RESERVED_PREFIX . 'driver_version';
+
 	/**
 	 * A map of MySQL tokens to SQLite data types.
 	 *
@@ -524,7 +540,10 @@ public function __construct( array $options ) {
 			self::RESERVED_PREFIX,
 			array( $this, 'execute_sqlite_query' )
 		);
-		$this->information_schema_builder->ensure_information_schema_tables();
+
+		// Ensure that the database is configured.
+		$migrator = new WP_SQLite_Configurator( $this, $this->information_schema_builder );
+		$migrator->ensure_database_configured();
 	}
 
 	/**
@@ -545,6 +564,31 @@ public function get_sqlite_version(): string {
 		return $this->pdo->query( 'SELECT SQLITE_VERSION()' )->fetchColumn();
 	}
 
+	/**
+	 * Get the SQLite driver version saved in the database.
+	 *
+	 * The saved driver version corresponds to the latest version of the SQLite
+	 * driver that was used to initialize and configure the SQLite database.
+	 *
+	 * @return string       SQLite driver version as a string.
+	 * @throws PDOException When the query execution fails.
+	 */
+	public function get_saved_driver_version(): string {
+		$default_version = '0.0.0';
+		try {
+			$stmt = $this->execute_sqlite_query(
+				sprintf( 'SELECT value FROM %s WHERE name = ?', self::GLOBAL_VARIABLES_TABLE_NAME ),
+				array( self::DRIVER_VERSION_VARIABLE_NAME )
+			);
+			return $stmt->fetchColumn() ?? $default_version;
+		} catch ( PDOException $e ) {
+			if ( str_contains( $e->getMessage(), 'no such table' ) ) {
+				return $default_version;
+			}
+			throw $e;
+		}
+	}
+
 	/**
 	 * Check if a specific SQL mode is active.
 	 *
diff --git a/wp-includes/sqlite/class-wp-sqlite-db.php b/wp-includes/sqlite/class-wp-sqlite-db.php
@@ -300,6 +300,7 @@ public function db_connect( $allow_bail = true ) {
 			require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-token.php';
 			require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-lexer.php';
 			require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-parser.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';
