The migrations/plan.yaml file is the declarative source of truth for pending database changes in Moose. It defines the exact sequence of operations Moose will execute to transition your production database to the desired state.
This reference documents the file structure, supported operations, and data type definitions found in generated plans.
A migration plan is a YAML document with the following root properties:
| Field | Type | Description |
|---|---|---|
created_at | String (ISO 8601) | Timestamp when the plan was generated. Used for versioning and audit trails. |
operations | Array | Ordered list of migration operations to execute. |
created_at: 2025-01-14T10:30:00Zoperations: - DropTableColumn: ... - AddTableColumn: ...Operations are the atomic units of change in a migration plan. Moose executes them sequentially.
CreateTableCreates a new ClickHouse table.
- CreateTable: table: name: <string> columns: [<ColumnDefinition>] order_by: [<string>] engine: <EngineType>| Field | Description |
|---|---|
name | Name of the table to create. |
columns | List of column definitions. |
order_by | Array of column names used for the sorting key. |
engine | ClickHouse table engine (e.g., MergeTree, ReplacingMergeTree). |
Permanently removes a table and all its data.
- DropTable: table: <string>| Field | Description |
|---|---|
table | Name of the table to drop. |
Adds a new column to an existing table.
- AddTableColumn: table: <string> column: <ColumnDefinition>| Field | Description |
|---|---|
table | Target table name. |
column | Full definition of the new column. |
Removes a column from a table. Destructive operation.
- DropTableColumn: table: <string> column_name: <string>| Field | Description |
|---|---|
table | Target table name. |
column_name | Name of the column to remove. |
Renames a column while preserving its data.
- RenameTableColumn: table: <string> before_column_name: <string> after_column_name: <string>| Field | Description |
|---|---|
table | Target table name. |
before_column_name | Current name of the column. |
after_column_name | New name for the column. |
Changes a column's data type or properties.
- ModifyTableColumn: table: <string> before_column: <ColumnDefinition> after_column: <ColumnDefinition>| Field | Description |
|---|---|
table | Target table name. |
before_column | Snapshot of the column state before modification. |
after_column | Desired state of the column. |
Executes arbitrary SQL statements. Used for custom migrations, backfills, or unsupported operations.
- RawSql: sql: [<string>] description: <string>| Field | Description |
|---|---|
sql | List of SQL statements to execute in order. |
description | Human-readable explanation of the operation's purpose. |
Every column in a CreateTable, AddTableColumn, or ModifyTableColumn operation follows this structure:
name: <string>data_type: <DataType>required: <boolean>unique: <boolean>primary_key: <boolean>default: <string> | nullcomment: <string> | nullannotations: [[<string>, <boolean>]]| Property | Type | Description |
|---|---|---|
name | String | Column identifier. |
data_type | Type | ClickHouse data type (see below). |
required | Boolean | If true, the column is NOT NULL. |
unique | Boolean | (Metadata) Whether the field is marked unique in the model. |
primary_key | Boolean | Whether the field is part of the primary key. |
default | String | Default value expression (e.g., 'active', 0, now()). |
Moose maps data model types to ClickHouse types in the plan.
| Type | YAML Representation |
|---|---|
| String | String |
| Boolean | Boolean |
| Integer | Int8, Int16, Int32, Int64, UInt8... |
| Float | Float32, Float64 |
| Date | Date, Date32, DateTime |
| UUID | UUID |
Wraps another type to allow NULL values.
data_type: Nullable: nullable: StringList of values of a single type.
data_type: Array: elementType: String elementNullable: falseFixed set of string or integer values.
data_type: Enum: name: "Status" values: - name: "ACTIVE" value: { String: "active" } - name: "INACTIVE" value: { String: "inactive" }Hierarchical data structures.
data_type: Nested: name: "Address" columns: [<ColumnDefinition>] jwt: falseStorage optimization for columns with few unique values.
data_type: LowCardinality: nullable: String