Chronos/DBWaitlist

Chronos DB, self-hosted

Beside MongoDB

Collections as tables, merges that send only the fields that changed, refresh, change streams and undo.

Self-hostedChronos DB is one binary you run yourself. Releases and install script. To put agents on a database you already run, with approvals: Chronos Gateway

How it works

chronos attach also works beside MongoDB 5.0 or later. The promise is the same as beside Postgres and MySQL: main is a copy of the collections you name, agents work in worlds, and a merge into main is written to MongoDB first, in one multi-document transaction. Each document it writes must still be as main has it. If MongoDB changed one meanwhile, the merge comes back as a conflict and nothing is written.

shell
export CHRONOS_SOURCE_URL='mongodb://chronos:example-password@db.internal:27017/shop?replicaSet=rs0&tls=true'chronos attach shop --tables customers,orders --fields org_idchronos serve shop

This page describes Chronos DB 0.6.2 (2026-11-19). Attach beside MongoDB came in 0.5.0. Following changes through change streams is new in 0.5.1. To put runs, rules and approvals on top of an attached folder, use Chronos Gateway.

Requirements

  • MongoDB 5.0 or later. An older server is refused: MongoDB <version> is too old: attach needs 5.0 or later (nothing was copied).
  • A replica set. MongoDB has transactions only on a replica set (Atlas is one). One member is enough: mongod --replSet rs0, then rs.initiate().
  • Not a standalone mongod. It is refused at attach: this MongoDB is a standalone server, which has no transactions: a merge couldn’t be written all or nothing. Attach needs a replica set (one member is enough: mongod --replSet rs0, then rs.initiate()), or Atlas; nothing was copied.
  • Not a sharded cluster. this is a sharded cluster (mongos): attach works with a replica set only for now.
  • A URL that names the database. The URL is MongoDB’s own connection string, mongodb:// or mongodb+srv://. Its database’s collections are the ones attached. Without a database: the MongoDB URL names no database: mongodb://user:password@host:27017/<database> (its collections are the ones attached).

The URL comes from CHRONOS_SOURCE_URL, or from a file only you can read (CHRONOS_SOURCE_FILE, or chronos serve --source-file f). It is never a command argument and is written nowhere in the folder. chronos serve and chronos refresh on the folder need it too. An error from the driver is printed without the password a URL in it might show.

A build with MongoDB in it

  • The released binaries have MongoDB in them, from 0.5.0.
  • A build of your own needs cargo build --features mongo.
  • A build without it says so when asked: this chronos was built without MongoDB: use a build with it (cargo build --features mongo).
  • mongodb+srv:// URLs connect from 0.5.0. Before, the driver was built without its DNS seed-list support and every such URL was refused before any connection.

The user and its privileges

readWrite on the database is enough for everything on this page. Chronos makes two collections there:

CollectionHolds
chronos_mergesa document per merge written, plus the folder’s marker. Made at attach
chronos_merge_rowseach document a merge wrote, before and after, kept to undo the merge by its id
  • If the user can’t make chronos_merges, attach stops with ... can’t make the collection chronos_merges in MongoDB (...): give it readWrite on the database.
  • For serve --follow, the user needs find and changeStream on the attached collections, and on no other. The built-in read role has both.
  • Follow opens one stream per collection, not one on the database, so the privileges are needed on the attached collections only.

chronos attach

usage
chronos attach <new folder> --tables a,b [--fields x,y] [--yes]
FlagDoes
<new folder>the folder attach makes. One that exists is refused: shop exists: attach makes a new folder (to attach again, give another)
--tables a,bthe collections to attach, of the database the URL names. Required: name the collections to attach: --tables a,b (collections of the database the URL names)
--fields org_idtop-level fields to keep as columns of their own (a tenant’s id, the fields an agent filters by). Not _id or doc, and no name with a dot or a leading $: --fields <f>: a top-level field’s name, not _id or doc
--yesgoes on above about 1,000,000 documents. Without it: about N documents in all (MongoDB’s estimate): copying holds one snapshot open on MongoDB for that long. Run again with --yes to go on
--schemarefused: --schema is for Postgres: name MongoDB’s collections with --tables a,b
--lazy-tenantrefused: --lazy-tenant works with a Postgres source only for now

Attach checks the server (a replica set, 5.0 or later), checks each collection and prints MongoDB’s estimate of its documents, makes chronos_merges, reads the type each --fields field holds, copies every collection in one snapshot, and then records the folder’s marker in chronos_merges. On any failure nothing is left behind. What it refuses is listed under what is refused.

How a collection is held

A collection is a table, and a document is a row.

ColumnHolds
_idthe document’s _id, as text and the table’s primary key: an ObjectId as its 24 hex digits, any other id as JSON ("abc", 7)
one per --fields namethat top-level field, as a column of its own: bigint for an int or long, text for a string or ObjectId
docthe rest of the document, as jsonb
SQL, in a world
select doc->>'name' from customers where org_id = 42;update customers set doc = jsonb_set(doc, '{owner}', '"ada"') where _id = '65f1a2b3c4d5e6f708192a3b';insert into customers (org_id, doc) values (42, '{"name": "NewCo"}');   -- _id is a new ObjectIddelete from customers where _id = '"lead-2"';                            -- a string id, with its quotes
  • Values are MongoDB’s relaxed Extended JSON. An ObjectId inside doc is {"$oid": "..."}, a date {"$date": "2026-10-01T10:00:00Z"}, a Decimal128 {"$numberDecimal": "1.50"}. Numbers are plain.
  • A field named by --fields must hold one type throughout the collection: string, int, long or ObjectId (int and long together count as long). Documents without it have NULL. It isn’t in doc; set the column.
  • A field that is a column can’t also be set inside doc: <table>.doc holds the field <name>, which is a column of its own here: set the column, not the field.
  • A new row’s _id defaults to a new ObjectId, made as MongoDB’s drivers make one (the time, then random digits). Give your own by setting _id.
  • doc must be a JSON object: <table>.doc must be a JSON object (the document’s fields).

What a merge sends

Chronos’s own checks run first, as for any merge. Then:

  1. A transaction starts

    The folder’s marker in chronos_merges is checked. A URL that names another database is refused: the MongoDB CHRONOS_SOURCE_URL names isn’t the one this folder was attached to (...).

  2. Read and compare

    Every document the merge writes is read and compared with main’s copy. Any difference is a conflict: nothing is written, main takes MongoDB’s document, and the merge is settled as any conflict. Numbers compare by value, and objects whatever their fields’ order.

  3. Inserts and updates, then deletes

    An update sends only the fields that changed, as $set and $unset by path, never the whole document. The fields it leaves keep their order and their types.

  4. Read back, record, commit

    The documents are read back, the merge is recorded in chronos_merges (and its documents in chronos_merge_rows), and the transaction commits.

  • A document another writer changes between the compare and the write fails the write. MongoDB aborts the transaction, and the merge says it is safe to run again.
  • Counts are checked. If MongoDB touched another number of documents than the merge sent: MongoDB updated 0 documents of customers where the merge sent 1: nothing was merged. The same for inserts and deletes.
  • Documents are read and written by _id, at most 1,000 in one command.
  • Field names with a dot or a leading $, and empty names, can’t be written by a merge: <table>.doc holds a field named "a.b": MongoDB can’t address it by name.

Number types and arrays

jsonb has one kind of number; MongoDB has three. The rule:

  • A number written to a field that already holds one keeps that field’s type. A double stays a double when you write 9; a long stays a long.
  • In a new field, a whole number is an int (a long past 32 bits), and a number with a fraction part is a double.
  • To write another type, write its Extended JSON: {"$numberLong": "5"}, {"$numberDecimal": "1.50"}, {"$date": "..."}, {"$oid": "..."}.

Arrays

An array is one value. A change to an array writes the whole array, so two changes to the same array are a conflict even when they touch different elements. Changing array elements one by one is not there.

Conflicts and errors

A document the merge writes that differs in MongoDB from main’s copy has changed in MongoDB since main last had them. Nothing is written, main takes MongoDB’s documents for the ones in conflict, and the merge returns the conflicts. Merge again and settle them as any conflict.

FailureSQLSTATEMessage ends
A duplicate key (MongoDB’s E11000)23505nothing was written
A transient error (the driver’s TransientTransactionError or UnknownTransactionCommitResult label)40001nothing was written: safe to merge again
Any other23000nothing was written

Each begins MongoDB, <step>: <the driver’s error>.

A crash around the commit

The merge’s document in chronos_merges is written in the write-back’s transaction, so it is there exactly when the writes are. If the connection is lost during the commit, chronos_merges tells whether it happened, at the next merge. If it can’t be told yet: the connection to MongoDB was lost during the commit (...), and whether it committed can’t be told yet (...): merges into main wait until it can; <world> is as it was.

