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-28
Time: 15:21:58 UTC
Session: gspace1-283.4
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to prevent database name collisions across services on shared MongoDB clusters?

Task: 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 a clear message before any MongoDB connection opens. Server crashes at startup rather than silently corrupting data.

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: When multiple services share a single MongoDB cluster (as in staging), nothing prevented two services from registering the same database name. For example, if a developer added 'ai-memory' to VITTO_DATABASE_NAMES, both backend-ai-api and backend-vitto-api would write to the same 'ai-memory' database — silently corrupting data. The collision guard catches this at the earliest possible moment (module import time, before any Mongoose connection). It costs zero at runtime (runs once), is self-documenting (error message explains why), and requires no external tooling. Dynamic space databases (space_*, space-agents_*) don't need the guard because their prefixes are structurally different and cannot collide with static names.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation