documentdb_distributed

Overview

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
pig ext install -y documentdb -v 15  # PG 15

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

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

Preload:

shared_preload_libraries = 'citus, pg_documentdb, pg_documentdb_core';

Create Extension:

CREATE EXTENSION documentdb_distributed CASCADE;  -- requires: citus, documentdb_core, documentdb

Usage

Sources:

• documentdb_distributed v0.114-0 control file
• DocumentDB package scope
• Official preload helper
• DocumentDB v0.114-0 changelog

documentdb_distributed is DocumentDB’s internal multi-node execution layer. It integrates the public documentdb API with Citus; it is not a standalone document API and does not add a separate client workflow.

Prerequisites and Install

All nodes need matching builds of Citus, documentdb_core, documentdb, and documentdb_distributed. The official helper places the libraries in preload order; restart every node after changing it:

shared_preload_libraries = 'citus, pg_cron, pg_documentdb_core, pg_documentdb, pg_documentdb_distributed'

After the Citus topology and the base DocumentDB stack are configured, install the distributed component as a superuser:

CREATE EXTENSION documentdb CASCADE;
CREATE EXTENSION documentdb_distributed;

SELECT extname, extversion
FROM pg_extension
WHERE extname IN ('citus', 'documentdb_core', 'documentdb', 'documentdb_distributed');

Use the normal DocumentDB gateway or documentdb_api functions after installation. Collection placement, shard topology, worker availability, and metadata consistency must be managed as part of the cluster deployment.

Important Boundaries

• The control file requires citus, documentdb_core, and documentdb and marks the extension superuser-only and non-relocatable.
• documentdb_distributed supplies distributed planner and execution support to existing DocumentDB commands; it is not an alternative to the public API extension.
• Release versions should remain synchronized across coordinators and workers before extension upgrades are attempted.
• Backup, restore, failover, and rolling-upgrade procedures must include both Citus metadata and DocumentDB data.

The upstream packaging/README.md explicitly says the standard packages do not include the internal/pg_documentdb_distributed component. Confirm that a distribution actually ships this extension before adding it to configuration. Version 0.114-0 includes a sharded $sample optimization fix behind a feature flag; it should not be treated as unconditional behavior.