---
title: "CLI Migrations"
description: "Apply, verify, and manage database migrations with the RoomSharp CLI."
canonical: "https://roomsharp.dev/docs/v0.4.7/cli-migrations"
source: "src/content/v0.4.7/cli-migrations.mdx"
---

# Migration Commands

<Warning title="Build Before Running">
Runtime commands load your compiled assembly. If you modify code (entities, migrations, database), you **MUST** rebuild before running these commands to avoid unexpected behavior.
</Warning>

## Build Requirements

**Option 1: Manual Build**
```bash
dotnet build
room migrate:status
```

**Option 2: Auto-Build (Recommended)**
```bash
room migrate:status -b        # Debug build
room migrate:status -b -r     # Release build
```

Runtime commands that require a built assembly:
- `migrate:up`, `migrate:status`, `migrate:plan`, `migrate:verify`
- `database:reset`, `database:seed`
- `schema:export`, `schema:validate`

## migrate:status

Shows the current migration status of your database.

```bash
room migrate:status
```

**Sample output:**

```
Current version : 0
Target version  : 3
Latest migration: 3
Pending migrations:
  - Migration_1_2 (1->2)
  - Migration_2_3 (2->3)
```

## migrate:up

Applies pending migrations to bring the database to the target version.

```bash
room migrate:up --to=3
```

- Applies auto + manual migrations
- Uses `MigrationManager` under the hood
- Optionally allows destructive fallback with `--fallback-destructive`
- Rebuilds schema via `SchemaGenerator` after migrations

## migrate:plan

Prints the exact migration chain that would be applied (strict pathing: no gaps, no branching).

```bash
room migrate:plan --to=3
```

## migrate:verify

Verifies applied migrations against their recorded checksums in `__room_migrations`.

```bash
room migrate:verify
```

<Tip>
Use `migrate:verify` in CI/production to detect schema drift and ensure migrations haven't been modified after being applied.
</Tip>

## migrate:set-version

<Danger title="DANGEROUS">
This does **not** roll back schema changes. It only edits `__room_state` for manual recovery scenarios. Use only if you know exactly what you're doing (prefer restoring from a backup in production).
</Danger>

```bash
room migrate:set-version --to=2 --force
```

## migrate:rollback

Rolls back migrations using the `IReversibleMigration` interface for migrations that implement `DownAsync`.

```bash
room migrate:rollback              # Roll back 1 step
room migrate:rollback --steps=3    # Roll back 3 steps
room migrate:rollback --to=5       # Roll back to version 5
room migrate:rollback --force      # Skip confirmation
```

| Option | Description |
|--------|-------------|
| `--to=N` | Roll back to specific version |
| `--steps=N` | Roll back N steps (default: 1) |
| `--force` | Skip confirmation prompt |
| `-b` | Auto-build before running |

<Warning title="Requires IReversibleMigration">
Only migrations implementing `IReversibleMigration` can be rolled back. Manual migrations without `DownAsync` will fail.
</Warning>

**Example reversible migration:**

```csharp
public class Migration_1_to_2 : IRoomMigration, IReversibleMigration
{
    public int StartVersion => 1;
    public int EndVersion => 2;

    public async Task UpAsync(MigrationContext ctx)
    {
        await ctx.CreateCommand("ALTER TABLE users ADD COLUMN email TEXT").ExecuteNonQueryAsync();
    }

    public async Task DownAsync(MigrationContext ctx)
    {
        await ctx.CreateCommand("ALTER TABLE users DROP COLUMN email").ExecuteNonQueryAsync();
    }
}
```

## migrate:timeline

Displays a visual timeline of applied migrations with success/failure status and execution time.

```bash
room migrate:timeline
```

**Sample output:**

```
┌ Migration Timeline
  Date             │ Migration                        │     Time │ Status
  ─────────────────┼──────────────────────────────────┼──────────┼───────
  2024-12-15 10:30 │ Migration_1_2                    │    125ms │ ✓
  2024-12-18 14:15 │ Migration_2_3                    │     89ms │ ✓
  2024-12-20 09:00 │ Migration_3_4                    │     45ms │ ✗
     └─ Foreign key constraint failed...
└ Current Version: 3
```

<Tip>
Use `migrate:timeline` to quickly diagnose migration history and identify failed migrations.
</Tip>

---

# Database Commands

<Warning>
These commands require `provider` and `connectionString`. Build the project first.
</Warning>

## database:drop

Drops the database entirely.

```bash
room database:drop --force
```

| Option | Description |
|--------|-------------|
| `--provider` | Database provider |
| `--connection` | Connection string |
| `--force` | Skip confirmation prompt |

## database:reset

Drops and recreates the database, applying all migrations from scratch.

```bash
room database:reset -b --force
```

| Option | Description |
|--------|-------------|
| `-b` | Auto-build before running |
| `--force` | Skip confirmation prompt |
| `--fallback-destructive` | Allow destructive fallback if schema mismatch |

## database:seed

Runs all registered seeders to populate the database with initial data.

```bash
room database:seed -b --env=development
```

| Option | Description |
|--------|-------------|
| `-b` | Auto-build before running |
| `--env` | Environment filter |
| `--only=A,B` | Run only specific seeders |
| `--skip=C` | Skip specific seeders |
| `--force` | Force re-run even if already seeded |
| `--plan` | Show execution plan without running |
| `--dry-run` | Preview without executing |
| `--allow-production` | Allow running in production environment |
| `--continue-on-error` | Continue if a seeder fails |

---

# Schema Commands

## schema:export

Exports the current schema to files for documentation or CI verification.

```bash
room schema:export --out ./schema_export
```

- Uses `SchemaMigrationExporter` to export schema for the active provider and version.
- Defaults to `schema_export` folder if `--out` is not provided.

### Raw SQL Export

```bash
room schema:export --sql --out ./schema_sql
```

Use `--sql` to export raw `CREATE TABLE` DDL statements instead of JSON. Useful for:
- DBA reviews
- CI/CD verification
- Database documentation

## schema:validate

Validates the live database schema against exported files.

```bash
room schema:validate --schema=./schema_export
```

- Uses `SchemaRuntimeValidator.EnsureSchema` to validate the live database schema against exported files.

---

# Migrations in Production

<Note title="Production Best Practices">

- Migrations run under a real DB transaction via `MigrationContext` and are protected by a provider-specific migration lock.
- RoomSharp fails fast if `__room_state.dirty = 1` (previous migration attempt left the database in an unsafe state). Recovery: restore from backup or manually repair schema, then clear `dirty`.
- Rollbacks are not supported unless you implement your own "down" strategy; use destructive fallback only when appropriate (typically dev/test).
- `__room_migrations` stores migration `Id` + `Checksum` so you can detect drift; use the CLI `migrate:verify` command in CI/production checks.

</Note>