From d20ffac0cef8c175e7d2bbbbba96b74975817331 Mon Sep 17 00:00:00 2001 From: Kuroda Kayn Date: Sat, 4 Jul 2026 03:31:05 +0800 Subject: [PATCH] docs(database): define Citus validation cluster setup Phase 6 needs clearer criteria before horizontal scaling work can start. Document the validation cluster topology, reviewed Citus DDL rehearsal, and required operational runbooks. This keeps the deferred Citus operation plan actionable without starting production migration work. --- doc/plan/database-optimization.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/plan/database-optimization.md b/doc/plan/database-optimization.md index 5f5563cc..e39ca45b 100644 --- a/doc/plan/database-optimization.md +++ b/doc/plan/database-optimization.md @@ -134,7 +134,7 @@ Atomic commit guidance: #### Phase 6: Citus Distributed PostgreSQL Operation -- [ ] Set up a Citus validation cluster when horizontal scaling is actually needed. +- [ ] Set up a Citus validation cluster when horizontal scaling is actually needed, with coordinator/worker topology, tenant colocation DDL, reference-table rehearsal, and rollback/rebuild runbook documented before real tenant migration. - [ ] Import synthetic or new workspaces for validation. - [ ] Configure PgBouncer, monitoring, backup, and failure drills for Citus coordinator/workers. - [ ] Govern worker concurrency by `workspace_id`. @@ -523,7 +523,9 @@ Goal: operate Citus as a future PostgreSQL-compatible distributed runtime for ne Work items: -- Set up a Citus validation cluster when horizontal scaling is actually needed. +- Set up a Citus validation cluster only after horizontal scaling is justified, using a non-production coordinator and at least two worker nodes. +- Apply the reviewed Phase 5 DDL shape in the validation cluster: distribute `workspaces` first, colocate tenant tables by `workspace_id`, rehearse `users` and small global dimensions as reference-table candidates, and keep control-domain tables outside the distributed group until a routing boundary requires otherwise. +- Document the validation cluster bootstrap, rollback, rebuild, backup-restore, and teardown runbooks before importing any real tenant data. - Import synthetic or new workspaces for validation, checking colocated joins, publishing-state transitions, collaborative editing, and dashboard read models. - Configure PgBouncer, backups, monitoring, capacity thresholds, and failure drills separately for Citus coordinator and worker nodes. - Apply Asynq worker concurrency limits by `workspace_id` and Citus cluster capacity, so single-tenant tasks do not overwhelm workers or the database.