DocumentDB 1.0 GA: Bringing MongoDB Protocol to PostgreSQL

DocumentDB 1.0 brings MongoDB wire protocol compatibility to PostgreSQL under an MIT license. Supported by the Linux Foundation, it offers an open-source NoSQL alternative for database architects.

TL;DR

  • What happened: Open-source DocumentDB 1.0 reached General Availability (GA) under an MIT license, providing native MongoDB wire protocol compatibility on top of PostgreSQL engine infrastructure.
  • Who is affected: Database administrators, platform engineers, and backend developers evaluating alternatives to proprietary or SSPL-licensed document stores.
  • Architecture & Support: Features a dual-component design (protocol gateway and PostgreSQL C extension), supporting PostgreSQL 15–18 via container images and PostgreSQL 17–18 via native Linux packages.
  • What to do now: Evaluate workload performance using staging shadow traffic, assess aggregation and indexing behavior, and verify driver compatibility before considering production migration.

The database ecosystem has entered a period of consolidation where operational simplicity often triumphs over single-purpose specialized engines. The milestone release of documentdb 1.0 ga delivers an open-source, MIT-licensed implementation of the MongoDB wire protocol directly on top of PostgreSQL core infrastructure. Announced initially by Microsoft in early 2025 and subsequently transferred to the Linux Foundation, the project has garnered backing from major industry vendors, including AWS, Cockroach Labs, Google, Microsoft, Snowflake, and Yugabyte. By marrying standard MongoDB document semantics with PostgreSQL reliability, the project offers platform engineers a pathway to consolidate multi-model database fleets.

Operating a dual-database footprint—maintaining relational instances alongside dedicated document clusters—introduces substantial overhead. Database administrators must manage separate deployment pipelines, monitoring stacks, backup policies, and disaster recovery strategies. DocumentDB addresses this operational fragmentation by enabling application teams to retain standard MongoDB client drivers, queries, and operational tools while standardizing backend storage on PostgreSQL instances. The 1.0 GA release reflects a concerted focus on production readiness, stabilizing query mechanics, indexing pipelines, aggregation logic, and geospatial calculations.

This technical analysis evaluates the architecture, performance characteristics, licensing implications, and operational considerations of DocumentDB 1.0. We examine how the system handles wire protocol translation, compare its throughput profile against alternatives like FerretDB and native MongoDB, and outline a structured migration and deployment framework for infrastructure teams.

Open-Source DocumentDB 1.0 Reaches General Availability

The general availability of DocumentDB 1.0 marks a shift in how open-source document databases are governed and deployed. As documented by InfoQ reporting on the release, the core objective of the project is to preserve existing developer skills and application code written for MongoDB while backing the data store with PostgreSQL. Application developers can continue using existing MongoDB client libraries without modifying operational query code or application logic.

Governed under the neutral umbrella of the Linux Foundation, DocumentDB avoids single-vendor control. The project brings together competing cloud providers and database software vendors to ensure the wire protocol translation layer remains open and vendor-agnostic. This multi-vendor foundation provides infrastructure architects with assurance regarding long-term maintenance, governance, and community-driven API standards.

The primary engineering goal of DocumentDB 1.0 is full API and protocol fidelity. Rather than requiring applications to use bespoke Object-Document Mapping (ODM) translation layers or modified SDKs, DocumentDB operates as a drop-in database endpoint. Applications point standard MongoDB drivers to the DocumentDB protocol gateway, which processes raw network requests and executes corresponding operations within underlying PostgreSQL engines.

Architectural Deep-Dive: Extension and Wire Protocol Gateway

DocumentDB achieves compatibility through a decoupled architecture consisting of two distinct runtime components: a protocol gateway daemon and a specialized PostgreSQL C extension. The diagram below illustrates the data flow from client applications to persistent disk storage.

+-------------------------------------------------------------+
|               Application / MongoDB Client                  |
|          (Standard MongoDB Drivers: PyMongo, Mongoose, etc.) |
+-------------------------------------------------------------+
                               |
                               | MongoDB Wire Protocol (TCP)
                               v
+-------------------------------------------------------------+
|             DocumentDB Wire Protocol Gateway                |
|  - Ingests OP_MSG / BSON binary streams                     |
|  - Parses command objects (find, insert, aggregate, update) |
|  - Translates wire payloads to PostgreSQL calls             |
+-------------------------------------------------------------+
                               |
                               | PostgreSQL Protocol / IPC
                               v
