moose prod
The Moose Runtime deployment model (invoked via moose prod) includes an automatic migration runner that executes planned changes during the application boot sequence.
Overview
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. |
Command Reference
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.
Execution Lifecycle
When moose prod starts, it performs the following sequence:
- Load Plan: Reads
migrations/plan.yamlfrom the deployment artifact. - Check Code Consistency: Verifies that the running application code matches
local_infra_map.json. If not, it aborts to prevent deploying code that doesn't match the plan. - Check Database Drift: Connects to ClickHouse and compares the current schema against
remote_state.json. If drift is detected, it aborts. - Execute Migration: Applies the operations defined in
plan.yaml. - Start Services: Once migrations succeed, the Ingestion API, Consumption API, and Streaming workers are started.
Failure Modes
| 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. |
Boreal Hosting
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.
See Also
- Planned Migrations — Generate the migration plan files
- moose migrate — Manual CLI migrations for serverless deployments