Infrastructure: How to prevent database name collisions across services on s...

Documentation for Sessions

📝 Infrastructure: How to prevent database name collisions across services on s...

Date: 2026-03-30
Time: 14:34:02 UTC
Session: gspace1-283.5
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to prevent database name collisions across services on shared MongoDB clusters (e.g., staging)?

Task: S283: Database name collision prevention

🎯 Decision Made

Chosen:

Collision guard in database-names.config.ts that runs at module load time. Iterates ALL static database names across AI, Vitto, API, and Docs registries. If any name appears twice, throws an Error with clear message before any MongoDB connection opens.

Options Considered:

  1. Code review only (human enforcement)
  2. Build-time validation script
  3. Runtime collision guard at module load (chosen)
  4. Database name registry service

💭 Reasoning

ROOT CAUSE: Nothing prevented a developer from adding a database name to one service registry (e.g., VITTO_DATABASE_NAMES) that already exists in another (e.g., AI_DATABASE_NAMES). On production with separate clusters this is harmless (different clusters). On staging with a shared cluster, both services write to the SAME database — silent data corruption. ALTERNATIVES: (1) Code review only — human enforcement, unreliable. (2) Build-time validation script — requires CI pipeline integration, not caught during local dev. (3) Database name registry service — over-engineered for a static config problem. CHOSEN BECAUSE: (1) Catches at earliest possible moment (module import, before any Mongoose connection). (2) Zero runtime cost (runs once). (3) Self-documenting error message explains WHY. (4) Dynamic space databases (space_*, space-agents_*) don't need it — structurally different prefixes. WOULD BE WRONG IF: We needed multiple services to intentionally share a database name (currently no such pattern exists). EARLY WARNING: If the guard throws in CI or local dev, a developer just added a duplicate name.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation