antelopejs/mongodb

@antelopejs/mongodb

The MongoDB backend of AntelopeJS: it runs the database interface's queries on MongoDB with the official mongodb driver, and exposes that client to modules that need it directly.

Interfaces

Schemas, tables, queries, change feeds and atomic mutations are documented on the database interface pages.

Install

ajs project modules add @antelopejs/mongodb

The command writes the module's default configuration: mongodb://localhost:27017, database antelopejs.

Configuration

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    mongodb: {
      source: {
        type: "package",
        package: "@antelopejs/mongodb",
        version: "^1.4.2",
      },
      config: {
        url: "mongodb://localhost:27017/?replicaSet=rs0",
        database: "my-project",
        options: { maxPoolSize: 10 },
      },
    },
  },
  envOverrides: {
    MONGODB_URL: "modules.mongodb.config.url",
  },
});

Change feeds rely on MongoDB change streams, which need a replica set. A single-node replica set is enough in development.

Quick start

In the module that stores data, add the database interface:

pnpm add @antelopejs/interface-database

Then follow the database interface guide to declare a schema and query it. The same code runs on @antelopejs/rethinkdb.

To call the driver directly instead, add @antelopejs/interface-mongodb:

import { GetClient } from "@antelopejs/interface-mongodb";

const client = await GetClient();
const users = client.db("my-project").collection("users");

Storage layout

• Each schema table is one collection, <schemaId>__<table>, shared by every instance of the schema. Each document stores its instance in _instance.
• _id stays unique across instances: use globally unique record identities.
• Each declared index <name> becomes a <name>__i MongoDB index led by _instance. An index declared with crossInstance: true also gets an unprefixed <name> index for CROSS_INSTANCE queries; without it, those queries still work but log a one-time warning and cannot use an index.
• Atomic mutations use a second client with retryWrites and retryReads disabled.

Versions before 1.4 created each index as <name> only. The module creates the <name>__i indexes next to them and never drops an index: drop the old ones you no longer need by hand, for example db.getCollection("<schemaId>__<table>").dropIndex("<name>").

Documentation

• Database: the @antelopejs/interface-database contract this module implements
• MongoDB: the @antelopejs/interface-mongodb contract this module implements
• Configuration: module sources, config blocks and config variables in antelope.config.ts

Compatibility

The module is developed and tested against @antelopejs/core ^1.13.4 on Node.js 24, with the mongodb driver ^6.21.0 and a MongoDB 8.0 replica set.

Contributing

pnpm install
pnpm lint
pnpm format:check
pnpm knip
pnpm test           # build, then ajs module test against an in-memory replica set

The tests start MongoDB with mongodb-memory-server, which downloads the server binary on the first run. They also run the shared conformance suite of @antelopejs/interface-database.

Read the contribution guidelines before opening a pull request.

License

Apache-2.0