From 0.6.2 (the last item from 0.6.1):

  • The commit is acknowledged by a majority of the replica set, in their journals (write concern majority, j: true), and the write-back reads with read concern majority, whatever the URL or the server’s defaults say. A merge main has can’t be rolled back by a failover. A replica set with a majority of its members down can’t take merges into main until they are back.
  • Asking whether a commit happened writes nothing that stays. Chronos inserts the merge’s id into chronos_merges in a transaction of its own and always aborts it: a duplicate means the merge committed, an insert that goes through means it didn’t. Before, the probe was an insert outside any transaction. It could answer “didn’t commit” for a merge still committing and drop it, so a merge that then committed in MongoDB never reached main, and it could leave a probe: true document. Such documents are removed at the next check.
  • A merge still committing can’t be told yet. If Chronos was killed during a write-back, MongoDB keeps that transaction open until transactionLifetimeLimitSeconds (60 seconds by default) and then aborts it. Until then the check answers that it can’t tell, and merges into main wait. Everything else keeps working.
  • From 0.6.1, recovery makes exactly the merge MongoDB committed: a world written since the crash keeps those writes, and main takes the touched documents from MongoDB.

Checking reads

A world forked WITH (check_reads = true) has what it read checked against MongoDB too: inside the write-back’s transaction before anything is written, and by CHECK READS between steps. A document it read that MongoDB changed since, or one added there that its read would have found, holds the merge.

The world readChecked by
A document by _idthat document alone
With a condition on a field kept as a column (--fields)the documents the condition can match
With a condition on a field inside docthe whole collection: any document added or changed there holds the merge
A collection wholethe collection read whole from MongoDB, 100,000 documents at most. Past that the merge is held for a person
For one tenantthat tenant’s documents only, when the tenant’s field is one of --fields

Dry runs

MERGE WORLD w DRY RUN (the HTTP API’s dry_run: true, MCP’s merge_preview) reads MongoDB in one snapshot. Each document the merge would write is compared with MongoDB’s as the write-back compares it, the world’s reads are checked if it checks them, and nothing is written or locked. Rehearsals (MERGE WORLD w REHEARSE) are Postgres’s only.

Refresh

shell
chronos refresh shop                       # once, on a folder no server has openchronos serve shop --refresh-every 5m      # on a timer, while it serves

A refresh reads each collection whole in one snapshot and gives main MongoDB’s inserts, updates and deletes. It checks the folder’s marker first: the MongoDB CHRONOS_SOURCE_URL names isn’t the one this folder was attached to (...): nothing was refreshed. A folder chronos serve has open refreshes with POST /v1/refresh and the admin token, or serve --refresh-every.

serve --follow

shell
chronos serve shop --follow                      # main takes MongoDB's changes a moment after they happenchronos serve shop --follow --refresh-every 1h   # and a whole refresh now and thenchronos refresh shop --unfollow                  # forget the streams' places

New in 0.5.1. A refresh reads every document; --follow reads a MongoDB change stream on each attached collection instead. The stream says which documents changed (their _ids). Those documents are then read as MongoDB has them now, in one snapshot, and compared with main’s as a refresh compares them. Main takes just those, a moment after they change, without reading the rest.

  • One stream per attached collection, not one on the database. Many attached collections mean as many small reads a second.
  • Places are kept in mongo-follow.json in the folder: for each collection, the resume token MongoDB gave after the last change main took. A place moves on only once main took the changes, so a follow stopped partway reads them again.
  • The first follow begins with a refresh. It takes its place in each stream first and then refreshes every collection once, since changes before a place aren’t in the stream. A change between the two is read again, and takes nothing.
  • A lost place begins with a refresh too. If the engine was away longer than MongoDB’s oplog keeps, the place is gone: the next follow says so, takes a new place and refreshes the collection. The same happens for a place that can’t be read from the file.
  • A stream only says where to look. A change read twice, or a merge’s own write coming back in the stream, takes nothing.
  • A collection dropped or renamed is compared whole, and followed on from a new place.
  • More than 100,000 documents of one collection changed at once: the collection is refreshed whole.
  • At most 50,000 changes are read from the streams at a time, shared out among the collections. The rest are read at the next follow.
  • MongoDB keeps nothing for a change stream, so there is no slot to drop.
  • chronos refresh shop --unfollow forgets the places: the next follow begins again with a refresh. It prints forgot the change stream’s place: the next follow begins with a refresh, or no change stream’s place to forget.
  • Privileges: find and changeStream on the attached collections, and on no other. The built-in read role has both.
