MongoDB Tuning for JoSk

This document collects MongoDB-specific guidance for users of the MongoAdapter. The README covers the basic setup — read that first.

Connection options for a replica set

When josk shares a replica set with other workloads, configure the driver for durable, primary-routed writes so the scheduler's lease and claim operations are linearizable:

import { MongoClient } from 'mongodb';
import { JoSk, MongoAdapter } from 'josk';

const options = {
  writeConcern: {
    j: true,            // wait for journal sync
    w: 'majority',      // wait for majority ack
    wtimeoutMS: 30000   // bail after 30s on a degraded RS
  },
  readConcern: { level: 'majority' },
  readPreference: 'primary'
};

const client = await MongoClient.connect('mongodb://url', options);

// Use a database dedicated to JoSk to avoid contention with your app DB.
const db = client.db('josk-db');

const jobs = new JoSk({
  adapter: new MongoAdapter({ db })
});

Why a dedicated database?

The scheduler issues frequent atomic findOneAndUpdate calls against the task and lock collections. Sharing the database with chatty application workloads can cause lock contention and inflate JoSk's tick latency. A dedicated DB on the same cluster is the cheapest isolation.

Cleaning up old tasks

Run from the MongoDB shell:

// Default prefix `default`:
db.getCollection('__JobTasks__default').deleteMany({});

// Custom prefix:
db.getCollection('__JobTasks__PrefixHere').deleteMany({});

// Lock collection (shared across prefixes by default):
db.getCollection('__JobTasks__.lock').deleteMany({});

Index inventory

MongoAdapter#__setup creates and maintains:

Collection	Index	Purpose
__JobTasks__<prefix>	{ uid: 1 } UNIQUE	Idempotent task add and direct removal by uid
__JobTasks__<prefix>	{ isDeleted: 1, executeAt: 1 }	Drives the "due now" scan in iterate()
__JobTasks__.lock	{ uniqueName: 1 } UNIQUE	One lease document per JoSk instance prefix
__JobTasks__.lock	{ expireAt: 1 } TTL (expireAfterSeconds: 0)	Auto-deletes leases past expireAt

Do not drop or modify these indexes manually — __setup recreates them on next startup.

Mongoose, CosmosDB, DocumentDB

MongoAdapter is tested against the official mongodb driver only. Other clients may work if they expose the same Db.collection(), Db.command(), and Collection APIs, but are unsupported. CosmosDB's Mongo API in particular omits operators the scheduler relies on for atomic claim semantics.