docs

Author: DatGuyJonathan

apps/framework-cli/src/framework/core/infrastructure_map.rs

@@ -1749,8 +1749,10 @@ impl InfrastructureMap {
                         // Detect engine change (e.g., MergeTree -> ReplacingMergeTree)
                         let engine_changed = table.engine != target_table.engine;
 
-                        // Detect cluster name change
-                        let cluster_changed = table.cluster_name != target_table.cluster_name;
+                        // Note: We intentionally do NOT check for cluster_name changes here.
+                        // cluster_name is a deployment directive (how to run DDL), not a schema property.
+                        // The inframap will be updated with the new cluster_name value, and future DDL
+                        // operations will use it, but changing cluster_name doesn't trigger operations.
 
                         let order_by_change = if order_by_changed {
                             OrderByChange {
@@ -1792,11 +1794,11 @@ impl InfrastructureMap {
                         // since ClickHouse requires the full column definition when modifying TTL
 
                         // Only process changes if there are actual differences to report
+                        // Note: cluster_name changes are intentionally excluded - they don't trigger operations
                         if !column_changes.is_empty()
                             || order_by_changed
                             || engine_changed
                             || indexes_changed
-                            || cluster_changed
                         {
                             // Use the strategy to determine the appropriate changes
                             let strategy_changes = strategy.diff_table_update(

apps/framework-cli/src/infrastructure/olap/clickhouse.rs

@@ -1899,7 +1899,10 @@ impl OlapOperations for ConfiguredDBClient {
                 indexes,
                 database: Some(database),
                 table_ttl_setting,
-                cluster_name: None, // Cluster info not extracted from introspection
+                // cluster_name is always None from introspection because ClickHouse doesn't store
+                // the ON CLUSTER clause - it's only used during DDL execution and isn't persisted
+                // in system tables. Users must manually specify cluster in their table configs.
+                cluster_name: None,
             };
             debug!("Created table object: {:?}", table);
 

apps/framework-cli/src/infrastructure/olap/clickhouse/diff_strategy.rs

@@ -304,17 +304,11 @@ impl TableDiffStrategy for ClickHouseTableDiffStrategy {
             })];
         }
 
-        // Check if cluster has changed
-        if before.cluster_name != after.cluster_name {
-            log::warn!(
-                "ClickHouse: cluster changed for table '{}' (from {:?} to {:?}), requiring drop+create",
-                before.name, before.cluster_name, after.cluster_name
-            );
-            return vec![
-                OlapChange::Table(TableChange::Removed(before.clone())),
-                OlapChange::Table(TableChange::Added(after.clone())),
-            ];
-        }
+        // Note: cluster_name changes are intentionally NOT treated as requiring drop+create.
+        // cluster_name is a deployment directive (how to run DDL) rather than a schema property
+        // (what the table looks like). When cluster_name changes, future DDL operations will
+        // automatically use the new cluster_name via the ON CLUSTER clause, but the table
+        // itself doesn't need to be recreated.
 
         // Check if PARTITION BY has changed
         if before.partition_by != after.partition_by {
@@ -1284,16 +1278,9 @@ mod tests {
 
         let changes = strategy.diff_table_update(&before, &after, vec![], order_by_change, "local");
 
-        // Should return DROP + CREATE (like ORDER BY changes)
-        assert_eq!(changes.len(), 2);
-        assert!(matches!(
-            changes[0],
-            OlapChange::Table(TableChange::Removed(_))
-        ));
-        assert!(matches!(
-            changes[1],
-            OlapChange::Table(TableChange::Added(_))
-        ));
+        // cluster_name is a deployment directive, not a schema property
+        // Changing it should not trigger any operations
+        assert_eq!(changes.len(), 0);
     }
 
     #[test]
@@ -1314,16 +1301,9 @@ mod tests {
 
         let changes = strategy.diff_table_update(&before, &after, vec![], order_by_change, "local");
 
-        // Should return DROP + CREATE (like ORDER BY changes)
-        assert_eq!(changes.len(), 2);
-        assert!(matches!(
-            changes[0],
-            OlapChange::Table(TableChange::Removed(_))
-        ));
-        assert!(matches!(
-            changes[1],
-            OlapChange::Table(TableChange::Added(_))
-        ));
+        // cluster_name is a deployment directive, not a schema property
+        // Changing it should not trigger any operations
+        assert_eq!(changes.len(), 0);
     }
 
     #[test]
@@ -1344,16 +1324,9 @@ mod tests {
 
         let changes = strategy.diff_table_update(&before, &after, vec![], order_by_change, "local");
 
-        // Should return DROP + CREATE (like ORDER BY changes)
-        assert_eq!(changes.len(), 2);
-        assert!(matches!(
-            changes[0],
-            OlapChange::Table(TableChange::Removed(_))
-        ));
-        assert!(matches!(
-            changes[1],
-            OlapChange::Table(TableChange::Added(_))
-        ));
+        // cluster_name is a deployment directive, not a schema property
+        // Changing it should not trigger any operations
+        assert_eq!(changes.len(), 0);
     }
 
     #[test]

apps/framework-docs/llm-docs/python/table-setup.md

@@ -449,6 +449,39 @@ name = "default"
 
 **Production:** Cluster names must match your ClickHouse `remote_servers` configuration.
 
+#### Understanding `cluster` as a Deployment Directive
+
+The `cluster` field is a **deployment directive** that controls HOW Moose runs DDL operations, not WHAT the table looks like:
+
+- **Changing `cluster` won't recreate your table** - it only affects future DDL operations (CREATE, ALTER, etc.)
+- **ClickHouse doesn't store cluster information** - the `ON CLUSTER` clause is only used during DDL execution
+- **`moose init --from-remote` & `moose db pull` cannot detect cluster names** - ClickHouse system tables don't preserve this information
+
+**If you're importing existing tables that were created with `ON CLUSTER`:**
+1. Run `moose init --from-remote` to generate your table definitions
+2. Manually add `cluster="your_cluster_name"` to the generated table configs
+3. Future migrations and DDL operations will correctly use `ON CLUSTER`
+
+**Example workflow:**
+```python
+# After moose init --from-remote generates this:
+my_table = OlapTable[MySchema](
+    "MyTable",
+    OlapConfig(
+        order_by_fields=["id"]
+    )
+)
+
+# Manually add cluster if you know it was created with ON CLUSTER:
+my_table = OlapTable[MySchema](
+    "MyTable",
+    OlapConfig(
+        order_by_fields=["id"],
+        cluster="my_cluster"  # Add this line
+    )
+)
+```
+
 ### S3Queue Engine Tables
 
 The S3Queue engine enables automatic processing of files from S3 buckets as they arrive.

apps/framework-docs/llm-docs/typescript/table-setup.md

@@ -278,6 +278,33 @@ name = "default"
 
 **Production:** Cluster names must match your ClickHouse `remote_servers` configuration.
 
+#### Understanding `cluster` as a Deployment Directive
+
+The `cluster` field is a **deployment directive** that controls HOW Moose runs DDL operations, not WHAT the table looks like:
+
+- **Changing `cluster` won't recreate your table** - it only affects future DDL operations (CREATE, ALTER, etc.)
+- **ClickHouse doesn't store cluster information** - the `ON CLUSTER` clause is only used during DDL execution
+- **`moose init --from-remote` & `moose db pull` cannot detect cluster names** - ClickHouse system tables don't preserve this information
+
+**If you're importing existing tables that were created with `ON CLUSTER`:**
+1. Run `moose init --from-remote` to generate your table definitions
+2. Manually add `cluster: "your_cluster_name"` to the generated table configs
+3. Future migrations and DDL operations will correctly use `ON CLUSTER`
+
+**Example workflow:**
+```typescript
+// After moose init --from-remote generates this:
+export const MyTable = new OlapTable<MySchema>("MyTable", {
+  orderByFields: ["id"]
+});
+
+// Manually add cluster if you know it was created with ON CLUSTER:
+export const MyTable = new OlapTable<MySchema>("MyTable", {
+  orderByFields: ["id"],
+  cluster: "my_cluster"  // Add this line
+});
+```
+
 ### S3Queue Engine Tables
 
 The S3Queue engine allows you to automatically process files from S3 buckets as they arrive.

apps/framework-docs/src/pages/moose/configuration.mdx

@@ -246,6 +246,9 @@ native_port = 9000
 # ClickHouse cluster configuration for replicated tables (optional)
 # Define clusters for use with ON CLUSTER DDL operations and distributed tables
 # In local dev, Moose creates single-node clusters. In production, names must match your ClickHouse remote_servers config.
+#
+# Note: Cluster names are deployment directives that control HOW Moose runs DDL (via ON CLUSTER),
+# not schema properties. Changing cluster names in your table configs won't trigger table recreation.
 # [[clickhouse_config.clusters]]
 # name = "default"
 # [[clickhouse_config.clusters]]

apps/framework-docs/src/pages/moose/olap/planned-migrations.mdx

@@ -84,6 +84,8 @@ You will commit the entire `migrations/` directory to version control, and Moose
 
 <Callout type="info" title="Why edit the plan?" compact>
 Moose makes some assumptions about your schema changes, such as renaming a column instead of dropping and adding. You can modify the plan to override these assumptions.
+
+Note: The `cluster` field controls which ClickHouse cluster Moose uses for `ON CLUSTER` DDL operations. It's a deployment directive, not a schema property, so changing it won't trigger table recreation.
 </Callout>
 
 Open `plan.yaml` in your PR. Operations are ordered (teardown first, then setup) to avoid dependency issues. Review like regular code. You can also edit the plan to override the default assumptions Moose makes.