# DocumentDB: a MongoDB-compatible engine built on PostgreSQL extensions

> The open source DocumentDB project adds a BSON type and MongoDB wire protocol to PostgreSQL through three extensions. It is a different thing from the AWS and Azure managed services that share the name.

**documentdb/documentdb** — MongoDB-compatible database engine for cloud-native and open-source workloads. Built for scalability, performance, and developer productivity.

- Repository: https://github.com/documentdb/documentdb
- Website: https://documentdb.io/
- Stars: 3,450 · Forks: 256
- Language: C
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/documentdb-documentdb

## What documentdb/documentdb actually is, and who it is for

The name is overloaded. AWS DocumentDB and Azure DocumentDB are managed services. This repository is neither. It is an MIT-licensed database engine that the README describes as a MongoDB compatible open source document database built on PostgreSQL, with a native implementation of a document-oriented NoSQL database for CRUD operations on BSON data types inside a PostgreSQL framework.

The audience follows from that. If you already operate PostgreSQL and want to store and query documents without standing up a second database system, this project is aimed at you. The README also positions it for on-premise deployment, where an organization keeps control of its own data and infrastructure. The other audience is tool builders: the README points to FerretDB and its integration of DocumentDB as a backend engine, which is the clearest signal that the project expects to be embedded under another MongoDB-compatible layer rather than only used directly.

## Three components: BSON core, API surface, and the gateway

The architecture is split into three parts, and the split matters when you plan a deployment. pg_documentdb_core is a PostgreSQL extension that introduces the BSON datatype and its operations to native Postgres. pg_documentdb is the public API surface, providing CRUD functionality on documents in the store. pg_documentdb_gw is the gateway, a protocol translation layer that converts MongoDB API calls into PostgreSQL queries.

The data flow runs through all three. A client speaks the MongoDB wire protocol to the gateway, the gateway rewrites that into PostgreSQL queries, and the queries land on the BSON type and functions installed by the core extension. The repository layout is consistent with this: pg_documentdb_core, pg_documentdb, pg_documentdb_gw and pg_documentdb_gw_host sit as separate top-level directories, alongside pg_documentdb_extended_rum, which the top-level Makefile also installs. There is also an internal/pg_documentdb_distributed directory that the Makefile delegates to, so the build tree distinguishes an open set of extensions from an internal distributed component.

The README lists the workloads this is meant to carry beyond basic CRUD: full-text search, geospatial queries and vector search. Those capabilities are attributed to the PostgreSQL foundation rather than to new code, which is the honest framing. The project's bet is that PostgreSQL indexing and query machinery, plus a BSON type, is a better base than writing a document store from scratch.

## Installing DocumentDB locally with Docker and pymongo

The README's Get Started path assumes Python 3.7+, pip, Docker and Git. It begins with the Python client libraries.

```bash
pip install pymongo
pip install dnspython
```

The second package is described as an optional dependency. Then the container. The README pulls a prebuilt image, tags it for convenience, and runs it with credentials you choose.

```bash
docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest
docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb
docker run -dt -p 10260:10260 --name documentdb-container documentdb --username <YOUR_USERNAME> --password <YOUR_PASSWORD>
```

Port 10260 is the default in these instructions, chosen to avoid conflicts with other local database services. The README notes you can use 27017, the standard MongoDB port, or any other free port, but you must then update both the docker run command and the connection string. Credentials must be set at container creation, or authentication will not work.

Connecting looks like ordinary pymongo, with TLS enabled and certificate validation relaxed for the local setup.

```python
import pymongo

client = pymongo.MongoClient(
    'mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true'
)
```

From there the README creates a database and collection, inserts one document and then several, reads them back with find and find_one, and runs an aggregation pipeline with $match and $project stages. If you have written pymongo before, nothing in that sequence is new, which is the point of the compatibility claim.

## Where the compatibility claim stops being obvious

MongoDB compatibility is a spectrum, not a boolean, and the README does not draw the line. It says DocumentDB is MongoDB compatible and demonstrates CRUD plus a two-stage aggregation pipeline. It does not publish a compatibility matrix, and the README does not document rollback, backup tooling, or how a partially supported operator fails. If your application depends on change streams, transactions, or an operator outside the demonstrated set, the README gives you no way to confirm support from the page alone.

The build story has a similar gap. The Docker image is the documented path. The Makefile shows a source path with install-no-distributed and install-documentdb targets that descend into pg_documentdb_core, pg_documentdb and pg_documentdb_extended_rum, but the README does not walk through building those extensions against a specific PostgreSQL version. A reader who wants a source install rather than the container is left to the Makefiles.

