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

Config this extension to shared_preload_libraries:

shared_preload_libraries = 'pg_documentdb_core, pg_cron, pg_documentdb';

Create this extension with:

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

Usage

Sources:

• DocumentDB v1.0-0 README
• DocumentDB v1.0-0 changelog
• documentdb control file
• Official preload helper
• DocumentDB 1.0 release

documentdb is the public PostgreSQL API extension for DocumentDB, an open-source MongoDB-compatible document database built on PostgreSQL. It stores BSON documents and implements CRUD, aggregation, full-text, geospatial, and vector workflows. MongoDB drivers require the separate DocumentDB gateway; installing this extension alone exposes the PostgreSQL API, not a wire-protocol listener.

Configure and Install

The official deployment helper preloads the core and API libraries with pg_cron. Restart PostgreSQL after changing this setting:

shared_preload_libraries = 'pg_cron, pg_documentdb_core, pg_documentdb, pg_documentdb_extended_rum'

Install the public extension and its declared dependencies:

CREATE EXTENSION documentdb CASCADE;
CREATE EXTENSION documentdb_extended_rum;

CASCADE can install documentdb_core, pg_cron, tsm_system_rows, vector, and postgis when their files are present. Installation is superuser-only and non-relocatable.

Native SQL Workflow

The SQL surface uses a database name, collection name, and BSON command document:

SELECT documentdb_api.create_collection('appdb', 'people');

SELECT documentdb_api.insert_one(
  'appdb',
  'people',
  '{"_id": 1, "name": "Ada", "team": "storage"}',
  NULL
);

SELECT document
FROM documentdb_api_catalog.bson_aggregation_find(
  'appdb',
  '{"find":"people","filter":{"team":"storage"}}'
);

For application compatibility, run the gateway and use a supported MongoDB driver against its configured TLS endpoint. The gateway translates wire-protocol commands into this PostgreSQL API.

Important Objects

• documentdb_api contains collection-management and command functions such as create_collection and insert_one.
• documentdb_api_catalog.bson_aggregation_find executes a MongoDB-style find specification and returns BSON documents.
• documentdb_core.bson is the storage and interchange type supplied by documentdb_core.
• DocumentDB roles and internal schemas separate public read/write operations from administrative and implementation objects.
• documentdb.enableNonBlockingUniqueIndexBuild controls the v0.114 path for background unique ordered-index builds and is enabled by default in that release.

Version and Operational Notes

Release 1.0-0 adds the first generally available release line. It fixes permission checks for zero-batch reads and write permissions for merge/output targets, along with crash, geospatial ordering and index-vacuum bugs. Custom role CRUD and post-join nested lookup remain disabled by default behind their settings. Match all libraries and apply the release upgrade SQL.

The official DocumentDB Local container enables usage telemetry by default; native packages are unaffected. Set DOCUMENTDB_USAGE_TELEMETRY=false, NO_ANALYTICS=1 or DO_NOT_TRACK=1 to disable it in the container.

MongoDB compatibility is not identical to every MongoDB server version. Test operators, index behavior, transactions, schema validation, authentication, and driver behavior used by the application. Match documentdb, documentdb_core, gateway, and optional distributed/index components to the same release line.