---
name: "postgres-citus-distributed-tables"
description: "Scale PostgreSQL horizontally across worker nodes for multi-tenant and real-time analytics."
metadata:
  author: "Citus Data"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "shard table with citus"
  - "create distributed table"
  - "configure citus reference table"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Citus Distributed PostgreSQL Sharding

Distributes relational tables across a Citus cluster using hash distribution columns, co-located foreign keys, reference tables, distributed transactions, and parallel executor query optimization.

## When to Invoke
Invoke this skill whenever you need to:
- shard table with citus
- create distributed table
- configure citus reference table

## Execution SOP & Rules
1. Execute SELECT create_distributed_table('orders', 'tenant_id') to shard across the cluster.
2. Design composite primary keys containing the distribution column (tenant_id, id).
3. Use SELECT create_reference_table('countries') for small read-heavy lookup tables.
4. Inspect distributed execution plans using EXPLAIN (VERBOSE) to check for remote distributed query pushes.

## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.