warn-citus-distributed-ddl

What It Detects

ALTER on a Citus distributed table propagates to every shard on every worker node.

Why It's Dangerous

A distributed table is a set of shards spread across worker nodes, and Citus propagates DDL to all of them — so one line in the migration becomes a lock on the coordinator plus a lock per shard across the cluster, and the statement is not finished until the slowest worker is. Some forms are refused outright rather than propagated: changing the distribution column answers "cannot execute ALTER TABLE command involving partition column" and the migration stops there.

Bad Example

-- orders is distributed by tenant_id across 32 shards
ALTER TABLE orders ALTER COLUMN tenant_id TYPE bigint;
-- ERROR: cannot execute ALTER TABLE command involving partition column

Good Example

-- See what the statement would fan out to before writing it:
SELECT table_name, citus_table_type, distribution_column, shard_count
FROM citus_tables;

Configuration

Disable this rule:

# .migrationpilotrc.yml
rules:
  MP107: false

Or change its severity:

# .migrationpilotrc.yml
rules:
  MP107:
    severity: warning