Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

The ORM includes a practical console toolkit for schema inspection, diffing, syncing, and seeding with safe defaults.

How it works

orm:status reports server capabilities and sync state, orm:diff shows the delta, orm:sync can dry-run or export the SQL plan, and orm:seed applies defaults() upserts for seedable resources.

Why it matters

A framework should not stop at attributes and repositories. Real teams need an operational surface that explains what will happen before it changes production state.

Key concepts

orm:status: Reports database/server capabilities and whether the schema is currently in sync.
orm:diff: Shows structural differences between the code schema and the live database.
--output: Exports the computed SQL plan to a file for audit, review, or deployment pipelines.

Operational Surface

CLI that explains the plan before touching the database

The ORM console commands are part of the product story. They let you inspect status, review diffs, export SQL plans, and seed data without improvising custom scripts.

Command	Purpose	Operational value
`bin/semitexa orm:status`	Show DB/server capabilities and whether schema is in sync.	Gives fast operational context before any change.
`bin/semitexa orm:diff`	List code-vs-database differences.	Lets reviewers see pending table, column, index, and FK changes.
`bin/semitexa orm:sync --dry-run`	Build the execution plan without executing it.	Safe default for CI, review, and local inspection.
`bin/semitexa orm:sync --output plan.sql`	Export the SQL plan to a file.	Useful for audit trails and DevOps handoff.
`bin/semitexa orm:seed`	Run defaults() upserts for seedable resources.	Makes local/demo environments reproducible quickly.

Inspect current sync state

bin/semitexa orm:status
bin/semitexa orm:diff

Review SQL before execution

bin/semitexa orm:sync --dry-run -vv
bin/semitexa orm:sync --dry-run --output var/migrations/history/review.sql

Apply safe changes, then seed

bin/semitexa orm:sync
bin/semitexa orm:seed

orm:sync orm:seed

Verified against Semitexa Ultimate 2026.09.19.1020

ORM Console Toolkit

Framework credibility also lives in operations. The ORM CLI should tell you what will change before it changes anything.

How it works

orm:status shows database capabilities and whether the schema is in sync. orm:diff lists code-versus-database differences without applying them. orm:sync --dry-run builds the execution plan as reviewable output, and --output exports it to a SQL file for audit trails. orm:seed runs defaults() upserts for seedable resources to make local and demo environments reproducible.

Why this matters

Teams that skip review tooling end up applying schema changes they did not fully understand. Treating orm:sync --dry-run as the normal review path — rather than an exotic flag — shortens incident recovery and makes schema changes safe to delegate.

