divine-mobile: Skill for Claude Code

ClickHouse Cloud Multi-Table RENAME Limitation

Problem

ClickHouse Cloud (SharedMergeTree engine) does not support renaming multiple tables in a single RENAME TABLE statement, which is a common pattern for atomic table swaps in schema migrations. Self-hosted ClickHouse supports this, so migrations that work locally or on self-hosted instances will fail on ClickHouse Cloud.

Context / Trigger Conditions

• Error message: "Database X is Shared, it does not support renaming of multiple tables in single query"
• Error code: 48
• Using golang-migrate (or similar) with ClickHouse Cloud
• Migration SQL contains a pattern like:

  RENAME TABLE db.original TO db.original_old,
               db.new_version TO db.original;
  

• Migration works in staging (self-hosted ClickHouse) but fails in production (ClickHouse Cloud)

Solution

Prevention: Write ClickHouse Cloud-compatible migrations

Instead of multi-table RENAME:

-- BAD: This fails on ClickHouse Cloud
RENAME TABLE nostr.my_table TO nostr.my_table_old,
             nostr.my_table_v2 TO nostr.my_table;

Use separate RENAME statements:

-- GOOD: Split into individual operations
RENAME TABLE nostr.my_table TO nostr.my_table_old;
RENAME TABLE nostr.my_table_v2 TO nostr.my_table;

Note: This loses atomicity, but ClickHouse Cloud doesn't support the atomic version anyway.

Recovery: Fix a dirty migration that already failed

1. Check the current state — identify which tables exist and what state they're in:

   SHOW TABLES LIKE '%my_table%';
   DESCRIBE TABLE nostr.my_table;       -- Check if it has old or new schema
   DESCRIBE TABLE nostr.my_table_v2;    -- Check if the new table was created
   

2. Complete the migration manually with separate renames:

   -- If both original and v2 exist (RENAME never executed):
   RENAME TABLE nostr.my_table TO nostr.my_table_old;
   RENAME TABLE nostr.my_table_v2 TO nostr.my_table;
   DROP TABLE IF EXISTS nostr.my_table_old;
   -- Recreate any views that were dropped