Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ServiceBroker
✓ import { ServiceBroker } from 'moleculer';
✗ const { ServiceBroker } = require('moleculer');
While CommonJS `require` works in Node.js >=22, ESM `import` is the idiomatic standard for modern Node.js development. The `moleculer` framework, and by extension its modules, encourage ESM.
DbService
✓ import DbService from 'moleculer-db';
✗ import { DbService } from 'moleculer-db';
DbService is a default export.
MongooseAdapter
✓ import MongooseAdapter from 'moleculer-db-adapter-mongoose';
✗ const MongooseAdapter = require('moleculer-db-adapter-mongoose');
When using a specific database adapter, import it directly from its package. Adapters are typically default exports.
This quickstart demonstrates how to create a basic Moleculer service using `moleculer-db` with the default NeDB adapter, performing common CRUD operations like create, find, list (with pagination), update, and remove. It shows the mixin pattern for integrating `DbService` into a Moleculer service.
import { ServiceBroker } from 'moleculer';
import DbService from 'moleculer-db';
const broker = new ServiceBroker();
// Create a DB service for 'user' entities using the default NeDB adapter
broker.createService({
name: 'users',
mixins: [DbService],
settings: {
// Define which fields are exposed publicly
fields: ['_id', 'username', 'name']
},
afterConnected() {
// Seed the DB or perform other post-connection setup
console.log('DB Service connected for users!');
// Example: this.create({ username: 'initialUser', name: 'Initial Name', status: 1 });
}
});
broker.start()
.then(async () => {
console.log('Broker started. Performing CRUD operations...');
// Create a new user
const newUser = await broker.call('users.create', {
username: 'john',
name: 'John Doe',
status: 1
});
console.log('Created user:', newUser);
// Get all users
const allUsers = await broker.call('users.find');
console.log('All users:', allUsers);
// List users with pagination (default page size/max page size apply)
const pagedUsers = await broker.call('users.list', { page: 1, pageSize: 5 });
console.log('Paged users (page 1):', pagedUsers.rows);
// Update a user (assuming _id is 'john' for NeDB/default adapter, or a generated ID)
// Note: In real scenarios, use the actual _id returned from creation
const updatedUser = await broker.call('users.update', { id: newUser._id, name: 'Jane Doe' });
console.log('Updated user:', updatedUser);
// Delete a user
await broker.call('users.remove', { id: newUser._id });
console.log('User deleted.');
})
.catch(err => {
console.error('Error starting broker or performing actions:', err);
process.exit(1);
});
Debug
Known issues
breakingThe minimum Node.js version has been bumped to `>=22.x.x` in `moleculer-db@0.9.0` and its related adapters. Older Node.js versions are no longer supported.fixUpgrade your Node.js environment to version 22 or higher. For example, `nvm install 22 && nvm use 22`.
affects: >=0.9.0
breakingWith Moleculer v0.15 compatibility in `moleculer-db@0.9.0`, the `broker.createService(schema, schemaMods)` signature is removed. Service schema modifications must now be done using the `mixins` pattern within the service definition.fixRefactor service definitions to use the `mixins` property for extending service schemas, e.g., `mixins: [DbService]` instead of passing a second argument to `createService`.
affects: >=0.9.0
breakingFor `moleculer-db-adapter-mongoose@0.10.0`, the minimum Node.js version was bumped to 14, and Mongoose versions 7 & 8 are now supported. While `moleculer-db@0.9.0` now mandates Node.js 22, ensure your Mongoose version is compatible if upgrading this adapter.fixEnsure your project uses a Mongoose version compatible with the adapter (Mongoose 7 or 8 for `moleculer-db-adapter-mongoose@0.10.0+`), alongside Node.js 22+.
affects: >=0.10.0 (adapter)
gotchaThe `idField` setting in `moleculer-db` is ignored by the `moleculer-db-adapter-sequelize`. With Sequelize, the ID field is typically defined within your model's schema, allowing for custom primary keys.fixWhen using `moleculer-db-adapter-sequelize`, configure your primary key directly in your Sequelize model definition rather than relying on the `idField` setting in `moleculer-db`.
affects: >=0.1.0 (all versions)
gotchaMoleculer DB currently supports only one model/entity per service. While this works well for NoSQL document databases, for SQL databases with multiple and complex relationships, you may need to write a custom adapter or service actions if `moleculer-db`'s features do not suffice.fixFor complex SQL schemas or multiple entities per service, consider custom service actions or a custom adapter. `moleculer-db` is intended for simpler 'one database per service' patterns.
affects: All versions
Errors
Common errors & fixes
TypeError: createService() second argument is not a plain object
Attempting to pass schema modifications as a second argument to `broker.createService()` after upgrading to Moleculer v0.15 compatible `moleculer-db` versions.
fixMigrate service definitions to use the `mixins` array for `DbService` integration and schema extensions: `broker.createService({ name: 'my-service', mixins: [DbService, myOtherMixin] })`. Error: This module requires Node.js version >=22.x.x. Current version is v18.x.x
`moleculer-db@0.9.0` (and its compatible adapters) explicitly requires Node.js 22 or newer.
fixUpdate your Node.js runtime to version 22 or later. Use a version manager like `nvm` for easy switching: `nvm install 22 && nvm use 22`.
MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017
The MongoDB server is not running or is inaccessible from the Moleculer service.
fixEnsure your MongoDB instance is running and accessible at the specified connection URI. Verify firewall rules and connection strings.
Audit
Dependencies
moleculerrequiredCore microservice framework; moleculer-db is a service mixin for it.