This is also the wrong tool if you want a managed service with a console, automatic failover and a support contract. The README's own pitch is the opposite: full control over your data and infrastructure, which means you carry the operational work. And if your goal is relational modeling, adding a document layer to PostgreSQL buys you nothing except another interface to maintain.

## DocumentDB versus MongoDB and PostgreSQL, and the AWS name collision

Against MongoDB, the difference is the storage engine and the operational model. MongoDB is a standalone document database with its own replication and sharding. DocumentDB keeps PostgreSQL underneath and translates the MongoDB protocol at the gateway, so your durability, backup and replication story stays PostgreSQL's. You gain a database you may already know how to run. You take on a translation layer that sits in the request path and that must be kept in step with whatever MongoDB API version your client expects.

Against plain PostgreSQL, the difference is the data model. PostgreSQL with JSONB gives you semi-structured columns inside a relational schema. DocumentDB adds a BSON datatype and a document API surface, so the document is the primary object rather than a column value. The README's justification for choosing PostgreSQL is worth reading as a design statement: proven stability, extensibility, an active community, advanced indexing and full-text search, and security and compliance features. Every one of those is inherited, not invented here.

The name collision deserves its own warning. The related searches for this project are dominated by AWS and Azure questions: instance types, serverless, elastic clusters, pricing. None of that describes this repository. AWS DocumentDB and Azure DocumentDB are separate managed products. If you searched for those and arrived here, you are looking at a different piece of software.

## Maintenance, releases, and what the MIT licence means here

The repository is not archived, and the last push was on 2026-09-11. Releases are frequent and versioned with a date-style suffix: v0.117-0 on 2026-09-10, v0.116-0 on 2026-08-24, v0.114-0 on 2026-07-17. That cadence suggests active work, but the version numbers stay below 1.0, and the README does not describe an upgrade procedure between releases or a stability guarantee for the extension interfaces. The CHANGELOG.md at the repository root is where that information would live; the README does not summarize it.

Upgrade cost is therefore something you have to budget for yourself. Because the gateway, the API extension and the BSON core extension are separate artifacts, a release can move any of them, and the documented install path pulls a single Docker tag, latest, rather than a pinned version. Anyone deploying this in a pipeline should pin an explicit tag instead of following the README literally, and should read the changelog before moving that pin.

The licence is MIT, which the README frames as the most permissive option, with no restrictions on incorporating the project into new or existing solutions. That is a permissive licence in the ordinary sense. It says nothing about the licences of PostgreSQL itself or of any dependency you link against, and it is not legal advice; if licence compatibility matters for your distribution, check the licenses directory in the repository and your own counsel.

## Conclusion

Adopt documentdb/documentdb if you want MongoDB-style document APIs and you already run PostgreSQL, or if you are building a tool that needs a self-hosted MongoDB-compatible backend, the way FerretDB uses it. Do not adopt it if you are looking for the AWS or Azure managed services of the same name, or if you need a drop-in replacement for a MongoDB deployment whose exact behavior you have not checked. Before committing, verify three things: which MongoDB API surface the current release covers, how the gateway is deployed alongside your PostgreSQL instance, and whether the extension build path in the Makefile matches your PostgreSQL version.

## FAQ

### What is DocumentDB used for?

It stores and queries documents using MongoDB-style APIs while keeping PostgreSQL underneath. The README lists CRUD operations on BSON data plus full-text search, geospatial queries and vector search, and it can also serve as a backend engine for other MongoDB-compatible tools such as FerretDB.

### Is DocumentDB the same as MongoDB?

No. It is a separate, MIT-licensed implementation that is compatible with the MongoDB API and translates those calls into PostgreSQL queries through its gateway component. The README demonstrates pymongo clients working against it, but it is not MongoDB itself.

### How much does it cost to use DocumentDB?

The project itself is open source under the MIT licence, so there is no licence fee described in the README. Costs come from the infrastructure you run it on, since the documented path is a Docker container you host yourself.

### Is DynamoDB the same as DocumentDB?

No. DynamoDB is a different database product and is not discussed in this repository at all. This project is a PostgreSQL-based document engine that speaks the MongoDB protocol.

### What is Azure DocumentDB?

Azure DocumentDB is a managed Microsoft service, not this repository. The project covered here is the open source documentdb/documentdb engine that you install and run yourself.

## Sources

- [documentdb/documentdb on GitHub](https://github.com/documentdb/documentdb)
- [License: MIT](https://github.com/documentdb/documentdb/blob/main/LICENSE)
- [Project website](https://documentdb.io/)
- [README](https://github.com/documentdb/documentdb/blob/main/README.md)
- [Releases](https://github.com/documentdb/documentdb/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/documentdb-documentdb