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>

core/App/Container/Registrars/AppServicesRegistrar.php

@@ -17,6 +17,8 @@ use MintyPHP\Http\RequestRuntimeInterface;
 use MintyPHP\Http\SessionStore;
 use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Access\PermissionRepository;
+use MintyPHP\Repository\Database\CoreMigrationRepository;
+use MintyPHP\Repository\Database\CoreMigrationRepositoryInterface;
 use MintyPHP\Repository\Module\ModuleMigrationRepository;
 use MintyPHP\Repository\Search\SearchQueryRepository;
 use MintyPHP\Repository\Stats\AdminStatsRepository;
@@ -27,6 +29,7 @@ use MintyPHP\Service\CustomField\CustomFieldServicesFactory;
 use MintyPHP\Service\CustomField\TenantCustomFieldService;
 use MintyPHP\Service\CustomField\UserCustomFieldValueService;
 use MintyPHP\Service\Data\GridUserCountEnricher;
+use MintyPHP\Service\Database\CoreMigrationService;
 use MintyPHP\Service\Import\ImportService;
 use MintyPHP\Service\Import\ImportServicesFactory;
 use MintyPHP\Service\Mail\MailLogService;
@@ -84,6 +87,12 @@ final class AppServicesRegistrar implements ContainerRegistrar
             $c->get(ModuleRegistry::class),
             $c->get(ModuleMigrationRepository::class)
         ));
+        $container->set(CoreMigrationRepository::class, static fn (): CoreMigrationRepository => new CoreMigrationRepository());
+        $container->set(CoreMigrationRepositoryInterface::class, static fn (AppContainer $c): CoreMigrationRepositoryInterface => $c->get(CoreMigrationRepository::class));
+        $container->set(CoreMigrationService::class, fn (AppContainer $c): CoreMigrationService => new CoreMigrationService(
+            $c->get(CoreMigrationRepositoryInterface::class),
+            $projectRoot . '/db/updates'
+        ));
         $container->set(ModulePermissionSynchronizer::class, fn (AppContainer $c): ModulePermissionSynchronizer => new ModulePermissionSynchronizer(
             $c->get(ModuleRegistry::class),
             $c->get(PermissionRepository::class),

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'];
+    }
+}

core/Console/Runner/Module/ModuleRunner.php

@@ -11,11 +11,73 @@ use MintyPHP\App\Module\ModulePermissionSynchronizer;
 use MintyPHP\App\Module\ModuleRegistry;
 use MintyPHP\App\Module\ModuleRuntimeAssetPublisher;
 use MintyPHP\App\Module\ModuleRuntimePageBuilder;
+use MintyPHP\Console\Support\CliAppBootstrap;
 use MintyPHP\Console\Support\ModuleCliRuntime;
