The Moose Runtime deployment model (invoked via moose prod) includes an automatic migration runner that executes planned changes during the application boot sequence.
When running as a full server, Moose orchestrates the entire lifecycle of your data stack. Migrations are treated as a prerequisite for starting the application: the server will not accept traffic or process data until the database schema matches the code definition.
| Feature | Description |
|---|---|
| Automatic Execution | Migrations run automatically when the moose prod command starts. |
| Drift Protection | The server validates the database state against remote_state.json before applying changes. |
| Code Validation | The server ensures the deployed code matches local_infra_map.json to prevent mismatches. |
| Zero-Touch | No separate CLI commands or CI/CD steps are required to apply migrations. |
The migration logic is embedded within the production server start command.
moose prodEnvironment Variables:
The server requires access to the ClickHouse database, typically configured via moose.config.toml or environment variables overridden at runtime.
When moose prod starts, it performs the following sequence:
migrations/plan.yaml from the deployment artifact.local_infra_map.jsonremote_state.json. If drift is detected, it aborts.plan.yaml.| Condition | Outcome | Resolution |
|---|---|---|
| Drift Detected | Server fails to start. | Regenerate the plan against the current production DB and redeploy. |
| Plan Mismatch | Server fails to start. | Ensure the migrations/ directory matches the code in your deployment artifact. |
| Migration Error | Server fails to start. | Fix the schema issue or plan file, then redeploy. |
If you are using Boreal Hosting, this process is handled automatically. The platform ensures that your application only becomes healthy once moose prod has successfully completed the migration phase.