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>

CLAUDE.md

@@ -37,7 +37,9 @@ docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
 
 # CLI commands (single entry point)
 docker compose exec php php bin/console list
-docker compose exec php php bin/console module:sync              # full module runtime sync
+docker compose exec php php bin/console module:sync              # full sync: db:migrate → module:migrate → permissions → build → assets
+docker compose exec php php bin/console db:migrate               # apply core db/updates/*.sql idempotently
+docker compose exec php php bin/console db:migrate --status      # list applied vs. pending core migrations
 docker compose exec php php bin/console module:migrate           # apply module SQL migrations
 docker compose exec php php bin/console module:permissions-sync  # sync + deactivate orphaned
 docker compose exec php php bin/console module:build             # build runtime page root

config/config.php

@@ -1,7 +1,7 @@
 <?php
 
-use MintyPHP\Auth;
 use MintyPHP\App\Bootstrap\EnvValidator;
+use MintyPHP\Auth;
 use MintyPHP\Cache;
 use MintyPHP\DB;
 use MintyPHP\Debugger;

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

db/init/init.sql

@@ -465,6 +465,14 @@ CREATE TABLE IF NOT EXISTS `module_migrations` (
   UNIQUE KEY `uq_module_migration` (`module_id`, `filename`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
+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;
+
 CREATE TABLE IF NOT EXISTS `user_api_tokens` (
   `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
   `uuid` CHAR(36) NOT NULL,

db/updates/2026-04-29-core-migrations-table.sql

@@ -0,0 +1,10 @@
+-- Tracking table for `bin/console db:migrate` (the new CLI that applies
+-- db/updates/*.sql idempotently for existing installs). Identical DDL to the
+-- one in db/init/init.sql; included here for installs that predate the table.
+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;

docs/howto-erste-aenderung.md

@@ -38,7 +38,7 @@ Ein neuer Entwickler soll den ersten Change strukturiert und reproduzierbar umse
 3. Optional Service/Repository ergänzen, Instanziierung über `app(...)`/Factory-Standards
 4. `docs/openapi.yaml` aktualisieren
 5. `/docs/reference-api.md` mit Beispiel aktualisieren
-6. Bei neuen Berechtigungen: `PermissionService` + `init.sql` synchron halten, für Bestandsumgebungen idempotentes SQL-Update in `db/updates/*.sql` bereitstellen
+6. Bei neuen Berechtigungen: `PermissionService` + `init.sql` synchron halten, für Bestandsumgebungen idempotentes SQL-Update in `db/updates/*.sql` bereitstellen — wird automatisch von `bin/console db:migrate` (bzw. `module:sync`) angewendet
 
 ### Done-Kriterien
 

docs/howto-fehlerbehebung.md

@@ -1,6 +1,21 @@
 # Fehlerbehebung
 
-Letzte Aktualisierung: 2026-03-14
+Letzte Aktualisierung: 2026-04-29
+
+## Schema scheint veraltet nach `git pull`
+
+### Symptom
+
+Nach einem Pull schlagen Queries fehl, weil eine Spalte/Tabelle fehlt — oder der Doctor meldet inkonsistentes Schema.
+
+### Lösung
+
+```bash
+docker compose exec php php bin/console db:migrate --status   # zeigt was fehlt
+docker compose exec php php bin/console module:sync           # wendet alles an (db:migrate + module:migrate + ...)
+```
+
+`db:migrate` wendet idempotente Updates aus `db/updates/*.sql` an und trackt sie in `core_migrations`. Auch nach manuellem `mariadb < db/updates/...sql` sicher: jeder Lauf ist idempotent.
 
 ## App reagiert nicht wie erwartet
 

docs/reference-cli-commands.md

@@ -26,13 +26,13 @@ php bin/console <command> --help
 
 ### module:sync
 
-Fuehrt den vollstaendigen Modul-Runtime-Sync aus: `migrate` → `permissions-sync` → `build` → `assets-sync`.
+Fuehrt den vollstaendigen Runtime-Sync aus: `db-migrate` → `migrate` → `permissions-sync` → `build` → `assets-sync`.
 
 ```bash
 docker compose exec php php bin/console module:sync
 ```
 
-Noetig nach jeder Aenderung an Modulen, Manifesten, Routen oder `APP_ENABLED_MODULES`.
+Noetig nach jeder Aenderung an Modulen, Manifesten, Routen oder `APP_ENABLED_MODULES` — und nach jedem `git pull`, der Schema-Updates unter `db/updates/*.sql` mitbringt.
 
 Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist dieser Befehl die Loesung.
 
@@ -42,6 +42,26 @@ Maschinenlesbar:
 docker compose exec php php bin/console module:sync --format=json
 ```
 
+### db:migrate
+
+Wendet idempotente Core-Schema-Updates aus `db/updates/*.sql` an. Angewendete Files werden in der Tabelle `core_migrations` getrackt; jeder Lauf wendet nur neu hinzugekommene Files an.
+
+Jede `db/updates/*.sql` MUSS idempotent sein (`CREATE TABLE IF NOT EXISTS`, `INSERT … ON DUPLICATE KEY UPDATE`, etc.) — Erstlauf gegen ein bereits bestehendes Schema ist damit ein No-op.
+
+```bash
+docker compose exec php php bin/console db:migrate
+```
+
+`module:sync` ruft den Befehl als ersten Schritt automatisch auf. Direktaufruf nuetzlich, wenn nur DB-Updates gewuenscht sind ohne Module-Build.
+
+Status-Anzeige (kein Schreibzugriff):
+
+```bash
+docker compose exec php php bin/console db:migrate --status
+```
+
+Listet `applied:` und `pending:` separat — nuetzlich beim Debugging veralteter Schemata.
+
 ### module:migrate
 
 Wendet ausstehende SQL-Migrationen aus aktiven Modulen an.

phpstan-baseline.neon

@@ -2184,36 +2184,6 @@ parameters:
 			count: 1
 			path: tests/Console/ConsoleApplicationTest.php
 
-		-
-			message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateConfirm" is never used$#'
-			identifier: public.property.unused
-			count: 1
-			path: tests/Console/ModuleCommandsTest.php
-
-		-
-			message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateDryRun" is never used$#'
-			identifier: public.property.unused
-			count: 1
-			path: tests/Console/ModuleCommandsTest.php
-
-		-
-			message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateModuleId" is never used$#'
-			identifier: public.property.unused
-			count: 1
-			path: tests/Console/ModuleCommandsTest.php
-
-		-
-			message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$deactivateResult" is never used$#'
-			identifier: public.property.unused
-			count: 1
-			path: tests/Console/ModuleCommandsTest.php
-
-		-
-			message: '#^Public property "MintyPHP\\Tests\\Console\\FakeModuleRunner\:\:\$runtimeSyncResult" is never used$#'
-			identifier: public.property.unused
-			count: 1
-			path: tests/Console/ModuleCommandsTest.php
-
 		-
 			message: '#^Public constant "MintyPHP\\Tests\\Service\\Access\\TestMultiDependencyPolicy\:\:ABILITY" is never used$#'
 			identifier: public.classConstant.unused

tests/Console/CoreCommandsTest.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace MintyPHP\Tests\Console;
+
+use MintyPHP\Console\Commands\Database\MigrateCommand;
+use PHPUnit\Framework\TestCase;
+
+final class CoreCommandsTest extends TestCase
+{
+    public function testDbMigrateSuccessOutputAndExitCode(): void
+    {
+        $runner = new FakeModuleRunner();
+        $runner->dbMigrateResult = [
+            'command' => 'db:migrate',
+            'status' => 'ok',
+            'exit_code' => 0,
+            'vendor_warnings_ignored' => 0,
+            'message' => 'db-migrate: applied 3 migration(s).',
+        ];
+
+        $command = new MigrateCommand($runner);
+
+        ob_start();
+        $exitCode = $command->execute([], []);
+        $output = (string) ob_get_clean();
+
+        self::assertSame(0, $exitCode);
+        self::assertStringContainsString('db-migrate: applied 3 migration(s).', $output);
+    }
+
+    public function testDbMigrateFailureWritesToStderrAndReturnsNonZero(): void
+    {
+        $runner = new FakeModuleRunner();
+        $runner->dbMigrateResult = [
+            'command' => 'db:migrate',
+            'status' => 'failed',
+            'exit_code' => 1,
+            'vendor_warnings_ignored' => 0,
+            'message' => 'db-migrate: failure: Core migration foo.sql failed: SQLSTATE[42S02]',
+        ];
+
+        $command = new MigrateCommand($runner);
+
+        ob_start();
+        $exitCode = $command->execute([], []);
+        ob_end_clean();
+
+        self::assertSame(1, $exitCode);
+    }
+
+    public function testDbMigrateStatusListsAppliedAndPending(): void
+    {
+        $runner = new FakeModuleRunner();
+        $runner->dbMigrateStatusResult = [
+            'command' => 'db:migrate --status',
+            'applied' => [
+                '2026-02-23-tenant-scope-global.sql',
+                '2026-03-13-seed-default-roles.sql',
+            ],
+            'pending' => [
+                '2026-04-29-core-migrations-table.sql',
+            ],
+        ];
+
+        $command = new MigrateCommand($runner);
+
+        ob_start();
+        $exitCode = $command->execute([], ['status' => true]);
+        $output = (string) ob_get_clean();
+
+        self::assertSame(0, $exitCode);
+        self::assertStringContainsString('2 applied, 1 pending', $output);
+        self::assertStringContainsString('2026-02-23-tenant-scope-global.sql', $output);
+        self::assertStringContainsString('2026-04-29-core-migrations-table.sql', $output);
+        self::assertStringContainsString("applied:\n", $output);
+        self::assertStringContainsString("pending:\n", $output);
+    }
+
+    public function testDbMigrateStatusHandlesEmptyLists(): void
+    {
+        $runner = new FakeModuleRunner();
+        $runner->dbMigrateStatusResult = [
+            'command' => 'db:migrate --status',
+            'applied' => [],
+            'pending' => [],
+        ];
+
+        $command = new MigrateCommand($runner);
+
+        ob_start();
+        $exitCode = $command->execute([], ['status' => true]);
+        $output = (string) ob_get_clean();
+
+        self::assertSame(0, $exitCode);
+        self::assertStringContainsString('0 applied, 0 pending', $output);
+        self::assertStringContainsString("applied:\n  (none)", $output);
+        self::assertStringContainsString("pending:\n  (none)", $output);
+    }
+}

tests/Console/ModuleCommandsTest.php

@@ -19,6 +19,7 @@ final class ModuleCommandsTest extends TestCase
             'vendor_warnings_ignored_total' => 2,
             'duration_ms' => 88,
             'steps' => [
+                'db-migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
                 'migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
                 'permissions-sync' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 1],
                 'build' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
@@ -41,6 +42,7 @@ final class ModuleCommandsTest extends TestCase
         self::assertSame('ok', $decoded['status']);
         self::assertSame(0, $decoded['exit_code']);
         self::assertArrayHasKey('steps', $decoded);
+        self::assertArrayHasKey('db-migrate', $decoded['steps']);
         self::assertArrayHasKey('migrate', $decoded['steps']);
         self::assertArrayHasKey('assets-sync', $decoded['steps']);
     }
@@ -78,6 +80,9 @@ final class ModuleCommandsTest extends TestCase
     }
 }
 
+/**
+ * @api Test fixture — public properties are mutated by test cases across files.
+ */
 final class FakeModuleRunner implements ModuleRunnerInterface
 {
     /** @var array<string, mixed> */
@@ -88,6 +93,7 @@ final class FakeModuleRunner implements ModuleRunnerInterface
         'vendor_warnings_ignored_total' => 0,
         'duration_ms' => 0,
         'steps' => [
+            'db-migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
             'migrate' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
             'permissions-sync' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
             'build' => ['status' => 'ok', 'exit_code' => 0, 'vendor_warnings_ignored' => 0],
@@ -96,6 +102,22 @@ final class FakeModuleRunner implements ModuleRunnerInterface
         'message' => 'ok',
     ];
 
+    /** @var array<string, mixed> */
+    public array $dbMigrateResult = [
+        'command' => 'db:migrate',
+        'status' => 'ok',
+        'exit_code' => 0,
+        'vendor_warnings_ignored' => 0,
+        'message' => 'db-migrate: all updates already applied.',
+    ];
+
+    /** @var array<string, mixed> */
+    public array $dbMigrateStatusResult = [
+        'command' => 'db:migrate --status',
+        'applied' => [],
+        'pending' => [],
+    ];
+
     /** @var array<string, mixed> */
     public array $deactivateResult = [
         'command' => 'module:deactivate',
@@ -109,6 +131,16 @@ final class FakeModuleRunner implements ModuleRunnerInterface
     public bool $deactivateConfirm = false;
     public bool $deactivateDryRun = false;
 
+    public function dbMigrate(): array
+    {
+        return $this->dbMigrateResult;
+    }
+
+    public function dbMigrateStatus(): array
+    {
+        return $this->dbMigrateStatusResult;
+    }
+
     public function migrate(): array
     {
         return [