+use MintyPHP\Service\Database\CoreMigrationService;
 use MintyPHP\Service\Module\ModuleMigrationService;
 
 final class ModuleRunner implements ModuleRunnerInterface
 {
+    public function dbMigrate(): array
+    {
+        $summary = ['applied' => 0, 'skipped_empty' => 0, 'total_files' => 0, 'applied_filenames' => []];
+        $message = 'db-migrate: all updates already applied.';
+        $step = ModuleCliRuntime::runStep('db-migrate', function () use (&$summary, &$message): int {
+            $lockResult = ModuleCliRuntime::withFileLock(
+                ModuleCliRuntime::projectRoot() . '/storage/runtime/.db-migrate.lock',
+                'db-migrate: another migration run is in progress, skipping.',
+                function () use (&$summary, &$message): int {
+                    /** @var CoreMigrationService $service */
+                    $service = app(CoreMigrationService::class);
+                    $result = $service->applyPendingMigrations();
+                    $summary = $result;
+
+                    if ($result['total_files'] === 0) {
+                        $message = 'db-migrate: no update files in db/updates/, nothing to do.';
+                    } elseif ($result['applied'] === 0) {
+                        $message = 'db-migrate: all updates already applied.';
+                    } else {
+                        $message = sprintf('db-migrate: applied %d migration(s).', $result['applied']);
+                    }
+
+                    if ($result['skipped_empty'] > 0) {
+                        $message .= sprintf(' (%d empty file(s) skipped)', $result['skipped_empty']);
+                    }
+
+                    return $result['ok'] ? 0 : 1;
+                }
+            );
+
+            if ($lockResult['busy']) {
+                $message = (string) $lockResult['message'];
+            }
+
+            return $lockResult['exit_code'];
+        });
+
+        return [
+            'command' => 'db:migrate',
+            'status' => $step['status'],
+            'exit_code' => $step['exit_code'],
+            'vendor_warnings_ignored' => $step['vendor_warnings_ignored'],
+            'message' => $step['error'] ?? $message,
+        ];
+    }
+
+    public function dbMigrateStatus(): array
+    {
+        CliAppBootstrap::bootstrap('cli', 'bin/console db:migrate --status');
+        /** @var CoreMigrationService $service */
+        $service = app(CoreMigrationService::class);
+        $status = $service->status();
+
+        return [
+            'command' => 'db:migrate --status',
+            'applied' => $status['applied'],
+            'pending' => $status['pending'],
+        ];
+    }
+
     public function migrate(): array
     {
         $summary = ['applied' => 0, 'modules_enabled' => 0, 'skipped_empty' => 0];
@@ -287,6 +349,7 @@ final class ModuleRunner implements ModuleRunnerInterface
     {
         $startedAt = microtime(true);
         $steps = [
+            'db-migrate' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
             'migrate' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
             'permissions-sync' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
             'build' => ['status' => 'pending', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
@@ -300,6 +363,7 @@ final class ModuleRunner implements ModuleRunnerInterface
                 'module-runtime-sync: another runtime sync is in progress, skipping.',
                 function () use (&$steps): int {
                     $orderedSteps = [
+                        'db-migrate' => fn (): array => $this->dbMigrate(),
                         'migrate' => fn (): array => $this->migrate(),
                         'permissions-sync' => fn (): array => $this->permissionsSync(),
                         'build' => fn (): array => $this->build(),
@@ -332,7 +396,8 @@ final class ModuleRunner implements ModuleRunnerInterface
 
         if ($message === '') {
             $message = sprintf(
-                'module-runtime-sync: summary migrate=%s permissions-sync=%s build=%s assets-sync=%s vendor_warnings_ignored=%d',
+                'module-runtime-sync: summary db-migrate=%s migrate=%s permissions-sync=%s build=%s assets-sync=%s vendor_warnings_ignored=%d',
+                $steps['db-migrate']['status'],
                 $steps['migrate']['status'],
                 $steps['permissions-sync']['status'],
                 $steps['build']['status'],

core/Console/Runner/Module/ModuleRunnerInterface.php

@@ -6,6 +6,16 @@ namespace MintyPHP\Console\Runner\Module;
 
 interface ModuleRunnerInterface
 {
+    /**
+     * @return array{command: string, status: string, exit_code: int, vendor_warnings_ignored: int, message: string}
+     */
+    public function dbMigrate(): array;
+
+    /**
+     * @return array{command: string, applied: list<string>, pending: list<string>}
+     */
+    public function dbMigrateStatus(): array;
+
     /**
      * @return array{command: string, status: string, exit_code: int, vendor_warnings_ignored: int, message: string}
      */
@@ -77,6 +87,9 @@ interface ModuleRunnerInterface
      *   steps: array<string, array{status: string, exit_code: int, vendor_warnings_ignored: int}>,
      *   message: string
      * }
+     *
+     * The `steps` map is keyed in execution order:
+     * `db-migrate`, `migrate`, `permissions-sync`, `build`, `assets-sync`.
      */
     public function runtimeSync(): array;
 }

core/Repository/Database/CoreMigrationRepository.php

@@ -0,0 +1,127 @@
+<?php
+
+namespace MintyPHP\Repository\Database;
+
+use MintyPHP\DB;
+use MintyPHP\DBError;
+use mysqli;
+
+/**
+ * Manages the core_migrations tracking table and applies raw SQL statements.
+ *
+ * Owns its own mysqli connection (using the same credentials as MintyPHP\DB)
+ * so we can run statements via mysqli->query() — bypassing prepared statements,
+ * which MariaDB rejects for some DDL (e.g. ALTER TABLE … ADD CONSTRAINT CHECK).
+ *
+ * All SQL for core migration tracking lives here (strict layering).
+ */
+final class CoreMigrationRepository implements CoreMigrationRepositoryInterface
+{
+    private ?mysqli $mysqli = null;
+
+    public function ensureTrackingTable(): void
+    {
+        $this->executeStatement(
+            'CREATE TABLE IF NOT EXISTS `core_migrations` (
+                `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
+                `filename` VARCHAR(255) NOT NULL,
+                `applied_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (`id`),
+                UNIQUE KEY `uq_core_migration` (`filename`)
+            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci'
+        );
+    }
+
+    /**
+     * @return array<string, true> Filenames already applied, keyed by filename
+     */
+    public function getAppliedFilenames(): array
+    {
+        $applied = [];
+        $result = $this->connection()->query('SELECT filename FROM core_migrations');
+        if ($result === false) {
+            throw new DBError('Failed to query core_migrations: ' . $this->connection()->error);
+        }
+        while (($row = $result->fetch_assoc()) !== null) {
+            $filename = trim((string) ($row['filename'] ?? ''));
+            if ($filename !== '') {
+                $applied[$filename] = true;
+            }
+        }
+        $result->free();
+        return $applied;
+    }
+
+    public function recordApplied(string $filename): void
+    {
+        $stmt = $this->connection()->prepare('INSERT INTO core_migrations (filename) VALUES (?)');
+        if ($stmt === false) {
+            throw new DBError('Failed to prepare INSERT into core_migrations: ' . $this->connection()->error);
+        }
+        $stmt->bind_param('s', $filename);
+        $stmt->execute();
+        if ($stmt->errno !== 0) {
+            $error = $stmt->error;
+            $stmt->close();
+            throw new DBError('Failed to insert into core_migrations: ' . $error);
+        }
+        $stmt->close();
+    }
+
+    public function beginTransaction(): void
+    {
+        $this->executeStatement('START TRANSACTION');
+    }
+
+    public function commit(): void
+    {
+        $this->executeStatement('COMMIT');
+    }
+
+    public function rollback(): void
+    {
+        $this->executeStatement('ROLLBACK');
+    }
+
+    public function executeStatement(string $sql): void
+    {
+        $mysqli = $this->connection();
+        $result = $mysqli->query($sql);
+        if ($result === false) {
+            throw new DBError($mysqli->error);
+        }
+        // For SELECT-style results, free the result set so the connection
+        // doesn't get stuck in "commands out of sync" state.
+        if ($result instanceof \mysqli_result) {
+            $result->free();
+        }
+    }
+
+    private function connection(): mysqli
+    {
+        if ($this->mysqli instanceof mysqli) {
+            return $this->mysqli;
+        }
+
+        // Reuse the MintyPHP\DB connection settings (public statics) so we
+        // hit the same database the rest of the app uses, but with our own
+        // socket — the vendor DB class always uses prepared statements,
+        // which MariaDB rejects for some DDL.
+        $args = array_filter(
+            [DB::$host, DB::$username, DB::$password, DB::$database, DB::$port, DB::$socket],
+            static fn ($v): bool => $v !== null
+        );
+
+        $reflect = new \ReflectionClass(mysqli::class);
+        $mysqli = $reflect->newInstanceArgs($args);
+        if ($mysqli->connect_errno !== 0) {
+            throw new DBError('Failed to connect to database for core migrations: ' . $mysqli->connect_error);
+        }
+        if (!$mysqli->set_charset('utf8mb4')) {
+            throw new DBError('Failed to set charset for core migrations connection: ' . $mysqli->error);
+        }
+
+        $this->mysqli = $mysqli;
+        return $mysqli;
+    }
+}

core/Repository/Database/CoreMigrationRepositoryInterface.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace MintyPHP\Repository\Database;
+
+/** Contract for core migration tracking: table creation, applied-file queries, and statement execution. */
+interface CoreMigrationRepositoryInterface
+{
+    public function ensureTrackingTable(): void;
+
+    /**
+     * @return array<string, true>
+     */
+    public function getAppliedFilenames(): array;
+
+    public function recordApplied(string $filename): void;
+
+    public function beginTransaction(): void;
+
+    public function commit(): void;
+
+    public function rollback(): void;
+
+    public function executeStatement(string $sql): void;
+}

core/Service/Database/CoreMigrationService.php

@@ -0,0 +1,130 @@
+<?php
+
+namespace MintyPHP\Service\Database;
+
+use MintyPHP\Repository\Database\CoreMigrationRepositoryInterface;
+use MintyPHP\Support\SqlStatementParser;
+use RuntimeException;
+
+/**
+ * Discovers and applies pending SQL migrations from db/updates/*.sql.
+ *
+ * Mirror of ModuleMigrationService for core schema changes. Each file MUST be
+ * idempotent (CLAUDE.md / GR-CORE-010); applied filenames are tracked in
+ * core_migrations so subsequent runs only apply genuinely new files.
+ *
+ * Orchestration only — SQL lives in CoreMigrationRepository,
+ * statement parsing in SqlStatementParser.
+ */
+final class CoreMigrationService
+{
+    public function __construct(
+        private readonly CoreMigrationRepositoryInterface $repository,
+        private readonly string $updatesPath,
+    ) {
+    }
+
+    /**
+     * Apply all pending core migrations.
+     *
+     * @return array{ok: bool, applied: int, skipped_empty: int, total_files: int, applied_filenames: list<string>}
+     */
+    public function applyPendingMigrations(): array
+    {
+        $this->repository->ensureTrackingTable();
+
+        $files = $this->discoverFiles();
+        $applied = $this->repository->getAppliedFilenames();
+
+        $totalApplied = 0;
+        $skippedEmpty = 0;
+        $appliedFilenames = [];
+
+        foreach ($files as $file) {
+            $filename = basename($file);
+            if (isset($applied[$filename])) {
+                continue;
+            }
+
+            $sql = file_get_contents($file);
+            if ($sql === false || trim($sql) === '') {
+                $skippedEmpty++;
+                continue;
+            }
+
+            $this->repository->beginTransaction();
+            try {
+                $statements = SqlStatementParser::splitStatements($sql);
+                foreach ($statements as $statement) {
+                    $this->repository->executeStatement($statement);
+                }
+
+                $this->repository->recordApplied($filename);
+                $this->repository->commit();
+            } catch (\Throwable $migrationError) {
+                $this->repository->rollback();
+                throw new RuntimeException(
+                    sprintf("Core migration %s failed: %s", $filename, $migrationError->getMessage()),
+                    0,
+                    $migrationError
+                );
+            }
+
+            $totalApplied++;
+            $appliedFilenames[] = $filename;
+        }
+
+        return [
+            'ok' => true,
+            'applied' => $totalApplied,
+            'skipped_empty' => $skippedEmpty,
+            'total_files' => count($files),
+            'applied_filenames' => $appliedFilenames,
+        ];
+    }
+
+    /**
+     * Inspect applied vs. pending migrations without running anything.
+     *
+     * @return array{applied: list<string>, pending: list<string>}
+     */
+    public function status(): array
+    {
+        $this->repository->ensureTrackingTable();
+
+        $files = $this->discoverFiles();
+        $appliedMap = $this->repository->getAppliedFilenames();
+
+        $applied = [];
+        $pending = [];
+        foreach ($files as $file) {
+            $filename = basename($file);
+            if (isset($appliedMap[$filename])) {
+                $applied[] = $filename;
+            } else {
+                $pending[] = $filename;
+            }
+        }
+
+        sort($applied);
+        sort($pending);
+
+        return ['applied' => $applied, 'pending' => $pending];
+    }
+
+    /**
+     * @return list<string> Absolute paths of `*.sql` files in updates dir, sorted alphabetically.
+     */
+    private function discoverFiles(): array
+    {
+        if (!is_dir($this->updatesPath)) {
+            return [];
+        }
+        $files = glob($this->updatesPath . '/*.sql');
+        if ($files === false || count($files) === 0) {
+            return [];
+        }
+        sort($files);
+        return $files;
+    }
+}