documentdb

Overview

DocumentDB 1.0 packages install SQL 1.0-0. PGSTY supports PostgreSQL 16-18; PG15 is excluded due to the libbson allocation alignment failure. The OSS package includes documentdb, documentdb_core and documentdb_extended_rum only. External RUM is a package dependency on PG16/17 only, not PG18.

Version

Build

You can build the RPM / DEB packages for documentdb using pig build:

pig build pkg documentdb         # build RPM / DEB packages

Install

You can install documentdb directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

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

Install the extension using pig or apt/yum/dnf:

pig install documentdb;          # Install for current active PG version

pig ext install -y documentdb -v 18  # PG 18
pig ext install -y documentdb -v 17  # PG 17
pig ext install -y documentdb -v 16  # PG 16

dnf install -y documentdb_18       # PG 18
dnf install -y documentdb_17       # PG 17
dnf install -y documentdb_16       # PG 16

apt install -y postgresql-18-documentdb   # PG 18
apt install -y postgresql-17-documentdb   # PG 17
apt install -y postgresql-16-documentdb   # PG 16

Preload:

shared_preload_libraries = 'pg_documentdb_core, pg_cron, pg_documentdb';

Create Extension:

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.