1<?php23declare(strict_types=1);45namespace Semitexa\Orm\Application\Console\Command;67use Semitexa\Core\Attribute\AsCommand;8use Semitexa\Core\Attribute\InjectAsReadonly;9use Semitexa\Core\Console\BaseCommand;10use Semitexa\Orm\Adapter\ServerCapability;11use Semitexa\Orm\Application\Service\Connection\ConnectionRegistry;12use Symfony\Component\Console\Command\Command;13use Symfony\Component\Console\Input\InputInterface;14use Symfony\Component\Console\Input\InputOption;15use Symfony\Component\Console\Output\OutputInterface;16use Symfony\Component\Console\Style\SymfonyStyle;1718#[AsCommand(name: 'orm:status', description: 'Show ORM status: database info, server capabilities, schema summary')]19class OrmStatusCommand extends BaseCommand20{21    #[InjectAsReadonly]22    protected ConnectionRegistry $connections;2324    protected function configure(): void25    {26        $this->setName('orm:status')27            ->setDescription('Show ORM status: database info, server capabilities, schema summary')28            ->addOption('connection', 'c', InputOption::VALUE_REQUIRED, 'Connection name to inspect', 'default');29    }3031    protected function execute(InputInterface $input, OutputInterface $output): int32    {33        $io = new SymfonyStyle($input, $output);34        $connectionOption = $input->getOption('connection');35        $connection = is_string($connectionOption) && $connectionOption !== '' ? $connectionOption : 'default';3637        try {38            $orm = $this->connections->manager($connection);39            $adapter = $orm->getAdapter();40            $isSqlite = str_contains(strtolower($adapter::class), 'sqlite');4142            // Server info43            $io->section('Database Server');44            $serverInfo = [45                ['Server Version' => $adapter->getServerVersion()],46                ['Database' => $orm->getDatabaseName()],47            ];48            if (!$isSqlite) {49                $pool = $orm->getPool();50                $serverInfo[] = ['Pool Size' => (string) $pool->getSize()];51                if ($pool instanceof \Semitexa\Orm\Adapter\ConnectionPool) {52                    foreach ($pool->getStats() as $key => $value) {53                        if ($key === 'size') {54                            continue;55                        }56                        $serverInfo[] = ['Pool ' . str_replace('_', ' ', $key) => (string) $value];57                    }58                }59            }60            $io->definitionList(...$serverInfo);6162            // Capabilities63            $io->section('Server Capabilities');64            $rows = [];65            foreach (ServerCapability::cases() as $capability) {66                $supported = $adapter->supports($capability);67                $rows[] = [68                    $capability->value,69                    $capability->name,70                    $supported ? '<info>Yes</info>' : '<fg=red>No</>',71                ];72            }73            $io->table(['Capability', 'Name', 'Supported'], $rows);7475            // Code schema summary76            $io->section('Code Schema');77            $collector = $orm->getSchemaCollector();78            $schema = $collector->collect();7980            $errors = $collector->getErrors();81            $warnings = $collector->getWarnings();8283            $totalColumns = 0;84            $totalIndexes = 0;85            foreach ($schema as $table) {86                $totalColumns += count($table->getColumns());87                $totalIndexes += count($table->getIndexes());88            }8990            $io->definitionList(91                ['Tables' => (string) count($schema)],92                ['Total Columns' => (string) $totalColumns],93                ['Total Indexes' => (string) $totalIndexes],94                ['Validation Errors' => (string) count($errors)],95                ['Validation Warnings' => (string) count($warnings)],96            );9798            if ($errors !== []) {99                $io->error('Validation errors:');100                $io->listing($errors);101            }102103            if ($warnings !== []) {104                $io->warning('Warnings:');105                $io->listing($warnings);106            }107108            // Sync status109            $io->section('Sync Status');110            $comparator = $orm->getSchemaComparator();111            $diff = $comparator->compare($schema);112113            if ($diff->isEmpty()) {114                $io->success('Database is in sync with code.');115            } else {116                $syncEngine = $orm->getSyncEngine();117                $plan = $syncEngine->buildPlan($diff);118                $io->warning('Database is out of sync.');119                $io->text($plan->getSummary());120            }121122            return Command::SUCCESS;123        } catch (\Throwable $e) {124            $io->error('Status check failed: ' . $e->getMessage());125            if ($output->isVerbose()) {126                $io->text($e->getTraceAsString());127            }128            return Command::FAILURE;129        }130    }131}132

<?php

declare(strict_types=1);

namespace Semitexa\Orm\Application\Console\Command;

use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Console\BaseCommand;
use Semitexa\Orm\Adapter\ServerCapability;
use Semitexa\Orm\Application\Service\Connection\ConnectionRegistry;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(name: 'orm:status', description: 'Show ORM status: database info, server capabilities, schema summary')]
class OrmStatusCommand extends BaseCommand
{
    #[InjectAsReadonly]
    protected ConnectionRegistry $connections;

    protected function configure(): void
    {
        $this->setName('orm:status')
            ->setDescription('Show ORM status: database info, server capabilities, schema summary')
            ->addOption('connection', 'c', InputOption::VALUE_REQUIRED, 'Connection name to inspect', 'default');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $connectionOption = $input->getOption('connection');
        $connection = is_string($connectionOption) && $connectionOption !== '' ? $connectionOption : 'default';

        try {
            $orm = $this->connections->manager($connection);
            $adapter = $orm->getAdapter();
            $isSqlite = str_contains(strtolower($adapter::class), 'sqlite');

            // Server info
            $io->section('Database Server');
            $serverInfo = [
                ['Server Version' => $adapter->getServerVersion()],
                ['Database' => $orm->getDatabaseName()],
            ];
            if (!$isSqlite) {
                $pool = $orm->getPool();
                $serverInfo[] = ['Pool Size' => (string) $pool->getSize()];
                if ($pool instanceof \Semitexa\Orm\Adapter\ConnectionPool) {
                    foreach ($pool->getStats() as $key => $value) {
                        if ($key === 'size') {
                            continue;
                        }
                        $serverInfo[] = ['Pool ' . str_replace('_', ' ', $key) => (string) $value];
                    }
                }
            }
            $io->definitionList(...$serverInfo);

            // Capabilities
            $io->section('Server Capabilities');
            $rows = [];
            foreach (ServerCapability::cases() as $capability) {
                $supported = $adapter->supports($capability);
                $rows[] = [
                    $capability->value,
                    $capability->name,
                    $supported ? '<info>Yes</info>' : '<fg=red>No</>',
                ];
            }
            $io->table(['Capability', 'Name', 'Supported'], $rows);

            // Code schema summary
            $io->section('Code Schema');
            $collector = $orm->getSchemaCollector();
            $schema = $collector->collect();

            $errors = $collector->getErrors();
            $warnings = $collector->getWarnings();

            $totalColumns = 0;
            $totalIndexes = 0;
            foreach ($schema as $table) {
                $totalColumns += count($table->getColumns());
                $totalIndexes += count($table->getIndexes());
            }

            $io->definitionList(
                ['Tables' => (string) count($schema)],
                ['Total Columns' => (string) $totalColumns],
                ['Total Indexes' => (string) $totalIndexes],
                ['Validation Errors' => (string) count($errors)],
                ['Validation Warnings' => (string) count($warnings)],
            );

            if ($errors !== []) {
                $io->error('Validation errors:');
                $io->listing($errors);
            }

            if ($warnings !== []) {
                $io->warning('Warnings:');
                $io->listing($warnings);
            }

            // Sync status
            $io->section('Sync Status');
            $comparator = $orm->getSchemaComparator();
            $diff = $comparator->compare($schema);

            if ($diff->isEmpty()) {
                $io->success('Database is in sync with code.');
            } else {
                $syncEngine = $orm->getSyncEngine();
                $plan = $syncEngine->buildPlan($diff);
                $io->warning('Database is out of sync.');
                $io->text($plan->getSummary());
            }

            return Command::SUCCESS;
        } catch (\Throwable $e) {
            $io->error('Status check failed: ' . $e->getMessage());
            if ($output->isVerbose()) {
                $io->text($e->getTraceAsString());
            }
            return Command::FAILURE;
        }
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Orm\Application\Console\Command;67use Semitexa\Core\Attribute\AsCommand;8use Semitexa\Core\Console\BaseCommand;9use Semitexa\Orm\Application\Service\Connection\ConnectionRegistry;10use Symfony\Component\Console\Command\Command;11use Symfony\Component\Console\Input\InputInterface;12use Symfony\Component\Console\Input\InputOption;13use Symfony\Component\Console\Output\OutputInterface;14use Symfony\Component\Console\Style\SymfonyStyle;1516#[AsCommand(name: 'orm:diff', description: 'Show differences between code schema and database')]17class OrmDiffCommand extends BaseCommand18{19    public function __construct(20        private readonly ConnectionRegistry $connections,21    ) {22        parent::__construct();23    }2425    protected function configure(): void26    {27        $this->setName('orm:diff')28            ->setDescription('Show differences between code schema and database')29            ->addOption('connection', 'c', InputOption::VALUE_REQUIRED, 'Connection name to diff', 'default');30    }3132    protected function execute(InputInterface $input, OutputInterface $output): int33    {34        $io = new SymfonyStyle($input, $output);35        $connectionOption = $input->getOption('connection');36        if (!is_string($connectionOption)) {37            $io->error('Invalid --connection option value.');3839            return Command::FAILURE;40        }4142        $connection = trim($connectionOption);43        if ($connection === '') {44            $io->error('The --connection option must not be empty.');4546            return Command::FAILURE;47        }4849        try {50            $orm = $this->connections->manager($connection);5152            // 1. Collect schema from code53            $collector = $orm->getSchemaCollector();54            $codeSchema = $collector->collect();5556            $errors = $collector->getErrors();57            if ($errors !== []) {58                $io->error('Schema validation errors:');59                $io->listing($errors);60                return Command::FAILURE;61            }6263            // 2. Compare with DB64            $comparator = $orm->getSchemaComparator();65            $diff = $comparator->compare($codeSchema);6667            if ($diff->isEmpty()) {68                $io->success('No differences. Database matches code schema.');6970                return Command::SUCCESS;71            }7273            // Display diff74            foreach ($diff->getCreateTables() as $table) {75                $io->section("+ CREATE TABLE `{$table->name}`");76                foreach ($table->getColumns() as $col) {77                    $io->text("    + {$col->name} ({$col->type->canonicalName($col->length, $col->precision, $col->scale)})");78                }79            }8081            foreach ($diff->getAddColumns() as $tableName => $columns) {82                $io->section("~ ALTER TABLE `{$tableName}`");83                foreach ($columns as $col) {84                    $io->text("    <info>+ ADD COLUMN</info> {$col->name} ({$col->type->canonicalName($col->length, $col->precision, $col->scale)})");85                }86            }8788            foreach ($diff->getAlterColumns() as $tableName => $alterations) {89                if (!isset($diff->getAddColumns()[$tableName])) {90                    $io->section("~ ALTER TABLE `{$tableName}`");91                }92                foreach ($alterations as $alt) {93                    $col = $alt['column'];94                    $changes = implode(', ', $alt['changes']);95                    $io->text("    <comment>~ MODIFY COLUMN</comment> {$col->name}: {$changes}");96                }97            }9899            foreach ($diff->getDropColumns() as $tableName => $columns) {100                if (!isset($diff->getAddColumns()[$tableName]) && !isset($diff->getAlterColumns()[$tableName])) {101                    $io->section("~ ALTER TABLE `{$tableName}`");102                }103                foreach ($columns as $colInfo) {104                    $io->text("    <fg=red>- DROP COLUMN</> {$colInfo['name']}");105                }106            }107108            foreach ($diff->getAddIndexes() as $tableName => $indexes) {109                foreach ($indexes as $entry) {110                    $cols = implode(', ', $entry['index']->columns);111                    $io->text("    <info>+ ADD INDEX</info> {$entry['name']} ({$cols})");112                }113            }114115            foreach ($diff->getDropIndexes() as $tableName => $indexNames) {116                foreach ($indexNames as $name) {117                    $io->text("    <fg=red>- DROP INDEX</> {$name}");118                }119            }120121            foreach ($diff->getAddForeignKeys() as $fk) {122                $io->text("    <fg=green>+ ADD FK</> `{$fk->constraintName()}` ({$fk->table}.{$fk->column} → {$fk->referencedTable}.{$fk->referencedColumn}) ON DELETE {$fk->onDelete->value}");123            }124125            foreach ($diff->getDropForeignKeys() as $entry) {126                $io->text("    <fg=red>- DROP FK</> `{$entry['constraintName']}` from `{$entry['table']}`");127            }128129            foreach ($diff->getDropTables() as $dbTable) {130                $phase = $dbTable->tableComment === 'SEMITEXA_DEPRECATED' ? 'phase 2 — DROP' : 'phase 1 — deprecate';131                $io->section("- DROP TABLE `{$dbTable->name}` ({$phase})");132            }133134            return Command::SUCCESS;135        } catch (\Throwable $e) {136            $io->error('Diff failed: ' . $e->getMessage());137            if ($output->isVerbose()) {138                $io->text($e->getTraceAsString());139            }140            return Command::FAILURE;141        }142    }143}144

<?php

declare(strict_types=1);

namespace Semitexa\Orm\Application\Console\Command;

use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Core\Console\BaseCommand;
use Semitexa\Orm\Application\Service\Connection\ConnectionRegistry;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(name: 'orm:diff', description: 'Show differences between code schema and database')]
class OrmDiffCommand extends BaseCommand
{
    public function __construct(
        private readonly ConnectionRegistry $connections,
    ) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->setName('orm:diff')
            ->setDescription('Show differences between code schema and database')
            ->addOption('connection', 'c', InputOption::VALUE_REQUIRED, 'Connection name to diff', 'default');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $connectionOption = $input->getOption('connection');
        if (!is_string($connectionOption)) {
            $io->error('Invalid --connection option value.');

            return Command::FAILURE;
        }

