What changes compared with MongoDB

TeselaDB implements the MongoDB 9.0 protocol, and the compatibility suite compares its answers with those of a real MongoDB server. Even so, some behaviours change, because a cluster that splits each collection into ranges replicated with Raft cannot, and does not want to, copy every detail of a replica set. Almost all of those changes are stronger guarantees. A few ask you to review your code. Others add what MongoDB does not have, such as a REST API or an MCP server on every node.

Stronger guarantees

In MongoDB, a write can take a while to show up in $search results, because the search index catches up on its own. In TeselaDB, a search sees every write confirmed before it starts. If your application waited for the index to catch up before searching, that wait is no longer needed.

Uniqueness also changes scope. In a collection with a shard key, MongoDB only guarantees that _id and unique indexes are unique within each shard, unless the index carries the shard key as a prefix. In TeselaDB, _id is unique across the cluster, and so is a unique index, without that prefix. The uniqueness checks you ran in the application to cover that gap can go.

local and available reads always return data confirmed by a majority, so you never see writes that are later lost. Inside a transaction, local, majority and snapshot read the same snapshot, the one at the transaction's read timestamp.

Search scores use the statistics of the whole collection. In a sharded MongoDB cluster, each shard scores with its own. The score then depends on how the data is spread. Here they match those of a replica set with the same documents and are the same on every replica, without depending on each one's merge history. The output of $group also comes out in the same order every time for the same data, where in MongoDB it can change from one run to the next.

What you have to review

The first point is order. MongoDB guarantees no order for a find without sort, although it often returns documents in insertion order. TeselaDB returns them in the order of their key within each range. If your code relied on seeing first what you inserted first, ask for sort. The same goes for ties. Unordered reads, $sort ties and the ids an index lists when it becomes unique follow the order of _id or of the key, and in a tie the equal value that $group keeps may change. If you care which one stays, sort explicitly before grouping, because that is the only way for the result not to depend on how the documents are stored.

The second is deprecated features. What MongoDB marks as deprecated in version 9.0 does not exist in TeselaDB, which answers the way MongoDB answers something that does not exist. That is the case of $substr or of index filters, and each use is replaced with the substitute the MongoDB documentation names. There are exceptions. isMaster, collStats, mapReduce and the hedge preference are kept with MongoDB's behaviour, because drivers, mongosh and the tools still send them. In new code, use hello, $collStats and the aggregation framework.

The third is keys that always grow. An ObjectId or a creation date as key concentrates writes in the last range, which lives on a single node. In busy collections, use another key or create the index with teselaBuckets, which spreads its entries over hash buckets. The planner joins the buckets when reading, so queries by date do not change.

Minor details remain. A wildcard index you try to make unique with collMod fails with error 67, where MongoDB accepts the command and writes an invalid index. When a collection is converted to capped, the documents are copied in _id order, so if the collection is over the size, other documents survive than in MongoDB.

What is added

Every node also serves a REST API with OpenAPI and an MCP server for agents. The MCP server starts read-only, its aggregation tools refuse $out and $merge, and it implements Streamable HTTP and stdio. Encryption at rest comes in the same binary and, without --encryptionKeyFile, takes the key from the cluster PKI. There are also cluster parameters of its own, such as teselaHistoryRetention, which sets how much history is kept. None of this changes the MongoDB protocol, so you only use it if it suits you.

Where to look up each case

The full list, with what MongoDB does, what TeselaDB does and what to do in each case, is in Differences with MongoDB. The status of each command and of each operator or stage is in Compatibility. Before migrating, it is worth searching your code for find calls without sort, deprecated features and keys that always grow, the three points that can change what your application sees.