reference/MIGRATION_COMMANDS.md

Dynaplex Migration Management Commands

Version: 1.0
Date: 2025-10-30
Component: dplx CLI tool

Overview

The dplx CLI tool provides comprehensive migration management commands for Dynaplex components, including commands for clearing migrations and reinitializing components. These commands are essential for architectural refactors and fresh starts.

New Commands

clear - Clear Migrations for a Component

Deletes all migration files for a specific component, including the ModelSnapshot.

Usage:

dplx db migrations clear -c <component>
dplx db migrations clear -c <component> --force

Options:

-c, --component - Component name (required, or auto-detected if in component directory)
-f, --force - Skip confirmation prompt

Behavior:

Validates component exists
Counts migrations to be deleted
Shows warning about destructive action
Prompts for confirmation (unless --force)
Deletes all .cs and .Designer.cs files in Migrations folder
Deletes ModelSnapshot file

Example:

$ dplx db migrations clear -c catalog

⚠️  Clearing migrations for 'catalog'
    • 5 migration(s) will be deleted

⚠️  This action is DESTRUCTIVE and cannot be undone!
    Migration files will be permanently deleted.

Continue? [y/N]: y
✓ Cleared 5 migration(s) from catalog

With force flag:

$ dplx db migrations clear -c catalog --force

(--force flag used, skipping confirmation)
✓ Cleared 5 migration(s) from catalog

clear-all - Clear All Component Migrations

Clears migrations for ALL components in the repository. Requires explicit confirmation by typing 'clear-all'.

Usage:

dplx db migrations clear-all

Behavior:

Finds all components with migrations
Shows summary table with migration counts
Requires typing 'clear-all' to confirm (ignores --force for safety)
Clears each component sequentially
Reports success/failure for each

Example:

$ dplx db migrations clear-all

⚠️  This will clear migrations for ALL components:

Component          Migrations  Action
-----------------------------------------
  catalog                   5  ✓ Clear
  identity                  3  ✓ Clear
  prism                     8  ✓ Clear
  spatial                   4  ✓ Clear
-----------------------------------------
  Total: 20 migration(s) across 4 component(s)

⚠️  THIS ACTION CANNOT BE UNDONE!

Type 'clear-all' to confirm: clear-all

Clearing catalog...
✓ Cleared 5 migration(s) from catalog
Clearing identity...
✓ Cleared 3 migration(s) from identity
Clearing prism...
✓ Cleared 8 migration(s) from prism
Clearing spatial...
✓ Cleared 4 migration(s) from spatial

✓ Successfully cleared migrations for all 4 component(s)

init - Initialize Component with Base Migration

Creates an initial "Base" migration for a component that doesn't have migrations.

Usage:

dplx db migrations init -c <component>

Behavior:

Validates component exists
Checks if component has database support
Verifies no existing migrations
Creates migration named "Base"

Example:

$ dplx db migrations init -c catalog

Creating Base migration for catalog...
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
✓ Migration added successfully

If migrations already exist:

$ dplx db migrations init -c catalog

⚠️  Component 'catalog' already has 5 migration(s)
Use 'dplx db migrations reset' to clear and reinitialize

init-all - Initialize All Components Without Migrations

Creates Base migrations for all components that have database support but no migrations.

Usage:

dplx db migrations init-all

Behavior:

Finds all components with:
- Database project
- DbMigrator project
- Zero existing migrations
Creates Base migration for each
Reports success/failure

Example:

$ dplx db migrations init-all

Initializing 3 component(s) with Base migrations
-----------------------------------------

Initializing catalog...
✓ Migration added successfully

Initializing spatial...
✓ Migration added successfully

Initializing workflow...
✓ Migration added successfully

-----------------------------------------
✓ Successfully initialized 3 component(s)

reset - Clear and Reinitialize Component

Combines clear and init into a single command. Perfect for architectural refactors.

Usage:

dplx db migrations reset -c <component>
dplx db migrations reset -c <component> --force

Behavior:

Shows 2-step plan (clear → init)
Prompts for confirmation (unless --force)
Clears existing migrations
Creates new Base migration
Reports overall success

Example:

$ dplx db migrations reset -c prism

Resetting migrations for 'prism'
-----------------------------------------
Step 1: Clear 8 existing migration(s)
Step 2: Create new Base migration

⚠️  This will permanently delete existing migrations!

Continue with reset? [y/N]: y

Clearing existing migrations...
✓ Cleared 8 migration(s) from prism

Creating new Base migration...
Build started...
Build succeeded.
Done.
✓ Migration added successfully

✓ Successfully reset migrations for prism

If no existing migrations:

$ dplx db migrations reset -c catalog

Resetting migrations for 'catalog'
-----------------------------------------
No existing migrations found, initializing...
✓ Migration added successfully

Use Cases

1. Architectural Refactor (Reset Pattern)

Scenario: You've refactored the prism component's Passport system and want fresh migrations.

# Single command to clear and reinitialize
dplx db migrations reset -c prism

# Or step-by-step
dplx db migrations clear -c prism
dplx db migrations init -c prism

2. Fresh Start for All Components

Scenario: Starting a new development iteration and want to reset all migrations.

# Clear all existing migrations
dplx db migrations clear-all

# Initialize all components
dplx db migrations init-all

3. CI/CD Automation

Scenario: Automated pipeline that resets migrations for testing.

# Use --force to skip prompts
dplx db migrations reset -c catalog --force
dplx db migrations reset -c identity --force
dplx db migrations reset -c prism --force

4. New Component Setup

Scenario: Created a new component and need initial migration.

dplx db migrations init -c my-new-component

Safety Features

1. Confirmation Prompts

All destructive operations require confirmation:

# clear requires y/N
Continue? [y/N]:

# clear-all requires typing exact phrase
Type 'clear-all' to confirm:

# reset requires y/N
Continue with reset? [y/N]:

2. Force Flag Behavior

--force skips confirmation for clear and reset
--force is ignored for clear-all (always requires typing 'clear-all')
Use with caution in automated scripts

3. Validation

All commands validate:

Component exists
Component has database support (for init/reset)
Migration paths are correct
Similar component suggestions if name is mistyped

File Locations

Migrations are stored in:

engines/[component]/src/Acsis.Dynaplex.Engines.[Component].Database/Migrations/

Files affected:

YYYYMMDDHHMMSS_MigrationName.cs - Migration code
YYYYMMDDHHMMSS_MigrationName.Designer.cs - Migration metadata
[Component]DbModelSnapshot.cs - Current model snapshot

Integration with Existing Commands

These new commands complement existing migration commands:

# Check what needs migrations
dplx db migrations pending

# Add a specific migration (manual)
dplx db migrations add -c catalog -n AddProductTable

# List existing migrations
dplx db migrations list -c catalog

# Remove last migration
dplx db migrations remove -c catalog

# Clear all migrations (NEW)
dplx db migrations clear -c catalog

# Initialize with Base migration (NEW)
dplx db migrations init -c catalog

# Reset migrations (NEW)
dplx db migrations reset -c catalog

Best Practices

1. Always Commit Before Clearing

# Ensure all changes are committed
git status

# Clear migrations
dplx db migrations clear -c catalog

2. Reset Pattern for Refactors

When doing architectural refactors:

# 1. Commit your code changes
git add .
git commit -m "Refactor: New Passport system"

# 2. Reset migrations
dplx db migrations reset -c prism

# 3. Verify migration
dplx db migrations list -c prism

# 4. Test migration
dplx db database update -c prism

# 5. Commit migration
git add engines/prism/src/Acsis.Dynaplex.Engines.Prism.Database/Migrations/
git commit -m "chore: Reset prism migrations for new Passport system"

3. Coordinate with Team

Before running clear-all:

Notify team members
Ensure everyone has committed their work
Coordinate timing
Document the reason in commit message

4. Use init-all for Fresh Clones

After cloning the repository:

# Build everything first
dotnet build

# Initialize any components missing migrations
dplx db migrations init-all

Error Handling

Component Doesn't Exist

$ dplx db migrations clear -c catalogg

Component 'catalogg' does not exist
Did you mean one of these?
  • catalog
  • category

No Database Support

$ dplx db migrations init -c doc-web

Component 'doc-web' doesn't have database support enabled
Did you create it with --no-db?

No Migrations to Clear

$ dplx db migrations clear -c catalog

Component 'catalog' has no migrations to clear

Troubleshooting

Issue: "Missing required project files"

Cause: Component doesn't have .Database or .DbMigrator project

Solution:

# Check component structure
ls engines/my-component/src/

# Should see:
# Acsis.Dynaplex.Engines.MyComponent.Database/
# Acsis.Dynaplex.Engines.MyComponent.DbMigrator/

Issue: Clear-all hangs

Cause: Waiting for confirmation input

Solution: Type exactly clear-all (not just 'y')

Issue: Reset fails on init step

Cause: Database context has compilation errors after clear

Solution:

Fix compilation errors in Database project
Run dplx db migrations init -c <component> manually

Implementation Details

Helper Functions

getMigrationsDir: Resolves migration directory path

let getMigrationsDir config componentName =
    let componentPascal = Config.toPascalCase componentName
    Path.Combine(
        config.ComponentsDir,
        componentName,
        "src",
        $"Acsis.Dynaplex.Engines.{componentPascal}.Database",
        "Migrations"
    )

countMigrations: Counts migration files (excludes ModelSnapshot)

let countMigrations config componentName =
    match getMigrationFiles config componentName with
    | Ok files -> files.Length / 2  // Each migration has 2 files
    | Error _ -> 0

Confirmation Prompts

Simple Y/N:

let promptConfirmation (message: string) =
    Console.printWarning message
    printf "Continue? [y/N]: "
    let response = System.Console.ReadLine()
    response.Trim().ToLower() = "y"

Type to Confirm:

let promptTypeToConfirm (confirmText: string) (message: string) =
    Console.printWarning message
    printf $"Type '{confirmText}' to confirm: "
    let response = System.Console.ReadLine()
    response.Trim() = confirmText

Documentation

Dynaplex Migration Management Commands

Overview

New Commands

clear - Clear Migrations for a Component

clear-all - Clear All Component Migrations

init - Initialize Component with Base Migration

init-all - Initialize All Components Without Migrations

reset - Clear and Reinitialize Component

Use Cases

1. Architectural Refactor (Reset Pattern)

2. Fresh Start for All Components

3. CI/CD Automation

4. New Component Setup

Safety Features

1. Confirmation Prompts

2. Force Flag Behavior

3. Validation

File Locations

Integration with Existing Commands

Best Practices

1. Always Commit Before Clearing

2. Reset Pattern for Refactors

3. Coordinate with Team

4. Use init-all for Fresh Clones

Error Handling

Component Doesn't Exist

No Database Support

No Migrations to Clear

Troubleshooting

Issue: "Missing required project files"

Issue: Clear-all hangs

Issue: Reset fails on init step

Implementation Details

Helper Functions

Confirmation Prompts

See Also