        $connection = trim($connectionOption);
        if ($connection === '') {
            $io->error('The --connection option must not be empty.');

            return Command::FAILURE;
        }

        try {
            $orm = $this->connections->manager($connection);

            // 1. Collect schema from code
            $collector = $orm->getSchemaCollector();
            $codeSchema = $collector->collect();

            $errors = $collector->getErrors();
            if ($errors !== []) {
                $io->error('Schema validation errors:');
                $io->listing($errors);
                return Command::FAILURE;
            }

            // 2. Compare with DB
            $comparator = $orm->getSchemaComparator();
            $diff = $comparator->compare($codeSchema);

            if ($diff->isEmpty()) {
                $io->success('No differences. Database matches code schema.');

                return Command::SUCCESS;
            }

            // Display diff
            foreach ($diff->getCreateTables() as $table) {
                $io->section("+ CREATE TABLE `{$table->name}`");
                foreach ($table->getColumns() as $col) {
                    $io->text("    + {$col->name} ({$col->type->canonicalName($col->length, $col->precision, $col->scale)})");
                }
            }

            foreach ($diff->getAddColumns() as $tableName => $columns) {
                $io->section("~ ALTER TABLE `{$tableName}`");
                foreach ($columns as $col) {
                    $io->text("    <info>+ ADD COLUMN</info> {$col->name} ({$col->type->canonicalName($col->length, $col->precision, $col->scale)})");
                }
            }

            foreach ($diff->getAlterColumns() as $tableName => $alterations) {
                if (!isset($diff->getAddColumns()[$tableName])) {
                    $io->section("~ ALTER TABLE `{$tableName}`");
                }
                foreach ($alterations as $alt) {
                    $col = $alt['column'];
                    $changes = implode(', ', $alt['changes']);
                    $io->text("    <comment>~ MODIFY COLUMN</comment> {$col->name}: {$changes}");
                }
            }

            foreach ($diff->getDropColumns() as $tableName => $columns) {
                if (!isset($diff->getAddColumns()[$tableName]) && !isset($diff->getAlterColumns()[$tableName])) {
                    $io->section("~ ALTER TABLE `{$tableName}`");
                }
                foreach ($columns as $colInfo) {
                    $io->text("    <fg=red>- DROP COLUMN</> {$colInfo['name']}");
                }
            }

            foreach ($diff->getAddIndexes() as $tableName => $indexes) {
                foreach ($indexes as $entry) {
                    $cols = implode(', ', $entry['index']->columns);
                    $io->text("    <info>+ ADD INDEX</info> {$entry['name']} ({$cols})");
                }
            }

            foreach ($diff->getDropIndexes() as $tableName => $indexNames) {
                foreach ($indexNames as $name) {
                    $io->text("    <fg=red>- DROP INDEX</> {$name}");
                }
            }

            foreach ($diff->getAddForeignKeys() as $fk) {
                $io->text("    <fg=green>+ ADD FK</> `{$fk->constraintName()}` ({$fk->table}.{$fk->column} → {$fk->referencedTable}.{$fk->referencedColumn}) ON DELETE {$fk->onDelete->value}");
            }

            foreach ($diff->getDropForeignKeys() as $entry) {
                $io->text("    <fg=red>- DROP FK</> `{$entry['constraintName']}` from `{$entry['table']}`");
            }

            foreach ($diff->getDropTables() as $dbTable) {
                $phase = $dbTable->tableComment === 'SEMITEXA_DEPRECATED' ? 'phase 2 — DROP' : 'phase 1 — deprecate';
                $io->section("- DROP TABLE `{$dbTable->name}` ({$phase})");
            }

            return Command::SUCCESS;
        } catch (\Throwable $e) {
            $io->error('Diff failed: ' . $e->getMessage());
            if ($output->isVerbose()) {
                $io->text($e->getTraceAsString());
            }
            return Command::FAILURE;
        }
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Orm\Application\Console\Command;67use Semitexa\Core\Attribute\AsCommand;8use Semitexa\Core\Console\BaseCommand;9use Semitexa\Orm\Application\Service\Connection\ConnectionRegistry;10use Symfony\Component\Console\Command\Command;11use Symfony\Component\Console\Input\InputInterface;12use Symfony\Component\Console\Input\InputOption;13use Symfony\Component\Console\Output\OutputInterface;14use Symfony\Component\Console\Style\SymfonyStyle;1516#[AsCommand(name: 'orm:sync', description: 'Synchronize ORM schema with the database')]17class OrmSyncCommand extends BaseCommand18{19    public function __construct(20        private readonly ConnectionRegistry $connections,21    ) {22        parent::__construct();23    }2425    protected function configure(): void26    {27        $this->setName('orm:sync')28            ->setDescription('Synchronize ORM schema with the database')29            ->addOption('connection', 'c', InputOption::VALUE_REQUIRED, 'Connection name to sync', 'default')30            ->addOption('dry-run', null, InputOption::VALUE_NONE, 'Show SQL plan without executing')31            ->addOption('allow-destructive', null, InputOption::VALUE_NONE, 'Allow destructive operations (DROP, type narrowing)')32            ->addOption('output', 'o', InputOption::VALUE_REQUIRED, 'Save SQL plan to file');33    }3435    protected function execute(InputInterface $input, OutputInterface $output): int36    {37        $io = new SymfonyStyle($input, $output);38        $connectionOption = $input->getOption('connection');39        if (!is_string($connectionOption)) {40            $io->error('Invalid --connection option value.');4142            return Command::FAILURE;43        }4445        $connection = trim($connectionOption);46        if ($connection === '') {47            $io->error('The --connection option must not be empty.');4849            return Command::FAILURE;50        }5152        $dryRun = (bool) $input->getOption('dry-run');53        $allowDestructive = (bool) $input->getOption('allow-destructive');54        $outputOption = $input->getOption('output');55        $outputFile = is_string($outputOption) && $outputOption !== '' ? $outputOption : null;5657        try {58            $orm = $this->connections->manager($connection);5960            // 1. Collect schema from code61            $io->section("Collecting schema from code (connection: {$connection})...");62            $collector = $orm->getSchemaCollector();63            $codeSchema = $collector->collect();6465            $errors = $collector->getErrors();66            if ($errors !== []) {67                $io->error('Schema validation errors:');68                $io->listing($errors);69                return Command::FAILURE;70            }7172            $warnings = $collector->getWarnings();73            if ($warnings !== []) {74                $io->warning('Schema warnings:');75                $io->listing($warnings);76            }7778            $io->text(sprintf('Found %d table(s) in code.', count($codeSchema)));7980            // 2. Compare with DB81            $io->section('Comparing with database...');82            $comparator = $orm->getSchemaComparator();83            $diff = $comparator->compare($codeSchema);8485            if ($diff->isEmpty()) {86                $io->success('Database is up to date. No changes needed.');8788                return Command::SUCCESS;89            }9091            // 3. Build execution plan92            $syncEngine = $orm->getSyncEngine();93            $plan = $syncEngine->buildPlan($diff);9495            $io->text($plan->getSummary());96            $io->newLine();9798            // Show plan details99            $safeOps = $plan->getSafeOperations();100            $destructiveOps = $plan->getDestructiveOperations();101102            if ($safeOps !== []) {103                $io->section('Safe operations:');104                foreach ($safeOps as $op) {105                    $io->text("  <info>[{$op->type->value}]</info> {$op->description}");106                    if ($output->isVerbose()) {107                        $io->text("    SQL: {$op->sql}");108                    }109                }110            }111112            if ($destructiveOps !== []) {113                $io->section('Destructive operations:');114                foreach ($destructiveOps as $op) {115                    $io->text("  <fg=red>[{$op->type->value}]</> {$op->description}");116                    if ($output->isVerbose()) {117                        $io->text("    SQL: {$op->sql}");118                    }119                }120121                if (!$allowDestructive) {122                    $io->warning('Destructive operations will be skipped. Use --allow-destructive to include them.');123                }124            }125126            // Save to file if requested127            if ($outputFile !== null) {128                $statements = $plan->toSqlStatements($allowDestructive);129                $content = implode(";\n", $statements) . ";\n";130                file_put_contents($outputFile, $content);131                $io->text("SQL plan saved to: {$outputFile}");132            }133134            // Execute if not dry-run135            if ($dryRun) {136                $io->note('Dry run mode — no changes applied.');137138                return Command::SUCCESS;139            }140141            $executed = $syncEngine->execute($plan, $allowDestructive);142            $io->success(sprintf('Executed %d operation(s).', count($executed)));143144            $orm->shutdown();145            return Command::SUCCESS;146        } catch (\Throwable $e) {147            $io->error('Sync failed: ' . $e->getMessage());148            if ($output->isVerbose()) {149                $io->text($e->getTraceAsString());150            }151            return Command::FAILURE;152        }153    }154}155

<?php

declare(strict_types=1);

namespace Semitexa\Orm\Application\Console\Command;

use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Core\Console\BaseCommand;
use Semitexa\Orm\Application\Service\Connection\ConnectionRegistry;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(name: 'orm:sync', description: 'Synchronize ORM schema with the database')]
class OrmSyncCommand extends BaseCommand
{
    public function __construct(
        private readonly ConnectionRegistry $connections,
    ) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->setName('orm:sync')
            ->setDescription('Synchronize ORM schema with the database')
            ->addOption('connection', 'c', InputOption::VALUE_REQUIRED, 'Connection name to sync', 'default')
            ->addOption('dry-run', null, InputOption::VALUE_NONE, 'Show SQL plan without executing')
            ->addOption('allow-destructive', null, InputOption::VALUE_NONE, 'Allow destructive operations (DROP, type narrowing)')
            ->addOption('output', 'o', InputOption::VALUE_REQUIRED, 'Save SQL plan to file');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $connectionOption = $input->getOption('connection');
        if (!is_string($connectionOption)) {
            $io->error('Invalid --connection option value.');

            return Command::FAILURE;
        }

        $connection = trim($connectionOption);
        if ($connection === '') {
            $io->error('The --connection option must not be empty.');

            return Command::FAILURE;
        }

        $dryRun = (bool) $input->getOption('dry-run');
        $allowDestructive = (bool) $input->getOption('allow-destructive');
        $outputOption = $input->getOption('output');
        $outputFile = is_string($outputOption) && $outputOption !== '' ? $outputOption : null;

        try {
            $orm = $this->connections->manager($connection);

            // 1. Collect schema from code
            $io->section("Collecting schema from code (connection: {$connection})...");
            $collector = $orm->getSchemaCollector();
            $codeSchema = $collector->collect();

            $errors = $collector->getErrors();
            if ($errors !== []) {
                $io->error('Schema validation errors:');
                $io->listing($errors);
                return Command::FAILURE;
            }

            $warnings = $collector->getWarnings();
            if ($warnings !== []) {
                $io->warning('Schema warnings:');
                $io->listing($warnings);
            }

            $io->text(sprintf('Found %d table(s) in code.', count($codeSchema)));

            // 2. Compare with DB
            $io->section('Comparing with database...');
            $comparator = $orm->getSchemaComparator();
            $diff = $comparator->compare($codeSchema);

            if ($diff->isEmpty()) {
                $io->success('Database is up to date. No changes needed.');

                return Command::SUCCESS;
            }

            // 3. Build execution plan
            $syncEngine = $orm->getSyncEngine();
            $plan = $syncEngine->buildPlan($diff);

            $io->text($plan->getSummary());
            $io->newLine();

            // Show plan details
            $safeOps = $plan->getSafeOperations();
            $destructiveOps = $plan->getDestructiveOperations();

            if ($safeOps !== []) {
                $io->section('Safe operations:');
                foreach ($safeOps as $op) {
                    $io->text("  <info>[{$op->type->value}]</info> {$op->description}");
                    if ($output->isVerbose()) {
                        $io->text("    SQL: {$op->sql}");
                    }
                }
            }

            if ($destructiveOps !== []) {
                $io->section('Destructive operations:');
                foreach ($destructiveOps as $op) {
                    $io->text("  <fg=red>[{$op->type->value}]</> {$op->description}");
                    if ($output->isVerbose()) {
                        $io->text("    SQL: {$op->sql}");
                    }
                }

                if (!$allowDestructive) {
                    $io->warning('Destructive operations will be skipped. Use --allow-destructive to include them.');
                }
            }

            // Save to file if requested
            if ($outputFile !== null) {
                $statements = $plan->toSqlStatements($allowDestructive);
                $content = implode(";\n", $statements) . ";\n";
                file_put_contents($outputFile, $content);
                $io->text("SQL plan saved to: {$outputFile}");
            }

            // Execute if not dry-run
            if ($dryRun) {
                $io->note('Dry run mode — no changes applied.');

                return Command::SUCCESS;
            }

            $executed = $syncEngine->execute($plan, $allowDestructive);
            $io->success(sprintf('Executed %d operation(s).', count($executed)));

            $orm->shutdown();
            return Command::SUCCESS;
        } catch (\Throwable $e) {
            $io->error('Sync failed: ' . $e->getMessage());
            if ($output->isVerbose()) {
                $io->text($e->getTraceAsString());
            }
            return Command::FAILURE;
        }
    }
}

1<?php23declare(strict_types=1);45namespace Semitexa\Orm\Application\Console\Command;67use Semitexa\Core\Attribute\AsCommand;8use Semitexa\Core\Console\BaseCommand;9use Semitexa\Orm\OrmManager;10use Symfony\Component\Console\Command\Command;11use Symfony\Component\Console\Input\InputInterface;12use Symfony\Component\Console\Output\OutputInterface;13use Symfony\Component\Console\Style\SymfonyStyle;1415#[AsCommand(name: 'orm:seed', description: 'Run defaults() upsert for all Resource classes with seed data')]16class OrmSeedCommand extends BaseCommand17{18    public function __construct(19        private readonly OrmManager $orm,20    ) {21        parent::__construct();22    }2324    protected function configure(): void25    {26        $this->setName('orm:seed')27            ->setDescription('Run defaults() upsert for all Resource classes with seed data');28    }2930    protected function execute(InputInterface $input, OutputInterface $output): int31    {32        $io = new SymfonyStyle($input, $output);3334        try {35            $orm = $this->orm;3637            $io->section('Running seed (defaults) upsert...');3839            $results = $orm->getSeedRunner()->run();4041            if ($results === []) {42                $io->note('No Resource classes with defaults() found.');4344                return Command::SUCCESS;45            }4647            $totalInserted = 0;48            $totalUpdated = 0;49            $totalUnchanged = 0;5051            $rows = [];52            foreach ($results as $tableName => $stats) {53                $rows[] = [$tableName, $stats['inserted'], $stats['updated'], $stats['unchanged']];54                $totalInserted += $stats['inserted'];55                $totalUpdated += $stats['updated'];56                $totalUnchanged += $stats['unchanged'];57            }5859            $io->table(60                ['Table', 'Inserted', 'Updated', 'Unchanged'],61                $rows,62            );6364            $io->success(sprintf(65                'Seed complete: %d inserted, %d updated, %d unchanged across %d table(s).',66                $totalInserted,67                $totalUpdated,68                $totalUnchanged,69                count($results),70            ));7172            return Command::SUCCESS;73        } catch (\Throwable $e) {74            $io->error('Seed failed: ' . $e->getMessage());75            if ($output->isVerbose()) {76                $io->text($e->getTraceAsString());77            }78            return Command::FAILURE;79        }80    }81}82

