@antelopejs/rethinkdb

The RethinkDB backend of AntelopeJS. It runs the queries of the database interface on RethinkDB through rethinkdb-ts, and gives that driver to the modules that need it directly.

Part of AntelopeJS. Used by AntelopeJS DMS, the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.

Interfaces

| Interface | Documentation | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | @antelopejs/interface-database | Database | | @antelopejs/interface-rethinkdb | RethinkDB | | @antelopejs/interface-database-catalog | External mode |

The database interface pages document schemas, tables, queries, change feeds, and atomic mutations.

Install

ajs project modules add @antelopejs/rethinkdb

The command writes the default configuration of the module, which opens a connection pool to 127.0.0.1:28015 as admin.

Configuration

The module connects through a connection pool (pool) or through a single connection (connection). When both are set, pool wins. When url is set, the module builds the pool from it and ignores connection.

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

export default defineConfig({
  name: "my-project",
  modules: {
    rethinkdb: {
      source: {
        type: "package",
        package: "@antelopejs/rethinkdb",
        version: "^1.4.0",
      },
      config: {
        pool: {
          host: "127.0.0.1",
          port: 28015,
          user: "admin",
          password: "",
          pool: true,
          cursor: false,
          silent: true,
          discovery: true,
        },
      },
    },
  },
});

For a single connection:

config: {
  connection: { host: "127.0.0.1", port: 28015, user: "admin", password: "" },
},

| Key | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pool | rethinkdb-ts pool options (RPoolConnectionOptions), passed to r.connectPool(). | | connection | rethinkdb-ts connection options (RConnectionOptions), passed to r.connect(). Used when pool and url are unset. | | url | rethinkdb://user:password@host:port/database, parsed into pool options. The port defaults to 28015 and the user to admin. Required in external mode. | | mode | owned (default) creates a database per schema and scopes rows to instances. external serves a database the module did not create. See External mode. | | statementTimeoutMs | Time limit, in milliseconds, of each read of an external instance. The module closes the connection of a read that runs past it. It must be a positive safe integer. | | catalog | { enabled?: boolean }. Turns the catalog of an external instance on or off. Unset, the catalog answers under ajs project dev and ajs project run only. |

The module refuses to start when none of url, pool, or connection is set, and when mode is neither owned nor external. The option types come from rethinkdb-ts.

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/postgres and @antelopejs/mongodb.

To use the driver directly instead, add @antelopejs/interface-rethinkdb and read its documentation.

Storage layout

• Each schema is a RethinkDB database, and each schema table is a table in it. Every table has a tenant_id index that scopes it to one instance. The database also holds an __instances__ table that records the instances of the schema.
• Each declared index <name> becomes a <name>__i index led by the instance. An index declared with crossInstance: true also gets an unprefixed <name> index for CROSS_INSTANCE queries. Without that index, those queries scan the table and log a warning once per index. Initialization refuses a declared index whose name ends in __i.
• The primary key is the _id field, which all instances of a table share. An insert of an _id that any instance already uses throws a DuplicateKeyError on _id.
• RethinkDB cannot enforce unique secondary indexes. Schema initialization refuses a table that declares an index with unique: true, and the error names the schema, the table, and the index.
• Schema initialization creates the missing databases, tables, and indexes. It makes up to five attempts, and it waits for the indexes before the schema accepts queries.
• When schema initialization fails or refuses a schema, the module logs the error and every query on that schema fails with the same message. The project keeps running.

Initialization builds every missing index at boot, so a boot that adds indexes to a large table takes longer. The module never drops an index. Drop an index you no longer need by hand, for example r.db("<schema>").table("<table>").indexDrop("<name>"). CHANGELOG.md records when the index layout changed.

Documentation

• Database documents @antelopejs/interface-database, which this module implements.
• RethinkDB documents @antelopejs/interface-rethinkdb, which this module implements.
• External mode explains how the module serves a database it did not create, and what its catalog answers.
• Configuration documents module sources, config blocks, and config variables in antelope.config.ts.

Compatibility

| Package | Supported | Tested with | | ---------------------------------------- | ---------------- | ----------- | | @antelopejs/interface-core | >=0.2.4 <1.0.0 | 0.4.0 | | @antelopejs/interface-database | >=0.3.1 <0.4.0 | 0.3.1 | | @antelopejs/interface-database-catalog | >=0.0.3 <0.1.0 | 0.0.3 | | @antelopejs/interface-rethinkdb | >=0.1.0 <0.2.0 | 0.1.0 |

The repository pins its Node.js version in .nvmrc. The rethinkdb-ts range is in the dependencies of package.json. The RethinkDB image that the tests run against is in .github/release-services.yml.

Contributing

The tests need a RethinkDB server on 127.0.0.1:28015. Start the one CI uses:

docker compose -f .github/release-services.yml up -d --wait

Then run the checks:

pnpm install
pnpm lint
pnpm format:check
pnpm typecheck
pnpm knip
pnpm test           # build, then the owned and external-mode suites

The tests also run the shared conformance suites of @antelopejs/interface-database. Read the contribution guidelines before opening a pull request.

License

Apache-2.0