feat(console): add db:migrate CLI for idempotent core schema updates

Existing systems used to have no automatic mechanism for the db/updates/*.sql idempotent updates after `git pull` — devs had to remember which files were already applied and run new ones manually with `mariadb < ...`. Mirror module:migrate to fix this: - New `bin/console db:migrate` walks db/updates/*.sql in alphabetical order, skipping anything already recorded in the new core_migrations tracking table. Each file runs in its own transaction; failure rolls back so the file is retried on the next run. - New `db:migrate --status` lists applied vs. pending files without running anything. Useful for ops debugging "schema seems stale" symptoms. - module:sync now runs db:migrate as its first step, so the standard post-pull command stays a single invocation. README's 3-step setup is unchanged — module:sync now also covers core schema updates. CoreMigrationRepository owns its own mysqli connection (using the same DB credentials as MintyPHP\DB) and runs raw `$mysqli->query()` instead of going through DB::query's prepared statement path — MariaDB rejects some DDL (e.g. ALTER TABLE … ADD CONSTRAINT CHECK) in the prepared protocol, which the existing 18 db/updates files trip on. ModuleMigrationRepository is left untouched (no module migration uses such DDL today and changing the vendor pattern is out of scope). End-to-end verified: against an existing DB the first run applies all 19 idempotent files as no-ops and records them, second run reports "all updates already applied". Against a freshly init'd DB the same thing happens — no double work, no surprises. All encrypted seed secrets keep decrypting because APP_CRYPTO_KEY is unchanged. Tests: tests/Console/CoreCommandsTest covers success/failure/status output shapes against a FakeModuleRunner (mirror of the existing ModuleCommandsTest pattern). 5 stale baseline entries in phpstan-baseline removed (covered by the new @api annotation on the test fixture class). Docs: CLAUDE.md and docs/reference-cli-commands.md document the new command + --status flag; docs/howto-fehlerbehebung.md gains a "schema seems stale after git pull" section pointing at db:migrate --status. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-29 08:59:57 +02:00
parent 0c78dc4355
commit 2e73cb98b4
17 changed files with 651 additions and 37 deletions
--- a/core/Console/Commands/Database/MigrateCommand.php
+++ b/core/Console/Commands/Database/MigrateCommand.php
@@ -0,0 +1,90 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Database;
+
+use MintyPHP\Console\Commands\Module\AbstractModuleCommand;
+use MintyPHP\Console\Runner\Module\ModuleRunnerInterface;
+
+/**
+ * Apply pending core SQL migrations from db/updates/.
+ *
+ * Mirror of `module:migrate` for core schema changes. Each `db/updates/*.sql`
+ * file MUST be idempotent; applied filenames are tracked in `core_migrations`.
+ *
+ * `--status` prints applied/pending lists without running anything.
+ */
+final class MigrateCommand extends AbstractModuleCommand
+{
+    public function __construct(?ModuleRunnerInterface $moduleRunner = null)
+    {
+        parent::__construct($moduleRunner);
+    }
+
+    public function name(): string
+    {
+        return 'db:migrate';
+    }
+
+    public function description(): string
+    {
+        return 'Apply pending core SQL migrations from db/updates/';
+    }
+
+    public function usage(): string
+    {
+        return <<<'USAGE'
+        Usage: php bin/console db:migrate [--status]
+
+        Options:
+          --status    Print applied / pending migration filenames without running anything
+
+        Each file under db/updates/*.sql is applied at most once and tracked in
+        the core_migrations table. Files MUST be idempotent (e.g. CREATE TABLE
+        IF NOT EXISTS, INSERT … ON DUPLICATE KEY UPDATE) so first-run on an
+        existing schema is a no-op.
+
+        `bin/console module:sync` runs db:migrate as its first step.
+        USAGE;
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        if (!empty($options['status'])) {
+            $status = $this->moduleRunner()->dbMigrateStatus();
+
+            $appliedCount = count($status['applied']);
+            $pendingCount = count($status['pending']);
+
+            echo sprintf("db-migrate-status: %d applied, %d pending\n\n", $appliedCount, $pendingCount);
+
+            echo "applied:\n";
+            if ($appliedCount === 0) {
+                echo "  (none)\n";
+            } else {
+                foreach ($status['applied'] as $filename) {
+                    echo '  ' . $filename . PHP_EOL;
+                }
+            }
+
+            echo "\npending:\n";
+            if ($pendingCount === 0) {
+                echo "  (none)\n";
+            } else {
+                foreach ($status['pending'] as $filename) {
+                    echo '  ' . $filename . PHP_EOL;
+                }
+            }
+
+            return 0;
+        }
+
+        $result = $this->moduleRunner()->dbMigrate();
+        if ($result['exit_code'] === 0) {
+            echo $result['message'] . PHP_EOL;
+        } else {
+            fwrite(STDERR, $result['message'] . PHP_EOL);
+        }
+
+        return (int) $result['exit_code'];
+    }
+}