Automatic Migrations

Automatic migrations are a schema evolution mechanism in Moose that automatically detects changes in your data models and applies them to the underlying database in real-time. This system is designed primarily for local development.

Command

Automatic migrations are enabled implicitly when running the development server:

moose dev

Production Usage

While technically possible to use automatic migrations in production environments, it is strongly discouraged.

Production deployments should always use Planned Migrations to ensure schema changes are reviewed, tested, and safe.

By default, moose prod blocks startup when destructive changes are detected without a reviewed plan.yaml. See Production Safety Gate for details. To override at runtime without changing config, set MOOSE_MIGRATION_CONFIG__PROD_AUTO_ALLOW_DESTRUCTIVE=true.

Behavior

When active, the auto-inference engine performs the following cycle:

1. Monitor: Watches the file system for changes in exported table definitions in your data model files.
2. Diff: Compares the code-defined schema against the actual schema of the running ClickHouse instance.
3. Generate: Creates the necessary SQL DDL statements to reconcile the difference.
4. Apply: Executes the SQL statements immediately against the database.

Operation Reference

The following table describes how code changes are translated into database operations by the auto-inference engine.

Confirmation Prompts

Column Rename Detection

When you rename a field, Moose uses heuristic analysis (name similarity, type matching) to detect likely renames. Instead of silently dropping the old column and adding a new one, it prompts you:

Rename (1/1): `events`.`user_id` → `uid` (confidence: 0.82)  y=rename  n=drop+create  c=cancel

• y (default): Apply as a RENAME COLUMN — data is preserved.
• n: Treat as a destructive drop + add — old column data is lost.
• c: Cancel the entire change cycle.

To skip prompts and auto-accept all renames, pass --yes-rename or set MOOSE_ACCEPT_RENAME=1.

Destructive Operations

When the detected changes contain destructive operations (table drops, column removals, view removals, materialized view removals, table recreates), Moose pauses and asks for confirmation before proceeding:

⚠  1 destructive change(s) — type y to accept, n to reject

If you reject, the change cycle is skipped — your code change stays, and Moose will re-prompt on the next file save. To skip destructive prompts, pass --yes-destructive or set MOOSE_ACCEPT_DESTRUCTIVE=1. Use --yes-all to skip both rename and destructive prompts.

Configuration

Automatic migrations rely on the olap feature flag in your project configuration.

[features]olap = true # enabled by default

CLI Output Reference

The CLI communicates migration actions via standard output prefixes in the terminal.

Example Output

⢹ Processing Infrastructure changes from file watcher             ~ Table page_views:                  Column changes:                    + user_agent: String                    - referrer: String                    ~ timestamp: DateTime -> DateTime64(3)

See Also

• Planned Migrations - The reference for production-grade migration workflows.
• Schema Change Reference - Detailed breakdown of migration plan objects.
• Serverless (moose migrate) - Commands for managing migrations manually.