Skip to content

docs(backend): document MongoDB connection and fail fast when it is missing - #480

Open
peaceshallom37-rgb wants to merge 1 commit into
AetherEdu:mainfrom
peaceshallom37-rgb:fix/issue-471-mongodb-env-docs
Open

docs(backend): document MongoDB connection and fail fast when it is missing#480
peaceshallom37-rgb wants to merge 1 commit into
AetherEdu:mainfrom
peaceshallom37-rgb:fix/issue-471-mongodb-env-docs

Conversation

@peaceshallom37-rgb

Copy link
Copy Markdown

Closes #471

Summary

The backend connects to MongoDB via MONGODB_URI/MONGO_URI (ensureMongooseIndexes in backend/src/index.ts) and loads dozens of Mongoose models, but the connection string was undocumented — .env.example only listed PostgreSQL and Redis. A fresh deployment following the documented setup would never connect to MongoDB, and index sync + Mongoose-backed routes would silently behave as if no database existed.

Changes

  • .env.example — adds a MONGODB_URI entry under Database Configuration, with a note explaining the Postgres-vs-Mongo split.
  • backend/src/index.tsensureMongooseIndexes() now fails fast (throws before the server starts) when Mongoose models are registered but no MongoDB URI is configured, instead of silently returning. Connection handling when a URI is set is unchanged.
  • backend/README.md — documents the division of responsibility: PostgreSQL is the primary relational store (users, enrollments, payments, courses, migrations); MongoDB is the document store for Mongoose-backed services (content delivery, notifications, offline sync, quizzes, translations, whiteboard, etc.), and is required at startup.

Verification

  • npm run typecheck passes.
  • Lint and test-suite failures are pre-existing on main (verified by stashing; e.g. @ts-ignore ban errors in index.ts and a featureFlags.ts import failure in tests/api.test.js).
  • The fail-fast path is inside startServer(), which only runs when the module is the entrypoint (require.main === module), so tests that import the app are unaffected.

…issing

Mongoose models are used across the backend (content delivery, notifications,
offline sync, quizzes, etc.) and index synchronization runs at startup, yet
the MongoDB connection string was undocumented while .env.example only
covered PostgreSQL and Redis. A fresh deployment following the documented
setup would silently never connect to MongoDB.

- Add MONGODB_URI (and the Postgres-vs-Mongo split) to .env.example.
- Fail startup when Mongoose models are registered but no Mongo URI is
  configured, so index sync and Mongoose-backed routes never silently run
  without a database.
- Document the Postgres-vs-Mongo division of responsibility in
  backend/README.md.

Closes AetherEdu#471
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Backend][Tech-debt] MongoDB connection is undocumented — MONGODB_URI missing from .env.example while mongoose models are used

1 participant