Planned Migrations

Planned migrations are the production-grade schema evolution mechanism in MooseStack. Unlike Automatic Migrations, this system separates the generation of schema changes from their execution, introducing a reviewable artifact (the plan) into your deployment lifecycle.

Command

Generate a migration plan by comparing your local code against a production environment:

# For Server Runtime (connect to Moose Admin API)
moose generate migration --url <ADMIN_API_URL> --token <ADMIN_TOKEN> --save
 
# For Serverless (connect to ClickHouse directly)
moose generate migration --clickhouse-url <CLICKHOUSE_CONNECTION_STRING> --save

Key Benefits:

• Deterministic: The plan is a static file (plan.yaml) that won't change at runtime.
• Drift Detection: Snapshots (remote_state.json) ensure the DB hasn't changed since the plan was created.
• Reviewable: You can audit every operation (e.g., DropColumn, AddTable) before it runs, and you can edit the plan to override Moose's assumptions.
• Versioned: Commit plans to Git to create a permanent audit trail.

Workflow

The lifecycle consists of four distinct stages:

1. Code Change — Modify your data models (tables, views) in your Moose project.

2. Generation — Run the CLI to compare your code against production.

   Terminal

   Copy code

   moose generate migration --save ...

3. Review — Inspect the generated migrations/plan.yaml file and commit it to Git.

4. Application — Execute the plan during deployment (if using Moose Runtime), manually via the CLI or your own CI/CD pipeline (if using Serverless).

   Terminal

   Copy code

   moose migrate ...
    
   ## or if using the Moose Runtime
   moose prod

Generated Artifacts

Running the generation command produces three files in the migrations/ directory.

Configuration

Planned migrations are active whenever a plan.yaml file exists in the migrations/ directory. No feature flag is required -- if the file is present, moose prod applies the static plan; if it is absent, Moose falls back to dynamic OLAP reconciliation.

[features]olap = true

Production Safety Gate

By default, moose prod refuses to start if the computed infrastructure diff contains destructive operations (table drops, column drops, table recreates, view removals) and no plan.yaml is present. This prevents accidental data loss when deploying schema changes that haven't been reviewed.

[migration_config]# Default: false — destructive changes blocked unless a plan.yaml is presentprod_auto_allow_destructive = false

When startup is blocked, the error message lists every destructive operation and suggests two remediation paths:

1. Run moose generate migration --save to create a reviewed plan.yaml.
2. Set prod_auto_allow_destructive = true in moose.config.toml (or MOOSE_MIGRATION_CONFIG__PROD_AUTO_ALLOW_DESTRUCTIVE=true as an environment variable) to opt out of the safety gate.

Command Options

The moose generate migration command accepts different arguments depending on your deployment model for applying changes.

via Moose Runtime (moose prod)

Connect to the Admin API of the running service.

moose generate migration --url <ADMIN_API_URL> --token <ADMIN_TOKEN> --save

via Serverless (moose migrate)

Connect directly to the ClickHouse database.

moose generate migration --clickhouse-url <CLICKHOUSE_CONNECTION_STRING> --save

Confirmation flags

These flags control the interactive confirmation prompts during plan generation:

Drift Detection

Drift occurs when the target database's schema changes between the time you generate a plan and the time you apply it.

How it works:

1. moose generate writes the current DB state to remote_state.json.
2. moose migrate (serverless) or moose prod (server runtime) compares remote_state.json with the current DB state.
3. If they differ (hash mismatch), the migration aborts.

Resolution: To fix drift, you must regenerate the plan against the new production state.

# Regenerate to accept the new state
moose generate migration ... --save

See Also

• Migration Plan Reference - Detailed syntax of plan.yaml.
• Manual Execution - Execute migration plans manually via the moose migrate command.
• Runtime Execution - Execute migration plans automatically via the Moose Server Runtime.