Skip to main content

Migrations (CLI)

Migrations are registered in a Dart registry file and executed by the CLI via a schema-capable driver.

Prerequisites​

What You’ll Learn​

  • How to apply, preview, rollback, and export migrations from CLI
  • Why registry path wiring matters
  • How to run migration workflows safely across connections

Step Outcome​

By the end of this page, you should be able to:

  • Apply and rollback migrations with confidence
  • Preview/export SQL before mutating production state
  • Diagnose registry/config wiring issues quickly

Registry defaults​

  • Convention default registry: lib/src/database/migrations.dart
  • Optional override via ormed.yaml (migrations.registry)

Registry paths matter​

The CLI does not “discover” migrations by scanning a directory. It runs the registry entrypoint you configured:

  • migrations.registry: a runnable Dart file that exposes buildMigrations()
  • migrations.directory: where your migration sources live (used by generators/export)

Apply migrations​

migrate applies pending migrations for the selected connection:

dart run ormed_cli:ormed migrate
dart run ormed_cli:ormed migrate --limit 5
dart run ormed_cli:ormed migrate --connection analytics

Recommended safe flow:

  1. migrate --pretend
  2. migrate
  3. migrate:status

Preview (pretend)​

Show the SQL that would run without mutating the database:

dart run ormed_cli:ormed migrate --pretend

Export SQL during preview​

When you already have Dart migrations but you want up.sql/down.sql files, you can export directly from the preview pipeline:

dart run ormed_cli:ormed migrate --pretend --write-sql
dart run ormed_cli:ormed migrate --pretend --write-sql --sql-out database/migration_sql

This does not apply migrations.

Export SQL from migrations (dedicated command)​

Use migrate:export to write up.sql and down.sql for migrations without applying them:

dart run ormed_cli:ormed migrate:export --out database/migration_sql
dart run ormed_cli:ormed migrate:export --out database/migration_sql --all

Defaults:

  • exports pending migrations
  • --all exports everything registered

Output layout:

<out>/
  m_YYYYMMDDHHMMSS_slug/
    up.sql
    down.sql
note

Exported SQL comes from the active driver’s schema preview (describeSchemaPlan). Different drivers/dialects can produce different SQL.

Rollback​

Rollback the most recent migration(s):

dart run ormed_cli:ormed migrate:rollback
dart run ormed_cli:ormed migrate:rollback --steps 3

Status​

dart run ormed_cli:ormed migrate:status
dart run ormed_cli:ormed migrate:status --pending

Fresh / reset / refresh​

These are development-focused helpers:

dart run ormed_cli:ormed migrate:fresh
dart run ormed_cli:ormed migrate:reset
dart run ormed_cli:ormed migrate:refresh

Generating migrations (Dart or SQL)​

The make:migration command generates both Dart and SQL migrations.

Dart Migrations (Default)​

dart run ormed_cli:ormed make:migration --name create_users_table

SQL Migrations​

dart run ormed_cli:ormed make:migration --name add_bio_to_users --format sql

Simultaneous Support​

The CLI runner is designed to handle both formats seamlessly. When you run migrate, it builds a unified timeline of all registered migrations. It doesn't matter if a migration is a Dart class or a pair of SQL files; they will be executed in the correct chronological order. This allows you to use Dart for standard schema changes and drop down to SQL for complex, database-specific logic without breaking the migration flow.

Use make:migration to scaffold a migration entry:

dart run ormed_cli:ormed make:migration --name create_users_table

Default authoring format​

You can select the default authoring format for the active connection:

migrations:
  directory: lib/src/database/migrations
  registry: lib/src/database/migrations.dart
  format: sql # dart | sql

This affects what make:migration generates when --format is omitted. Your registry can still contain a mix of Dart and SQL-file migrations.

make --name ... remains available as a compatible alias.

Programmatic export (advanced)​

If you are building tooling, you can export SQL from SchemaPlan previews directly:

Future<void> exportSqlForMigration({
  required SchemaDriver schemaDriver,
  required MigrationDescriptor descriptor,
}) async {
  final exporter = MigrationSqlExporter(schemaDriver);
  await exporter.exportDescriptor(
    descriptor,
    outputRoot: Directory('database/migration_sql'),
  );
}

To register an SQL-file migration entry (manual wiring):

final entry = MigrationEntry(
  id: MigrationId.parse('m_20250101000000_create_users_table'),
  migration: SqlFileMigration(
    upPath: 'migrations/m_20250101000000_create_users_table/up.sql',
    downPath: 'migrations/m_20250101000000_create_users_table/down.sql',
  ),
);

Read This Next​

Verify Migration CLI Setup​

dart run ormed_cli:ormed migrate --pretend
dart run ormed_cli:ormed migrate:status --pending