+-------------------------------------------------------------+
|             PostgreSQL Database Engine                      |
|  +-------------------------------------------------------+  |
|  |             DocumentDB PostgreSQL Extension           |  |
|  |  - Implements BSON query processing & indexing logic |  |
|  |  - Custom aggregation operators & geospatial functions|  |
|  |  - Executes against PostgreSQL JSONB/Custom Storage   |  |
|  +-------------------------------------------------------+  |
|  | PostgreSQL Core Engine (WAL, MVCC, Buffer Pool, Page I/O)|
+-------------------------------------------------------------+

The Wire Protocol Gateway acts as the front-end network server. It listens on standard TCP ports, handles TLS negotiation, and unpacks incoming MongoDB wire protocol frames (such as OP_MSG payloads). Upon receiving a network request, the gateway parses the serialized binary JSON (BSON) structures and maps the operation to native PostgreSQL interface calls. This translation happens transparently, converting operations like db.collection.find() or update operators into optimized internal database invocations.

The PostgreSQL Extension resides directly inside the PostgreSQL process space. This extension supplies custom data types, query execution functions, operator classes, and indexing strategies tailored to BSON semantics. Rather than converting every document into flat relational rows, the extension leverages PostgreSQL native JSONB representations and customized storage engines to maintain document schema flexibility, nested object traversing, and field-level updates.

The 1.0 GA release incorporates substantial stability enhancements across core functional areas:

  • Indexing Engine: Fixes addressing field lookup efficiency, single-field indexes, compound indexes, and multikey indexing over nested arrays.
  • Aggregation Pipelines: Improved execution mechanics for pipeline stages, including pipeline memory allocation, group-by operations, lookup transformations, and unwinding arrays.
  • Geospatial Processing: Corrected boundary calculations and spatial query execution for 2dsphere index queries and distance algorithms.

Licensing and Governance: MIT versus MongoDB SSPL

Licensing models directly influence long-term cloud architecture strategies. DocumentDB 1.0 is released under the permissive MIT License, creating a sharp contrast with the licensing constraints of commercial document databases, notably MongoDB’s Server Side Public License (SSPL).

Dimension DocumentDB 1.0 GA MongoDB (SSPL)
License Type Permissive (MIT) Source-Available (SSPL v1)
Commercial Cloud Hosting Fully permitted without source disclosure Restricted unless underlying infrastructure code is open-sourced under SSPL
Source Modification Rights Unrestricted modification and private distribution Permitted, subject to copyleft triggers upon offering as a service
Governance Model Neutral multi-vendor under Linux Foundation Single-vendor commercial entity (MongoDB Inc.)
Downstream Integration Can be linked into proprietary commercial products Requires explicit commercial licensing for proprietary redistribution

Under the SSPL, organisations that offer MongoDB as a managed commercial cloud service must release the complete source code of all supporting automation, management, and control-plane software under the same license. This requirement has historically restricted managed platform providers and cloud vendors from offering MongoDB-compatible engines without custom commercial agreements.

The MIT licensing of DocumentDB eliminates these operational legal barriers. Enterprises, independent software vendors (ISVs), and cloud hosting providers can integrate, modify, embed, and commercialise DocumentDB without exposing proprietary control-plane assets or infrastructure management code. Managed under the Linux Foundation with support from Microsoft, AWS, Google, Snowflake, Yugabyte, and Cockroach Labs, the project provides a balanced vendor ecosystem designed to prevent proprietary lock-in.

PostgreSQL Compatibility, Container Images, and Kubernetes Operator

Platform engineers evaluating DocumentDB 1.0 must consider existing PostgreSQL engine versions and orchestration tools. The project maintains clear version boundaries between containerized deployments and native bare-metal or virtual machine package distributions.

PostgreSQL Version Container Image Support Native Linux Package Support
PostgreSQL 15 Supported Not Available
PostgreSQL 16 Supported Not Available
PostgreSQL 17 Supported Supported (RPM / DEB)
PostgreSQL 18 Supported Supported (RPM / DEB)

Container images provide full support across PostgreSQL versions 15 through 18, accommodating environment upgrades without requiring immediate engine distribution shifts. For bare-metal deployments, native Linux packages (such as DEB for Ubuntu/Debian and RPM for RHEL/Rocky Linux) are focused exclusively on PostgreSQL 17 and 18, reflecting modern server distributions.