MessageMeans
following MongoDB’s changes through a change stream on each collection of shop: customers (from now), orders (from now)a first follow: each collection took a place and was refreshed
... (again: MongoDB’s log no longer reached the place kept)the oplog no longer holds the place: a new place, then a refresh
... (again: its stream ended)the collection was dropped or renamed, or its place was lost mid-read: a new place, then a refresh
MongoDB won’t open a change stream (...): it takes a replica set, and a user who may run find and changeStream on each attached collection. Without it, main takes MongoDB’s documents at each refresh (--refresh-every)the user lacks the privileges, or the server is not a replica set. The server keeps trying
MongoDB, reading the change stream of customers: ...a read of a stream failed; it is tried again

The HTTP API’s attached says follow: true for MongoDB in a build with it.

Undo by merge id

Each write-back keeps the documents it wrote, before and after, in chronos_merge_rows, in its transaction. A merge can be undone by its id for 30 days (CHRONOS_UNDO_WINDOW_DAYS), as beside Postgres. The undo puts the documents back through MongoDB as a merge does: each compared, in one transaction.

SQL
UNDO MERGE ID 'merge:...' [, 'merge:...'] [SKIP CHANGED] [DRY RUN]
  • A merge over HTTP answers its id (merge, beside merged). HTTP undo_merge takes ids, with skip_changed and dry_run.
  • A document changed since the merge refuses the undo with nothing written (409, 40001), or is left with skip_changed while the rest go back.
  • A document already put back is already, from 0.5.2: neither undone nor skipped, and it never refuses the undo. So a merge undone in part can be undone again for the documents left, once they hold what the merge wrote, and undoing a merge twice does nothing.
  • MongoDB has no cascades to hold an undo for.
  • Effects aren’t undone: the undo lists them (effects_not_undone).

What is refused

At attach, each named with the reason, and nothing copied (can’t attach, nothing was copied:):

WhatMessage
A standalone serverthis MongoDB is a standalone server, which has no transactions ...
A sharded cluster (mongos)this is a sharded cluster (mongos): attach works with a replica set only for now
MongoDB older than 5.0MongoDB <version> is too old: attach needs 5.0 or later (nothing was copied)
A collection that isn’t there<name>: no such collection in <database>
A view<name>: a view: attach the collections it reads
A time-series collection<name>: a time-series collection: not attached yet
A capped collection<name>: a capped collection: its documents can’t be deleted or grow
A system. collection, chronos_merges or chronos_merge_rows<name>: not a collection of yours
A document over 4 MB (as Extended JSON text)<collection>: the document <id> is over 4 MB: not attached
A --fields field of mixed types<collection>.<field>: holds string and int in different documents; a field kept as a column (--fields) must be one of string, int, long or objectId throughout
Two documents whose _ids are written the same in the folder<collection>: two documents share the key <id> as it is written here: not attached

At a merge: field names with a dot or a leading $ can’t be written, and neither can a field inside doc that is a column of its own.

What is not there, and not tested

Each of these is refused with a message that says so:

Not yetInstead
Rehearsals (MERGE WORLD w REHEARSE)DRY RUN
chronos refresh --check (the reconciliation scan)DRY RUN of a merge compares its documents with MongoDB
Merge checks run in the sourcemerge checks still run on main, Chronos’s copy
writeback.jsonevery field is compared, and the fields that changed are written
pg_role (writing as the end user)every write runs as the user the URL names
--lazy-tenantcollections are copied whole
Sharded clustersa replica set
Views, time-series and capped collectionsattach the collections a view reads
Array elements changed one by onea changed array is written whole
  • Not tested against Atlas. Attach was tested against MongoDB 5.0 and 7.0 run locally, not against Atlas. Atlas is a replica set, and mongodb+srv:// URLs (Atlas’s usual one) connect from 0.5.0.
  • Asking rather than trying. The HTTP API’s attached says kind: "mongodb", with follow, dry_run and check_reads true, and act_as, lazy_tenant and source_checks false. It also says undo: {ready, window_days}.

Next

Beside MongoDB · Chronos