moose migrate
The CLI deployment model relies on the moose migrate CLI command to execute planned schema changes. This gives you explicit control over when migrations run, which is essential for architectures where Moose OLAP is integrated as a library rather than a standalone server (e.g. as a library in a Python or TypeScript application).
Overview
In serverless or library-based deployments, MooseStack does not control the application runtime. Therefore, migrations must be triggered externally, typically as a step in a CI/CD pipeline or a manual administrative action.
| Feature | Description |
|---|---|
| Manual Control | Migrations run only when you explicitly execute the command. |
| CI/CD Integration | Designed to run as a discrete step in deployment pipelines (e.g., GitHub Actions). |
| Drift Protection | Validates remote_state.json against the target database before execution. |
| Direct Connection | Connects directly to ClickHouse using a connection string. |
Command Reference
moose migrate --clickhouse-url <CONNECTION_STRING>Options
| Option | Description | Required |
|---|---|---|
--clickhouse-url | The full connection string to the target ClickHouse database (e.g., clickhouse://user:pass@host:9440/db). | Yes |
Execution Lifecycle
When moose migrate is executed:
- Load Plan: Reads
migrations/plan.yamlfrom the current directory. - Check Database Drift: Connects to the provided ClickHouse URL and compares the current schema against
remote_state.json. - Abort on Drift: If the database state does not match the snapshot, the process exits with an error code.
- Execute Migration: Applies the operations defined in
plan.yamlsequentially. - Report Success: Exits with code 0 if all operations succeed.
Failure Modes
| Condition | Outcome | Resolution |
|---|---|---|
| Drift Detected | Command fails (exit code 1). | Regenerate the plan against the current production DB and retry. |
| Connection Error | Command fails (exit code 1). | Check network connectivity and credentials in the connection string. |
| SQL Error | Command fails (exit code 1). | Fix the problematic operation in plan.yaml or the database state and retry. |
CI/CD Example
This command is typically used in a deployment pipeline before updating the application code.
# Example GitHub Actions step- name: Apply Migrations run: moose migrate --clickhouse-url "$CLICKHOUSE_URL" env: CLICKHOUSE_URL: ${{ secrets.CLICKHOUSE_URL }}See Also
- Planned Migrations — Generating the plan files
- moose prod (Moose Runtime Migrations) — Automatic migrations for Moose Runtime deployments
- Migration Modes — Overview of schema evolution modes