To streamline cloud-native operational management, DocumentDB provides an official Kubernetes Operator. The operator automates stateful lifecycle tasks, including multi-node cluster provisioning, storage expansion, high-availability failover, and zero-downtime extension upgrades. Below is an example manifest illustrating how a DocumentDB cluster is declared using the custom resource definition (CRD):

apiVersion: documentdb.io/v1alpha1
kind: DocumentDBCluster
metadata:
  name: docdb-production-cluster
  namespace: database-workloads
spec:
  replicas: 3
  postgresVersion: "17"
  storage:
    size: 250Gi
    storageClassName: fast-nvme
  resources:
    limits:
      cpu: "8"
      memory: 16Gi
    requests:
      cpu: "4"
      memory: 8Gi
  gateway:
    enabled: true
    port: 27017
    tls:
      enabled: true
      secretName: docdb-tls-cert

The maintainers intend to establish separate release channels: a Long-Term Support (LTS) track targeting enterprise production environments requiring multi-year API stability, and a rapid-development track for testing new feature sets. However, the vendor advisory notes that the finalized versioning policy and lifetime guarantees for LTS releases remain under active refinement by the project steering committee.

Version Selection Guidance

When planning new Kubernetes deployments, standardise on PostgreSQL 17 or 18 container bases. This aligns cluster states with future native Linux packaging and ensures compatibility with upstream extension optimization work.

Performance Dynamics: Benchmark Insights and Tail Latency Trade-Offs

Transitioning from a dedicated document database engine to an extension-driven translation architecture involves distinct performance trade-offs. Synthetic benchmark assessments provide preliminary insight into how DocumentDB 1.0 compares to alternative engines under controlled conditions.

Initial evaluation data published by Layerbase utilizing the Yahoo! Cloud Serving Benchmark (YCSB) analyzed read and write characteristics across DocumentDB and FerretDB. The testing demonstrated that DocumentDB achieved between 20% and 33% higher read throughput compared to FerretDB across standard query workloads. This read efficiency stems directly from the tight integration of the DocumentDB C extension inside the PostgreSQL execution engine, which reduces memory copy overhead during document serialization and retrieval.

However, the benchmarks also highlighted workload-dependent trade-offs. In mixed workloads involving intensive concurrent updates, FerretDB demonstrated lower update tail latency ($P_{99}$ and $P_{99.9}$) than DocumentDB. This variance occurs because write operations in DocumentDB trigger underlying PostgreSQL multi-version concurrency control (MVCC) mechanics, write-ahead logging (WAL), and JSONB page update operations, which can introduce latency spikes during high-concurrency update bursts.

Performance Variance in Production

An open community issue on GitHub reports higher baseline query latency in DocumentDB 1.0 when tested against native MongoDB 9.0.4 across select transactional workloads. These preliminary claims have not been independently verified under enterprise storage arrays or varied cache profiles. Infrastructure teams must execute internal performance validation using production-derived datasets.

Runtime memory overhead and CPU translation costs during extreme gateway saturation have not been fully disclosed by the project maintainers. SREs must monitor protocol translation overhead under heavy connection multiplexing to ensure system stability.

DocumentDB Ecosystem Interoperability and FerretDB Integration

Understanding the ecosystem requires clarifying the technical relationship between DocumentDB and FerretDB. Rather than competing in isolation, the two open-source initiatives feature modular interoperability.

DocumentDB provides both the low-level PostgreSQL C extension (which implements BSON data structures and document execution routines within PostgreSQL) and its own built-in MongoDB protocol gateway. FerretDB, conversely, is an independent project that can utilize the DocumentDB PostgreSQL extension as its underlying storage engine while providing its own standalone protocol proxy and API translation engine.

+-------------------------------------------------------------------+
|                     MongoDB Client Applications                   |
+-------------------------------------------------------------------+
                  |                                   |
                  | Driver Wire Protocol              | Driver Wire Protocol
                  v                                   v
+-----------------------------------+   +---------------------------+
| DocumentDB Unified Architecture   |   | FerretDB Architecture     |
| +-------------------------------+ |   | +-----------------------+ |
| | DocumentDB Protocol Gateway   | |   | | FerretDB Protocol Proxy| |
| +-------------------------------+ |   | +-----------------------+ |
|                 |                 |   |             |             |
|                 v                 |   |             v             |
| +-------------------------------+ |   | +-----------------------+ |
| | DocumentDB Postgres Extension | |   | | DocDB Extension / C   | |
| +-------------------------------+ |   | +-----------------------+ |
+-----------------------------------+   +---------------------------+
                  |                                   |
                  +-----------------+-----------------+
                                    |
                                    v