<?php

declare(strict_types=1);

namespace Semitexa\Orm\Application\Console\Command;

use Semitexa\Core\Attribute\AsCommand;
use Semitexa\Core\Console\BaseCommand;
use Semitexa\Orm\OrmManager;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(name: 'orm:seed', description: 'Run defaults() upsert for all Resource classes with seed data')]
class OrmSeedCommand extends BaseCommand
{
    public function __construct(
        private readonly OrmManager $orm,
    ) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->setName('orm:seed')
            ->setDescription('Run defaults() upsert for all Resource classes with seed data');
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);

        try {
            $orm = $this->orm;

            $io->section('Running seed (defaults) upsert...');

            $results = $orm->getSeedRunner()->run();

            if ($results === []) {
                $io->note('No Resource classes with defaults() found.');

                return Command::SUCCESS;
            }

            $totalInserted = 0;
            $totalUpdated = 0;
            $totalUnchanged = 0;

            $rows = [];
            foreach ($results as $tableName => $stats) {
                $rows[] = [$tableName, $stats['inserted'], $stats['updated'], $stats['unchanged']];
                $totalInserted += $stats['inserted'];
                $totalUpdated += $stats['updated'];
                $totalUnchanged += $stats['unchanged'];
            }

            $io->table(
                ['Table', 'Inserted', 'Updated', 'Unchanged'],
                $rows,
            );

            $io->success(sprintf(
                'Seed complete: %d inserted, %d updated, %d unchanged across %d table(s).',
                $totalInserted,
                $totalUpdated,
                $totalUnchanged,
                count($results),
            ));

            return Command::SUCCESS;
        } catch (\Throwable $e) {
            $io->error('Seed failed: ' . $e->getMessage());
            if ($output->isVerbose()) {
                $io->text($e->getTraceAsString());
            }
            return Command::FAILURE;
        }
    }
}

Recommended Flow

How teams should use the CLI

Start with orm:status or orm:diff when you need to understand schema state quickly.

Treat orm:sync --dry-run as the normal review path, not as an exotic extra flag.

Use --allow-destructive only when the team intentionally wants to include DROP and narrowing operations.

Export plans with --output when another human or deployment system needs the exact SQL artifact.

How it works

orm:status reports server capabilities and sync state, orm:diff shows the delta, orm:sync can dry-run or export the SQL plan, and orm:seed applies defaults() upserts for seedable resources.

Why it matters

A framework should not stop at attributes and repositories. Real teams need an operational surface that explains what will happen before it changes production state.

Key concepts

orm:status: Reports database/server capabilities and whether the schema is currently in sync.
orm:diff: Shows structural differences between the code schema and the live database.
--output: Exports the computed SQL plan to a file for audit, review, or deployment pipelines.