feature: implement DevMigrator closes #283

composer.json

@@ -51,7 +51,6 @@
 
 	"scripts": {
 		"phpunit": "vendor/bin/phpunit --configuration phpunit.xml",
-		"phpunit:coverage": "XDEBUG_MODE=coverage vendor/bin/phpunit --configuration phpunit.xml --coverage-text",
 		"phpstan": "vendor/bin/phpstan analyse --level 6 --memory-limit 1G src",
 		"phpcs": "vendor/bin/phpcs src --standard=phpcs.xml",
 		"phpmd": "vendor/bin/phpmd src/ text phpmd.xml",

src/Cli/ExecuteCommand.php

@@ -4,8 +4,10 @@
 use Gt\Cli\Argument\ArgumentValueList;
 use Gt\Cli\Command\Command;
 use Gt\Cli\Parameter\Parameter;
+use Gt\Config\Config;
 use Gt\Config\ConfigFactory;
 use Gt\Database\Connection\Settings;
+use Gt\Database\Migration\DevMigrator;
 use Gt\Database\Migration\MigrationIntegrityException;
 use Gt\Database\Migration\Migrator;
 use Gt\Database\StatementExecutionException;
@@ -19,6 +21,7 @@ public function run(?ArgumentValueList $arguments = null):void {
 
 		$settings = $this->buildSettingsFromConfig($config, $repoBasePath, $arguments);
 		[$migrationPath, $migrationTable] = $this->getMigrationLocation($config, $repoBasePath, $arguments);
+		[$devMigrationPath, $devMigrationTable] = $this->getDevMigrationLocation($config, $repoBasePath, $arguments);
 
 		$migrator = new Migrator($settings, $migrationPath, $migrationTable);
 		$migrator->setOutput(
@@ -38,16 +41,33 @@ public function run(?ArgumentValueList $arguments = null):void {
 		$runFrom = $this->calculateResetNumber($arguments, $migrationFileList, $migrator, $migrationCount);
 
 		$this->executeMigrations($migrator, $migrationFileList, $runFrom);
+
+		if($this->isDevMerge($arguments)) {
+			$this->mergeDevMigrations($settings, $migrator, $migrationPath, $devMigrationPath, $devMigrationTable);
+			return;
+		}
+
+		if($this->isDev($arguments)) {
+			$this->executeDevMigrations($settings, $devMigrationPath, $devMigrationTable);
+		}
 	}
 
 	/** Determine whether the --force flag was provided. */
 	private function isForced(?ArgumentValueList $arguments):bool {
 		return $arguments?->contains("force") ?? false;
 	}
 
+	private function isDev(?ArgumentValueList $arguments):bool {
+		return $arguments?->contains("dev") ?? false;
+	}
+
+	private function isDevMerge(?ArgumentValueList $arguments):bool {
+		return $arguments?->contains("dev-merge") ?? false;
+	}
+
 	/** Build Settings from config for the current repository. */
 	protected function buildSettingsFromConfig(
-		\Gt\Config\Config $config,
+		Config $config,
 		string $repoBasePath,
 		?ArgumentValueList $arguments = null
 	): Settings {
@@ -110,7 +130,7 @@ protected function buildSettingsFromConfig(
 	 * @return list<string>
 	 */
 	protected function getMigrationLocation(
-		\Gt\Config\Config $config,
+		Config $config,
 		string $repoBasePath,
 		?ArgumentValueList $arguments = null
 	): array {
@@ -129,6 +149,34 @@ protected function getMigrationLocation(
 		return [$migrationPath, $migrationTable];
 	}
 
+	/**
+	 * Return [devMigrationPath, devMigrationTable] derived from config.
+	 *
+	 * @return list<string>
+	 */
+	protected function getDevMigrationLocation(
+		Config $config,
+		string $repoBasePath,
+		?ArgumentValueList $arguments = null
+	): array {
+		$queryPath = $this->getOverrideOrConfigValue(
+			$config,
+			$arguments,
+			"base-directory",
+			"database.query_path",
+			"query"
+		);
+		$devMigrationPath = implode(DIRECTORY_SEPARATOR, [
+			$this->resolvePath($repoBasePath, $queryPath),
+			$config->get("database.dev_migration_path") ?? implode(DIRECTORY_SEPARATOR, [
+				"_migration",
+				"dev",
+			]),
+		]);
+		$devMigrationTable = $config->get("database.dev_migration_table") ?? "_migration_dev";
+		return [$devMigrationPath, $devMigrationTable];
+	}
+
 	/**
 	 * Calculate the migration start point from --reset or current migration count.
 	 *
@@ -158,7 +206,11 @@ private function calculateResetNumber(
 	 *
 	 * @param list<string> $migrationFileList
 	 */
-	private function executeMigrations(Migrator $migrator, array $migrationFileList, int $runFrom): void {
+	private function executeMigrations(
+		Migrator $migrator,
+		array $migrationFileList,
+		int $runFrom,
+	): void {
 		try {
 			$migrator->checkIntegrity($migrationFileList, $runFrom);
 			$migrator->performMigration($migrationFileList, $runFrom);
@@ -180,6 +232,72 @@ private function executeMigrations(Migrator $migrator, array $migrationFileList,
 		}
 	}
 
+	private function executeDevMigrations(
+		Settings $settings,
+		string $devMigrationPath,
+		string $devMigrationTable
+	): void {
+		$devMigrator = new DevMigrator(
+			$settings,
+			$devMigrationPath,
+			$devMigrationTable,
+		);
+		$devMigrator->setOutput(
+			$this->stream->getOutStream(),
+			$this->stream->getErrorStream()
+		);
+
+		$devMigrator->createMigrationTable();
+		$devMigrationFileList = $devMigrator->getMigrationFileList();
+
+		try {
+			$devMigrator->checkFileListOrder($devMigrationFileList);
+			$devMigrator->checkIntegrity($devMigrationFileList);
+			$devMigrator->performMigration($devMigrationFileList);
+		}
+		catch(MigrationIntegrityException $exception) {
+			$this->writeLine(
+				"There was an integrity error migrating dev file '"
+				. $exception->getMessage()
+				. "' - this dev migration is recorded to have been run already, "
+				. "but the contents of the file has changed."
+			);
+		}
+		catch(StatementPreparationException|StatementExecutionException $exception) {
+			$this->writeLine(
+				"There was an error executing dev migration file: "
+				. $exception->getMessage()
+				. "'"
+			);
+		}
+	}
+
+	private function mergeDevMigrations(
+		Settings $settings,
+		Migrator $migrator,
+		string $migrationPath,
+		string $devMigrationPath,
+		string $devMigrationTable
+	): void {
+		$devMigrator = new DevMigrator($settings, $devMigrationPath, $devMigrationTable);
+		$devMigrator->setOutput(
+			$this->stream->getOutStream(),
+			$this->stream->getErrorStream()
+		);
+		$devMigrator->createMigrationTable();
+
+		try {
+			$devMigrator->mergeIntoMainMigrationDirectory($migrator, $migrationPath);
+		}
+		catch(MigrationIntegrityException $exception) {
+			$this->writeLine(
+				"There was an integrity error merging dev migration file '"
+				. $exception->getMessage()
+				. "' - ensure the dev migration has already been run and not edited since."
+			);
+		}
+	}
+
 	public function getName():string {
 		return "execute";
 	}
@@ -244,6 +362,18 @@ public function getOptionalParameterList():array {
 				null,
 				"Override database.password for this command"
 			),
+			new Parameter(
+				false,
+				"dev",
+				null,
+				"Run branch-local migrations from the dev migration directory"
+			),
+			new Parameter(
+				false,
+				"dev-merge",
+				null,
+				"Promote branch-local dev migrations into canonical migrations"
+			),
 			new Parameter(
 				false,
 				"force",
@@ -280,9 +410,9 @@ private function getDefaultPath(string $repoBasePath):?string {
 	/**
 	 * @param bool|string $repoBasePath
 	 * @param string|null $defaultPath
-	 * @return \Gt\Config\Config
+	 * @return Config
 	 */
-	protected function getConfig(bool|string $repoBasePath, ?string $defaultPath):\Gt\Config\Config {
+	protected function getConfig(bool|string $repoBasePath, ?string $defaultPath):Config {
 		$config = ConfigFactory::createForProject($repoBasePath);
 
 		$default = $defaultPath
@@ -296,7 +426,7 @@ protected function getConfig(bool|string $repoBasePath, ?string $defaultPath):\G
 	}
 
 	protected function getOverrideOrConfigValue(
-		\Gt\Config\Config $config,
+		Config $config,
 		?ArgumentValueList $arguments,
 		string $argumentKey,
 		string $configKey,

src/Migration/AbstractMigrator.php

@@ -0,0 +1,135 @@
+<?php
+namespace Gt\Database\Migration;
+
+use Gt\Database\Connection\Settings;
+use Gt\Database\Database;
+use SplFileInfo;
+use SplFileObject;
+
+abstract class AbstractMigrator {
+	const string STREAM_OUT = "out";
+	const string STREAM_ERROR = "error";
+
+	protected ?SplFileObject $streamError = null;
+	protected ?SplFileObject $streamOut = null;
+
+	protected string $driver;
+	protected Database $dbClient;
+	protected string $path;
+	protected string $tableName;
+	protected Settings $settings;
+
+	public function __construct(
+		Settings $settings,
+		string $path,
+		?string $tableName = null
+	) {
+		$this->settings = clone $settings;
+		$this->driver = $settings->getDriver();
+		$this->path = $path;
+		$this->tableName = $tableName ?? $this->getDefaultTableName();
+
+		if($this->driver !== Settings::DRIVER_SQLITE) {
+			$settings = $settings->withoutSchema();
+		}
+
+		$this->dbClient = new Database($settings);
+	}
+
+	abstract protected function getDefaultTableName():string;
+
+	public function setOutput(
+		SplFileObject $out,
+		?SplFileObject $error = null
+	):void {
+		$this->streamOut = $out;
+		$this->streamError = $error;
+	}
+
+	/** @return array<string> */
+	public function getMigrationFileList():array {
+		if(!is_dir($this->path)) {
+			return [];
+		}
+
+		$fileList = glob("$this->path/*.sql");
+		$fileList = array_values(array_filter($fileList, function(string $file):bool {
+			return preg_match("/^\d+.*\.sql$/", basename($file)) === 1;
+		}));
+		sort($fileList);
+		return $fileList;
+	}
+
+	/** @param array<string> $fileList */
+	public function checkFileListOrder(array $fileList):void {
+		$previousNumber = null;
+
+		foreach($fileList as $file) {
+			$migrationNumber = $this->extractNumberFromFilename($file);
+
+			if(!is_null($previousNumber)) {
+				if($migrationNumber === $previousNumber) {
+					throw new MigrationSequenceOrderException("Duplicate: $migrationNumber");
+				}
+				if($migrationNumber < $previousNumber) {
+					throw new MigrationSequenceOrderException("Out of order: $migrationNumber before $previousNumber");
+				}
+				if($migrationNumber !== $previousNumber + 1) {
+					throw new MigrationSequenceOrderException("Gap: $previousNumber before $migrationNumber");
+				}
+			}
+			elseif($migrationNumber !== 1) {
+				throw new MigrationSequenceOrderException("Gap: expected 1, got $migrationNumber");
+			}
+
+			$previousNumber = $migrationNumber;
+		}
+	}
+
+	public function extractNumberFromFilename(string $pathName):int {
+		$file = new SplFileInfo($pathName);
+		$filename = $file->getFilename();
+		preg_match("/^(\d+)-?.*\.sql$/", $filename, $matches);
+
+		if(!isset($matches[1])) {
+			throw new MigrationFileNameFormatException($filename);
+		}
+
+		return (int)$matches[1];
+	}
+
+	protected function executeSqlFile(string $file):string {
+		$md5 = md5_file($file);
+		$sqlStatementSplitter = new SqlStatementSplitter();
+
+		foreach($sqlStatementSplitter->split(file_get_contents($file)) as $sql) {
+			$this->dbClient->executeSql($sql);
+		}
+
+		return $md5;
+	}
+
+	protected function nowExpression():string {
+		if($this->driver === Settings::DRIVER_SQLITE) {
+			return "datetime('now')";
+		}
+
+		return "now()";
+	}
+
+	protected function output(
+		string $message,
+		string $streamName = self::STREAM_OUT
+	):void {
+		$stream = $this->streamOut ?? null;
+		if($streamName === self::STREAM_ERROR) {
+			$stream = $this->streamError;
+		}
+
+		if(is_null($stream)) {
+			return;
+		}
+
+		$stream->fwrite($message . PHP_EOL);
+	}
+}