+-------------------------------------------------------------------+
|                    PostgreSQL Storage Engine                      |
+-------------------------------------------------------------------+

As Patty Chow, product manager at Microsoft, highlighted in commentary published by InfoQ, alternative open-source document implementations give developers choices in deployment architectures while retaining established MongoDB client drivers and query patterns. Community feedback reflects these varying choices; on Reddit, user 716green observed that historical compatibility between MongoDB and FerretDB has required ongoing effort, noting appreciation for Microsoft’s investments in advancing the underlying open-source extensions.

Both architectures support standard inspection utilities, such as mongosh, and administrative GUI tools like MongoDB Compass. This ecosystem compatibility enables platform teams to maintain standard developer workflows without updating application client libraries.

The selection of the name “DocumentDB” for this open-source initiative has caused considerable naming confusion across cloud database engineering communities.

Historically, Microsoft used the name Azure DocumentDB for its proprietary managed document service, which was later rebranded and expanded into Azure Cosmos DB. Concurrently, Amazon Web Services offers Amazon DocumentDB, a proprietary fully managed document database service designed to be compatible with MongoDB. The introduction of this distinct open-source project—also called DocumentDB—has generated ongoing community debate.

In a discussion on Hacker News, user marifjeren expressed a common sentiment regarding the project’s branding:

“Name it anything else for god’s sake. DocumentDB is already what everybody calls Amazon DocumentDB.”

To avoid operational and architectural confusion, platform engineers should distinguish between these three distinct offerings:

  1. Open-Source DocumentDB (The 1.0 GA Project): The Linux Foundation-governed, MIT-licensed open-source project combining a protocol gateway and PostgreSQL extension.
  2. Amazon DocumentDB: AWS’s proprietary managed cloud database service. It is not open-source, nor does it run on this Linux Foundation codebase.
  3. Azure DocumentDB / Azure Cosmos DB: Microsoft’s managed multi-model cloud database service. The historical Azure DocumentDB branding is obsolete in Azure, replaced by Cosmos DB.

Infrastructure teams documenting internal architectural standards must explicitly reference “Open-Source DocumentDB on PostgreSQL” or cite the official Linux Foundation repository endpoints to prevent misconfigurations during cloud service provisioning.

Practical Implementation Strategy for Engineering Teams

Deploying DocumentDB 1.0 in production environments requires systematic staging validation, protocol gateway tuning, and log analysis. Database administrators should follow this structured implementation checklist to evaluate compatibility and performance before executing workload cutovers.

Practitioner Deployment & Migration Checklist

  • [ ] API Compatibility Auditing: Run application integration test suites against a staging DocumentDB cluster to flag unmapped aggregation stages or unsupported operators.
  • [ ] Connection Pooling Verification: Ensure application connection pools account for protocol gateway translation overhead. Validate connection limit settings on both the gateway and PostgreSQL backends.
  • [ ] Index Strategy Mapping: Review existing MongoDB index definitions. Re-create compound and geospatial indexes natively within DocumentDB to confirm index pushdown functions properly.
  • [ ] Monitoring Infrastructure Setup: Configure telemetry logging to capture PostgreSQL long-running queries, memory allocation, and JSONB page read metrics.
  • [ ] Shadow Traffic Testing: Mirror live production read traffic to a staging DocumentDB instance to measure real-world $P_{95}$ and $P_{99}$ latency profiles under concurrent load.

Diagnostic Commands and Log Inspection

To verify that the DocumentDB C extension is properly initialized within a target PostgreSQL 17 or 18 database, execute the following SQL diagnostics using psql:

# Connect to the target PostgreSQL instance as database superuser
psql -h postgres-staging.internal -U postgres -d app_db -c "CREATE EXTENSION IF NOT EXISTS documentdb;"

# Verify extension initialization and installed version
psql -h postgres-staging.internal -U postgres -d app_db -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'documentdb';"

To analyze translation efficiency and detect slow query executions within PostgreSQL logs, enable detailed query logging inside postgresql.conf. Test these configurations in a staging environment prior to applying them in production:

