Components

The DocumentDB implementation consists of three PostgreSQL extensions and a gateway that work together to provide MongoDB-compatible document database functionality on top of PostgreSQL.

pg_documentdb_core

pg_documentdb_core is a PostgreSQL extension that introduces BSON datatype support and operations for native Postgres. This core component is essential for enabling document-oriented NoSQL capabilities within a PostgreSQL environment. It provides the foundational data structures and functions required to handle BSON data types, which are crucial for performing CRUD operations on documents.

Key Features

• BSON Datatype Support: Adds BSON (Binary JSON) datatype to PostgreSQL, allowing for efficient storage and manipulation of JSON-like documents.

• Native Operations: Implements native PostgreSQL operations for BSON data, ensuring seamless integration and performance.

• Extensibility: Serves as the core building block for additional functionalities and extensions within the DocumentDB ecosystem.

pg_documentdb

pg_documentdb is the public API surface for DocumentDB, providing CRUD functionality on documents stored in the database. This component leverages the capabilities of pg_documentdb_core to offer a comprehensive set of APIs for managing document data within PostgreSQL.

Key Features

• CRUD Operations: Provides a rich set of APIs for creating, reading, updating, and deleting documents.

• Advanced Queries: Supports complex queries, including full-text searches, geospatial queries, vector search, and aggregation pipelines.

• Index Management: Single-field, compound, multi-key, partial, unique, TTL, text, geospatial, and vector indexes.

• User and Role Management: Built-in commands for managing users, roles, and SCRAM authentication.

• Integration: Works seamlessly with pg_documentdb_core to deliver robust document management capabilities.

Usage

To use pg_documentdb, you need to have pg_documentdb_core installed and configured in your PostgreSQL environment. Once set up, you can leverage the APIs provided by pg_documentdb to perform document operations from any PostgreSQL client. For the full list of callable functions, see Functions.

pg_documentdb_extended_rum

pg_documentdb_extended_rum (SQL extension name documentdb_extended_rum) is DocumentDB's fork of the PostgreSQL RUM index access method, which backs DocumentDB's document indexes. It keeps RUM's on-disk format and extends the query path for document workloads.

It is required in 1.0: documentdb.rum_library_load_option defaults to require_documentdb_extended_rum, so pg_documentdb loads its index handler from the extended RUM library. The library loads only from shared_preload_libraries, and CREATE EXTENSION documentdb CASCADE does not create the extension, so a manually configured server needs both steps before indexes are built:

-- postgresql.conf: add pg_documentdb_extended_rum to shared_preload_libraries and set
-- documentdb.alternate_index_handler_name = 'extended_rum', then restart
CREATE EXTENSION documentdb_extended_rum;

The package setup wizard and the documentdb-local image do this for you. See Configuration for the load option.

pg_documentdb_gw

pg_documentdb_gw is the gateway protocol translation layer that converts the user's MongoDB wire protocol commands into PostgreSQL queries against the pg_documentdb API. It is what allows MongoDB-compatible drivers and tools (mongosh, PyMongo, the official MongoDB Node.js driver, the VS Code extension, and others) to talk to a DocumentDB instance unmodified.

Key Features

• MongoDB Wire Protocol: Parses MongoDB wire protocol messages (OP_MSG, OP_QUERY, OP_INSERT, etc.) and dispatches them to the corresponding pg_documentdb SQL functions.

• Authentication: SCRAM-SHA-256. It is the only mechanism advertised in the hello/isMaster handshake, and the only one usable against a stock build. The gateway also accepts MONGODB-OIDC at SASL start for token-based authentication, but that path delegates to a documentdb_api_internal.authenticate_token function the extensions do not define, so it requires a deployment-supplied token provider. PLAIN is rejected.

• TLS Termination: Terminates TLS on the gateway port (default 10260), allowing drivers to connect over the standard MongoDB-style mongodb:// connection string with tls=true.

• Cursor and Session Management: Translates getMore, killCursors, killSessions, and killOp commands to the corresponding backend operations.

• Deployment Options: Can be run as a standalone process (the default in the documentdb-local container) or, when built from source, as a PostgreSQL background worker via the pg_documentdb_gw_host extension, which the packages and the container image don't include.