Moleculer Database Context Integrator

Common errors

• Error: Cannot find module '@mikro-orm/core'

  cause Mikro-ORM core package is a peer dependency but has not been installed.
  fix Install the core Mikro-ORM package: `npm install @mikro-orm/core`

• Error: Cannot find module 'moleculer'

  cause Moleculer is a peer dependency but has not been installed.
  fix Install the Moleculer framework: `npm install moleculer`

• Error: Driver not found for type 'sqlite'

  cause The specific Mikro-ORM database driver (e.g., `@mikro-orm/sqlite`) for the configured database type is missing.
  fix Install the appropriate Mikro-ORM driver for your database type, e.g., `npm install @mikro-orm/sqlite` for SQLite, or `@mikro-orm/mongodb` for MongoDB.

• Error: EntityManager not found in context

  cause The `DatabaseContextManager.middleware()` was not correctly added to the Moleculer broker, or the action was called without a context where the EntityManager would be injected.
  fix Ensure `yourMoleculerBroker.middlewares.add(dbContextManager.middleware());` is called *before* starting the broker and calling actions.

Warnings

• gotcha MongoDB support is considered experimental and has not been as thoroughly tested as SQL database integrations. Users relying on MongoDB should proceed with caution and thorough testing.
  Fix: For production systems requiring MongoDB, comprehensive custom testing is recommended. Review the underlying Mikro-ORM documentation for specific MongoDB transaction behaviors and limitations.
• gotcha Moleculer and Mikro-ORM (specifically `@mikro-orm/core` and specific drivers like `@mikro-orm/sqlite`) are peer dependencies. They must be installed separately in your project, and version compatibility should be checked.
  Fix: Ensure you install `moleculer`, `@mikro-orm/core`, and the specific Mikro-ORM driver(s) (e.g., `@mikro-orm/sqlite`, `@mikro-orm/mongodb`) that match the versions specified in your project's `package.json` or the library's peer dependency range.
• gotcha When configuring MikroConnector for MongoDB, `implicitTransactions` must be set to `true` if you require transaction support and are running a replica set. Failing to do so might result in transaction-related errors.
  Fix: For MongoDB replica sets, ensure your `MikroConnector.init()` configuration includes `implicitTransactions: true`.

Install

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

Imports

• MikroConnector
  wrong:

  const MikroConnector = require('moleculer-context-db').MikroConnector;

  correct:

  import { MikroConnector } from 'moleculer-context-db';

  Used to configure and initialize the Mikro-ORM connection. CommonJS `require` works but ES6 import is preferred.
• DatabaseContextManager
  wrong:

  const DatabaseContextManager = require('moleculer-context-db').DatabaseContextManager;

  correct:

  import { DatabaseContextManager } from 'moleculer-context-db';

  Manages the database context and provides the Moleculer middleware. CommonJS `require` works but ES6 import is preferred.
• middleware
  wrong:

  yourMoleculerBroker.middlewares.add(middleware());

  correct:

  yourMoleculerBroker.middlewares.add(DatabaseContextManager.middleware());

  The `middleware` method is a static method of `DatabaseContextManager` and should be called directly on the class.

Quickstart

Demonstrates how to set up moleculer-context-db with Mikro-ORM (SQLite) in a Moleculer broker, define an entity, and perform CRUD operations within a service using the context-injected EntityManager.

import { ServiceBroker } from 'moleculer';
import { MikroConnector, DatabaseContextManager } from 'moleculer-context-db';
import { BaseEntity, Entity, PrimaryKey, Property, MikroORM, Collection } from '@mikro-orm/core';
import { SqliteDriver } from '@mikro-orm/sqlite';

// 1. Define your Mikro-ORM entities (example)
@Entity()
class User extends BaseEntity<User, 'id'> {
  @PrimaryKey()
  id!: number;

  @Property({ unique: true })
  username!: string;

  @Property()
  email!: string;
}

// 2. Instantiate and initialize the MikroConnector
const connector = new MikroConnector<SqliteDriver>();

async function setup() {
  await connector.init({
    type: 'sqlite',
    dbName: ':memory:',
    entities: [User],
    cache: { enabled: false },
    // Ensure schema is synchronized for in-memory DB
    migrations: { runMigrations: true, path: './migrations' }, // Dummy path, not used for in-memory
    allowGlobalContext: true // Important for direct ORM access in tests/scripts
  });
  const orm = connector.getOrm();
  if (orm) {
    await orm.getSchemaGenerator().updateSchema();
  }

  // 3. Create a Moleculer Service Broker
  const broker = new ServiceBroker({
    logger: true,
    logLevel: 'info'
  });

  // 4. Instantiate DatabaseContextManager and add its middleware
  const dbContextManager = new DatabaseContextManager(connector);
  broker.middlewares.add(dbContextManager.middleware());

  // 5. Define a Moleculer service that uses the context-injected EntityManager
  broker.createService({
    name: 'users',
    actions: {
      async create(ctx) {
        // Access the EntityManager from the context
        const em = ctx.em;
        if (!em) {
          throw new Error('EntityManager not found in context');
        }
        const { username, email } = ctx.params;
        const user = em.create(User, { username, email });
        await em.persistAndFlush(user);
        return user;
      },
      async list(ctx) {
        const em = ctx.em;
        if (!em) {
            throw new Error('EntityManager not found in context');
        }
        return em.find(User, {});
      }
    }
  });

  await broker.start();

  // 6. Call a service action to test
  try {
    const user1 = await broker.call('users.create', { username: 'john.doe', email: 'john@example.com' });
    console.log('Created user:', user1);

    const user2 = await broker.call('users.create', { username: 'jane.doe', email: 'jane@example.com' });
    console.log('Created user:', user2);

    const users = await broker.call('users.list');
    console.log('All users:', users);
  } catch (error) {
    console.error('Error during service call:', error);
  } finally {
    await broker.stop();
    const orm = connector.getOrm();
    if (orm) {
      await orm.close();
    }
  }
}

setup();