# Enable logging of statements taking longer than 250 milliseconds
log_min_duration_statement = 250
# Log execution plans for slow queries (requires auto_explain extension)
session_preload_libraries = 'auto_explain'
auto_explain.log_min_duration = '250ms'
auto_explain.log_analyze = true
auto_explain.log_buffers = true

When inspecting PostgreSQL logs, look for translation patterns generated by the gateway. DocumentDB operations log underlying function calls executing against BSON types:

2026-11-14 10:14:02.123 UTC [14022] LOG:  duration: 285.412 ms  statement: 
    SELECT documentdb_api.find_documents(
        p_collection_name => 'orders',
        p_filter => '{"status": "PENDING", "total": {"$gt": 100}}'::bson,
        p_sort => '{"created_at": -1}'::bson,
        p_limit => 50
    );

Common Deployment Mistake: Missing Index Pushdowns

A frequent error during early testing is assuming all MongoDB index definitions transfer automatically without verification. If an application executes an un-indexed aggregation pipeline, the underlying PostgreSQL engine executes a full table scan over all stored JSONB/BSON documents. Always inspect the output of db.collection.explain() via mongosh to confirm that the index is actively reducing scanned index keys and documents.

Key Takeaways for Database Administrators and Systems Engineers

DocumentDB 1.0 GA delivers a open-source option for teams seeking to unify relational and document data workloads onto PostgreSQL infrastructure. By combining an MIT license with open governance under the Linux Foundation, the project provides operational flexibility while protecting organisations from restrictive source-available licensing models.

From an architectural standpoint, the project demonstrates strong read performance gains over comparable proxy layers, though SREs must carefully evaluate update tail latency under high-concurrency write conditions. The unified dual-component model—pairing a protocol gateway with an in-engine C extension—preserves developer familiarity with MongoDB tools while allowing operations teams to standardise on established PostgreSQL monitoring, backup, and high-availability frameworks.

Engineering teams planning an evaluation should focus initial efforts on staging validation: auditing query compatibility, benchmarking shadow traffic, and validating index execution plans using the provided Kubernetes Operator and PostgreSQL diagnostic suites.

Frequently asked questions

What is open-source DocumentDB 1.0 and how does it connect to PostgreSQL?

Open-source DocumentDB 1.0 is an MIT-licensed document database system built on PostgreSQL. It consists of a network protocol gateway that ingests standard MongoDB wire protocol traffic and a PostgreSQL C extension that translates those requests into native document operations. This architecture allows developers to run unchanged MongoDB queries, client drivers, and administrative tools directly against underlying PostgreSQL storage infrastructure.

How does the MIT license of DocumentDB differ from MongoDB’s SSPL?

The MIT license is a permissive open-source license that allows unrestricted commercial use, modification, distribution, and managed service hosting without requiring developers to open-source proprietary backend management platforms. In contrast, MongoDB’s Server Side Public License (SSPL) mandates that anyone offering MongoDB as a commercial cloud service must release all surrounding infrastructure and management software under the same license terms.

What is the difference between DocumentDB and FerretDB?

DocumentDB provides both a dedicated MongoDB protocol translation gateway and a core PostgreSQL C extension for document processing. FerretDB is an independent project that can use DocumentDB’s PostgreSQL extension as a backend storage layer while providing its own distinct protocol conversion proxy. While DocumentDB offers an all-in-one execution stack, FerretDB functions as a modular proxy layer that leverages DocumentDB components under the hood.

Which versions of PostgreSQL and operating systems are supported by DocumentDB 1.0?

DocumentDB 1.0 supports PostgreSQL versions 15, 16, 17, and 18 when deployed via official container images. For bare-metal or virtual machine environments using native Linux package formats (such as DEB or RPM packages), support is focused on PostgreSQL 17 and 18. Cluster deployments on Kubernetes are managed through an official DocumentDB Kubernetes operator.

How does DocumentDB 1.0 compare in performance to native MongoDB?

Initial synthetic benchmarks indicate that DocumentDB delivers strong read performance, achieving 20% to 33% higher read throughput than FerretDB in YCSB testing. However, preliminary community testing notes that DocumentDB may exhibit higher query latency compared to native MongoDB 9.0.4 on specific workloads, while FerretDB shows lower tail latency during mixed update operations. Detailed performance validation on target NVMe storage is recommended.

Sources and further reading

This article was drafted with AI assistance from the publicly cited sources and passed automated checks for structure and sourcing. Verify critical details against the vendor advisories linked above before acting.