a2-mongoose-multi-db

🚀 multi-mongoose

A powerful Mongoose wrapper for multi-database support, automatic failover, routing, deduped inserts, parallel reads, snapshots, event hooks, and more.

---

📦 Why multi-mongoose?

Use multi-mongoose when:

• You want to connect to multiple MongoDB databases
• You want write failover support if a DB fails
• You need dynamic write routing by region, tenant, etc.
• You want to read from all databases in parallel
• You need safe insert logic across all DBs
• You want built-in stats, snapshots, and event hooks

---

🔁 Mongoose vs multi-mongoose

Feature	Mongoose	multi-mongoose ✅
Multiple DB connections	❌ Manual	✅ Built-in
Automatic write failover	❌ No	✅ Yes
Smart write routing	❌ No	✅ Yes
Read from all DBs	❌ No	✅ Yes
Shared schemas	❌ No	✅ Yes
Safe insert (no duplicates)	❌ No	✅ Yes
Global plugin support	❌ Limited	✅ Yes
Per-DB stats/snapshot	❌ No	✅ Yes
Query rate limiting	❌ No	✅ Yes

---

📦 Installation

npm i a2-mongoose-multi-db

---

🚀 Usage Examples by Feature

1. Multiple DB Connections

Connect to several MongoDB databases at once, each with a unique name.

await multiMongoose.init([
  { name: 'us', uri: 'mongodb://localhost:27017/usdb' },
  { name: 'eu', uri: 'mongodb://localhost:27017/eudb' }
]);

---

2. Write Failover

If a write fails on one DB, it automatically retries on others.

await multiMongoose.init([...], { retryOnFail: true, maxRetries: 2 });
// If 'us' DB is down, write will retry on 'eu' DB.
await User.create({ email: '[e-mail]' });

---

3. Smart Write Routing

Route writes to a DB based on your own logic (e.g., by region or tenant).

multiMongoose.setWriteRouter((model, doc) => doc.region === 'eu' ? 'eu' : 'us');
await User.create({ email: '[e-mail]', region: 'eu' }); // Goes to 'eu' DB

---

4. Parallel Reads

Read from all databases in parallel and merge results.

const allUsers = await User.find({}); // Returns users from all DBs

---

5. Shared Schemas

Register a model once and use it across all databases.

const userSchema = new mongoose.Schema({ name: String, email: String });
const User = multiMongoose.model('User', userSchema);

---

6. Safe Insert (No Duplicates)

Insert a document only if it does not exist in any DB.

await User.safeInsert({ email: '[e-mail]' }); // Only inserts if not found in any DB

---

7. Global Plugin Support

Apply Mongoose plugins to all models in all DBs.

multiMongoose.usePlugin(require('mongoose-timestamp'));
const User = multiMongoose.model('User', userSchema); // All DBs get the plugin

---

8. Per-DB Stats & Snapshots

Get stats for each DB or snapshot all documents to a file.

const stats = await User.getStats();
console.log(stats); // { us: { connected: true, docCount: 10 }, ... }
await User.snapshot('./all-users.json'); // Saves all docs from all DBs

---

9. Query Rate Limiting

Limit the number of queries per second per DB.

multiMongoose.setQueryLimit({ perSecond: 10 }); // Max 10 queries/sec per DB

---

✅ Supported Mongoose Features

Category	Examples	Supported?
Read Queries	find, findOne, findById, countDocuments, aggregate	✅ Yes (runs across all DBs)
Write Queries	save, create, insertMany, updateOne, updateMany, replaceOne, deleteOne, deleteMany	✅ Yes (on selected write DB)
Query chaining	Model.find().sort().limit().select()	✅ Yes
Mongoose middleware/hooks	pre, post, lifecycle hooks	✅ Yes
Schema methods & statics	schema.methods.xyz, Model.staticFn()	✅ Yes
Population (populate)	Model.find().populate('ref')	✅ Yes
Validation	Custom schema validators, required, etc.	✅ Yes
Plugins	schema.plugin()	✅ Yes (globally or per-schema)
Aggregation pipeline	.aggregate([ ... ])	✅ Yes (reads from all DBs)
Transactions (future support)	session.startTransaction()	🚧 Not supported (yet)
Lean queries	find().lean()	✅ Yes
Timestamps	timestamps: true	✅ Yes
Discriminators	Model.discriminator()	✅ Yes
Virtuals	schema.virtual('fullName')	✅ Yes

---

👤 Author

Arun Kumar

---