documentdb

documentdb : API surface for DocumentDB for PostgreSQL

Overview

Packages

Source

pig build pkg documentdb;		# build rpm/deb

Install

Make sure PGDG and PIGSTY repo available:

pig repo add pgsql -u   # add both repo and update cache

Install this extension with pig:

pig install documentdb;		# install via package name, for the active PG version

pig install documentdb -v 18;   # install for PG 18
pig install documentdb -v 17;   # install for PG 17
pig install documentdb -v 16;   # install for PG 16
pig install documentdb -v 15;   # install for PG 15

Config this extension to shared_preload_libraries:

shared_preload_libraries = 'pg_documentdb, pg_documentdb_core, pg_cron';

Create this extension with:

CREATE EXTENSION documentdb CASCADE; -- requires documentdb_core, pg_cron, postgis, tsm_system_rows, vector

Usage

Sources: README, CHANGELOG, documentdb.control, documentdb_core.control, documentdb_extended_rum.control

documentdb is a MongoDB-compatible document database implemented as PostgreSQL extensions. It adds BSON storage and APIs in PostgreSQL, plus an optional gateway layer for MongoDB wire-protocol clients. FerretDB 2.0+ can use DocumentDB as its backend.

Components

The public extension surface is split across related extensions:

• documentdb_core: BSON datatype and low-level BSON operations.
• documentdb: public API for document CRUD and query behavior.
• documentdb_extended_rum: extended RUM access method used by DocumentDB indexing.
• pg_documentdb_gw: gateway protocol layer used by the local Docker image and MongoDB-compatible clients.

Install the SQL extension in each database that needs the API:

CREATE EXTENSION IF NOT EXISTS documentdb CASCADE;

The documentdb.control file for 0.113-0 declares dependencies on documentdb_core, pg_cron, tsm_system_rows, vector, and postgis. The gateway container listens on a MongoDB-compatible port; the README examples use 10260 to avoid colliding with local MongoDB services.

MongoDB Client Example

import pymongo

client = pymongo.MongoClient(
    "mongodb://user:pass@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true"
)

db = client["quickStartDatabase"]
coll = db.create_collection("quickStartCollection")

coll.insert_one({"name": "Alice", "email": "[email protected]"})
print(coll.find_one({"name": "Alice"}))

The upstream README also demonstrates aggregation pipelines through normal MongoDB drivers:

pipeline = [
    {"$match": {"name": "Alice"}},
    {"$project": {"_id": 0, "name": 1, "email": 1}},
]

for doc in coll.aggregate(pipeline):
    print(doc)

Version Notes

This project’s CSV tracks DocumentDB 0.113 for PostgreSQL 15-18. The upstream tag is v0.113-0; control files report default_version = '0.113-0'.

The 0.111 through 0.113 changelog entries are mostly query-planner, collation, and index correctness work:

• 0.113-0 adds opt-in collation support for non-unique ordered indexes with $in and $nin, and supports pruning dead index entries on ordered TTL indexes behind feature flags.
• 0.112-0 removes the legacy composite-returning bson_update_document UDF path, expands non-unique ordered-index collation support, and improves $group and accumulator execution.
• 0.111-0 adds background init job infrastructure, more $group validation, collation/index pushdown improvements, and several crash fixes.

Caveats

• DocumentDB is a multi-extension stack; CREATE EXTENSION documentdb CASCADE is the normal entry point, but operational deployments also need the gateway/runtime pieces if MongoDB wire compatibility is required.
• Some features listed in the changelog are gated by documentdb.* feature flags. Verify flag defaults in the exact installed build before documenting behavior as always-on.
• documentdb_extended_rum is relocatable, but documentdb and documentdb_core are not.