Moleculer Database Service

Common errors

• TypeError: createService() second argument is not a plain object

  cause Attempting to pass schema modifications as a second argument to `broker.createService()` after upgrading to Moleculer v0.15 compatible `moleculer-db` versions.
  fix Migrate 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

  cause `moleculer-db@0.9.0` (and its compatible adapters) explicitly requires Node.js 22 or newer.
  fix Update 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

  cause The MongoDB server is not running or is inaccessible from the Moleculer service.
  fix Ensure your MongoDB instance is running and accessible at the specified connection URI. Verify firewall rules and connection strings.

Warnings

• breaking The 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.
  Fix: Upgrade your Node.js environment to version 22 or higher. For example, `nvm install 22 && nvm use 22`.
• breaking With 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.
  Fix: Refactor service definitions to use the `mixins` property for extending service schemas, e.g., `mixins: [DbService]` instead of passing a second argument to `createService`.
• breaking For `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.
  Fix: Ensure 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+.
• gotcha The `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.
  Fix: When 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`.
• gotcha Moleculer 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.
  Fix: For 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.

Install

• npm install moleculer-db npm
• yarn add moleculer-db yarn
• pnpm add moleculer-db pnpm

Imports

• ServiceBroker
  wrong:

  const { ServiceBroker } = require('moleculer');

  correct:

  import { ServiceBroker } from '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
  wrong:

  import { DbService } from 'moleculer-db';

  correct:

  import DbService from 'moleculer-db';

  DbService is a default export.
• MongooseAdapter
  wrong:

  const MongooseAdapter = require('moleculer-db-adapter-mongoose');

  correct:

  import MongooseAdapter from 'moleculer-db-adapter-mongoose';

  When using a specific database adapter, import it directly from its package. Adapters are typically default exports.

Quickstart

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);
});