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.
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> --saveKey Benefits:
plan.yaml) that won't change at runtime.remote_state.json) ensure the DB hasn't changed since the plan was created.DropColumn, AddTable) before it runs, and you can edit the plan to override Moose's assumptions.The lifecycle consists of four distinct stages:
moose generate migration --save ...migrations/plan.yaml file and commit it to Git.moose migrate ...
## or if using the Moose Runtime
moose prodRunning the generation command produces three files in the directory.
migrations/| File | Purpose |
|---|---|
plan.yaml | The imperative list of operations (e.g., AddTableColumn) to execute. See Plan Reference. |
remote_state.json | A snapshot of the production database schema at the time of generation. Used to detect drift. |
local_infra_map.json | A snapshot of your local code's schema definitions. Used to validate the plan against the code. |
Planned migrations are enabled via the ddl_plan feature flag in your project configuration.
[features]olap = trueddl_plan = trueThe moose generate migration command accepts different arguments depending on your deployment model for applying changes.
Connect to the Admin API of the running service.
moose generate migration --url <ADMIN_API_URL> --token <ADMIN_TOKEN> --save| Option | Description |
|---|---|
--url | The endpoint of your production Moose Admin API. |
--token | The authentication token for the Admin API. |
--save | Writes the generated plan to the migrations/ directory. Without this, it performs a dry run. |
Connect directly to the ClickHouse database.
moose generate migration --clickhouse-url <CLICKHOUSE_CONNECTION_STRING> --save| Option | Description |
|---|---|
--clickhouse-url | Direct connection string (e.g., clickhouse://user:pass@host:9440/db). |
--save | Writes the generated plan to the migrations/ directory. Without this, it performs a dry run. |
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:
moose generate writes the current DB state to remote_state.json.moose migrate (serverless) or moose prod (server runtime) compares remote_state.json with the current DB state.Resolution: To fix drift, you must regenerate the plan against the new production state.
# Regenerate to accept the new state
moose generate migration ... --saveplan.yaml.moose migrate command.