Skip to content

Storage compatibility in Cratis Chronicle

Choose a supported storage backend before deploying Chronicle. A service that exposes a MongoDB API does not necessarily implement the features Chronicle and its consumers require.

Chronicle supports MongoDB, SQL Server, PostgreSQL, and SQLite. MongoDB requires a replica set for transactions and change streams. Use storage configuration for the authoritative backend list, configuration, and deployment limitations, including the ephemeral in-memory backend.

Azure DocumentDB and MongoDB-compatible services

Section titled “Azure DocumentDB and MongoDB-compatible services”

DocumentDB is not supported as a Chronicle storage backend. The measured local build accepted event storage operations but lacked change streams and index collation, both required by Chronicle’s MongoDB storage path.

The measurements recorded in Chronicle issue #5642 used ghcr.io/documentdb/documentdb/documentdb-local with MongoDB API 7.0, Chronicle 19.122.0, Arc 22.163.0, and MongoDB.Driver 3.13.0. All data was fictional.

Feature Result Note
Event appends and multi-document transactions Works Duplicate keys were rejected; aborted writes were absent.
Projections to read models Works Projections produced read models.
Unique constraints Works Two concurrent appends produced one winner.
Persisted reads after kernel restart and kernel readiness Works Stored data remained readable after restart and the kernel became ready.
Collection-level and database-level $changeStream Fails Stage $changeStream is not supported yet in native pipeline; breaks Arc MongoDB observable queries and read-model container watchers.
Index collation, even locale: simple Fails createIndex.collation is not implemented yet; prevents some kernel indexes, such as the open-incident gauge index, and breaks sink index reconciliation.
Chronicle MongoDB storage specs against the container 22 passed, 6 failed Failures came from the two feature gaps above; two additional cleanup NullReferenceException errors occurred.

The kernel also logged ObjectDisposedException during shutdown/restart. That observation was not attributed to DocumentDB.

When starting with MongoDB storage, Chronicle probes database-level change streams and collation once, outside the append path. An explicit unsupported-feature response stops startup with a message naming the missing features and linking to this page. Permissions, connectivity, timeouts, and standalone-server errors make a probe inconclusive: Chronicle warns and continues rather than labeling the service unsupported. A warning does not establish that a standalone server can run Chronicle; MongoDB still requires a replica set.

In Migrate schema mode, the collation probe creates an index with Collation.Simple on a temporary chronicle_capability_probe collection in the system database, then drops the collection and its index. It does not remove a collection that already existed. Cleanup failures produce a warning; remove a leftover probe collection with a schema identity before retrying.

In Verify mode, the probe performs a read-only find with Collation.Simple instead of DDL. This is best effort: a service may accept collation on a find but reject it when creating indexes, so a successful read probe does not establish index-collation support.

Use a non-production endpoint you control. Set CHRONICLE_MONGODB_CONNECTION_DETAILS to its connection string and run only the MongoDB storage spec project:

Terminal window
export CHRONICLE_MONGODB_CONNECTION_DETAILS="mongodb://mongo.example.test:27017/?replicaSet=myReplicaSet"
dotnet test Source/Kernel/Storage.MongoDB.Specs/Storage.MongoDB.Specs.csproj --configuration Release

Follow checking a MongoDB-compatible service for permissions and recording results per feature. Change-stream or collation spec failures mean the service lacks required support. Never commit real connection details. Someone with access must run this manual check against the managed Azure service; CI does not verify that service.