MongoDB

Before you start

Use this recipe in the server project from the custom-server quick start or your existing backend. Make the database and storage environment variables available to the server and schema commands. The React Native project's deploy configuration is a separate step.

Run MongoDB as a replica set or sharded cluster. Hot Updater runs every write in a transaction so that each change commits atomically, and a standalone MongoDB server cannot run them: its first write fails with MongoTransactionUnsupportedError. There is no option to write without transactions. For local development, a single-node replica set is enough: start mongod with --replSet rs0, then run rs.initiate() once in mongosh.

Installation

Install the MongoDB native driver.

npm install @hot-updater/server @hot-updater/aws mongodb

npm install --save-dev hot-updater

Setup

Create a database connection file:

import { MongoClient } from "mongodb";

export const client = new MongoClient(process.env.MONGODB_URI!);

// Connect to MongoDB
await client.connect();

Hot Updater uses the client's default database: the one named in MONGODB_URI, or test when it names none.

Hot Updater configuration

Create the Hot Updater instance:

import { createHotUpdater } from "@hot-updater/server";
import { mongoAdapter } from "@hot-updater/server/adapters/mongodb"; 
import { apiKeys, insights } from "@hot-updater/server/plugins";
import { s3Storage } from "@hot-updater/aws";
import { client } from "./mongodb";

export const hotUpdater = createHotUpdater({
  database: mongoAdapter({ client }), 
  plugins: [insights(), apiKeys()],
  storage: s3Storage({
    region: "auto",
    endpoint: process.env.R2_ENDPOINT,
    credentials: {
      accessKeyId: process.env.R2_ACCESS_KEY_ID!,
      secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    },
    bucketName: process.env.R2_BUCKET_NAME!,
  }),
});

mongoAdapter({ client }) takes only the client. It returns an engine database with the migrator that hot-updater db migrate runs. Each Hot Updater table is a collection whose documents use the row's key as _id, and each index is created as declared. Guarded changes are conditional on a document's version, and write conflicts are retried. insights() records app events, and apiKeys() protects the client routes with the x-api-key header.

Schema generation

Run the database migration to create the MongoDB collections and indexes.

npx hot-updater db migrate src/hotUpdater.ts

This command targets src/hotUpdater.ts, creates the collections and indexes of core and of the server's plugins, then writes the schema settings. It does nothing when the settings are current; run it again after upgrading Hot Updater. It refuses a database created by an older Hot Updater schema instead of converting it. hot-updater db generate does not apply to MongoDB.

The server checks the settings before its first read or write. Until they exist, it throws HotUpdaterSchemaMigrationRequiredError and its handlers answer 503. A running server checks again on its next request, so it recovers once the migration has run.

CLI configuration

After the schema is applied, create the client API key using this same direct server configuration. Then connect the React Native project's CLI to the protected admin mount. Its storage configuration must match a server entry, and its plugins must list the server's plugins.

API endpoints

The adapter persists data; your framework mounts the HTTP handlers. Continue with the Hono, Express or Elysia recipe. See the handler boundaries and repository contract for client and admin access.

Finish with Set up your app and Test an OTA update.