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.

Version Bump Detection

When you change the version field on an OlapTable, Moose recognizes this as a version bump rather than an independent drop + create. It prompts you for two decisions:

1. Backfill — whether to copy data from the old table to the new one via INSERT INTO ... SELECT (offered only when schemas are compatible)
2. Keep or drop — whether to retain the old table (marked EXTERNALLY_MANAGED) or drop it after migration

Version bump  Detected 1 version bump(s). The old table(s) can be kept or dropped.Version bump  `events_1_0` (v1.0) → `events_2_0` (v2.0)Backfill data from `events_1_0` into `events_2_0`? [Y/n]> yKeep old table `events_1_0`? (will be marked EXTERNALLY_MANAGED) [y/N]> n

Moose executes operations in the correct order: create the new table, run the backfill, then drop the old table (if not retained). See Schema Versioning for the full version bump workflow.

In agent mode (moose dev --agent), these prompts are published to the MCP server instead of stdin. An AI agent answers them by calling the respond_to_prompt tool at the MCP endpoint.

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.