What is DocumentDB?

DocumentDB provides a NoSQL datastore implemented using PostgreSQL, giving developers complete visibility into the architecture and implementation of the engine. It's designed to offer:

• MongoDB wire protocol compatibility through the pg_documentdb_gw gateway, so MongoDB drivers and tools connect unmodified
• Public document CRUD and management APIs through the pg_documentdb extension
• Native BSON document support via the pg_documentdb_core PostgreSQL extension
• Advanced indexing capabilities including single field, multi-key, compound, text, geospatial, and vector indexes
• Vector search functionality powered by the pgvector PostgreSQL extension
• SCRAM-SHA-256 authentication and TLS on the gateway
• Full PostgreSQL compatibility for advanced SQL operations

Key Features

• PostgreSQL Foundation: Built on the powerful PostgreSQL engine, allowing you to leverage both document and relational capabilities
• Open Source: Released under the MIT license with no restrictions on usage, modification, or distribution
• Document Database Standard: First implementation towards creating an open standard for document databases, similar to ANSI SQL for relational databases
• Runs anywhere: Linux packages, a container image for local development, and a Kubernetes operator for replicated deployments
• Developer Friendly: Rich ecosystem of tools and extensions, including VS Code integration and MongoDB compatibility

Architecture Components

DocumentDB consists of four primary components:

1. pg_documentdb_core: Core PostgreSQL extension that provides native BSON storage, field access, and indexing primitives.
2. pg_documentdb: Public API surface that implements document commands, CRUD operations, query execution, and index management.
3. pg_documentdb_gw: Gateway that translates MongoDB wire protocol requests into PostgreSQL operations and handles authentication, sessions, and TLS.
4. pg_documentdb_extended_rum: The index access method behind DocumentDB's document indexes, required in 1.0.

Together, these components let you use DocumentDB through MongoDB-compatible tools and drivers while still benefiting from PostgreSQL internals.

Common Use Cases

• Modern Web Applications: Store and query JSON documents with MongoDB compatibility
• AI/ML Applications: Leverage vector search for similarity matching and embeddings
• Hybrid Data Models: Combine document and relational data in the same database
• Migration Path: Easy transition from existing MongoDB workloads
• Local Development: Full-featured local instance for development and testing

Start here

Choose your environment once, create a working instance, then connect with the client that fits your goal:

1. Choose Docker or Linux packages. Docker installation is recommended for evaluation and development on Linux, macOS, or Windows. Linux packages installation is for environments without Docker, or when you need control over PostgreSQL, topology, services, and configuration.
2. Create a working instance. Follow the Docker Quick Start or Linux Packages Quick Start. Linux package installation has two stages: install packages, then run the setup wizard. Neither copying a command nor installing files alone proves the endpoint is ready.
3. Insert and read your first document. Use the Visual Studio Code Quick Start, Node.js Quick Start, or Python Quick Start. Keep the same running instance; no second server installation is needed.

For advanced control, use an existing local PostgreSQL instance with administrator-managed configuration and restart, or install the PostgreSQL extension only. Extension-only installation does not install the gateway, so apps and drivers cannot connect; you use it through SQL.

Verify your setup

Before moving on to application code, confirm that DocumentDB is reachable and can insert and read a document. For Docker, check docker ps --filter "name=documentdb" and wait for the readiness banner in docker logs documentdb; for Linux packages, inspect sudo documentdb-setup --status.

Run this shell example on the same host as DocumentDB. Use your Docker username, or admin for Linux packages, and enter your password at the prompt.

The certificate bypass is for local development only. Linux package setup binds the gateway on all interfaces by default: firewall port 10260 before setup and follow network and certificate guidance.

mongosh localhost:10260 \
  -u '<YOUR_USERNAME>' \
  -p \
  --authenticationMechanism SCRAM-SHA-256 \
  --tls \
  --tlsAllowInvalidCertificates

Then run:

db.runCommand({ ping: 1 })
use quickstart
db.orders.insertOne({ item: "widget", qty: 5 })
db.orders.find({ item: "widget" })

The insert should report acknowledged: true, and the query should return your document. No sample-data loading is required.

For a fuller walkthrough, use the Mongo Shell Quick Start. Driver-based examples are available in the Node.js Quick Start and Python Quick Start.

Troubleshooting and debugging

If setup does not work on the first try:

• For Linux packages, check sudo documentdb-setup --status and package troubleshooting. The default PostgreSQL 18 install uses documentdb-local@18.target, not the meta-package alias.
• For Docker, confirm the container is running and port 10260 is published with docker ps. Inspect startup, authentication, and TLS errors with docker logs documentdb.
• If you want certificate validation instead of tlsAllowInvalidCertificates=true, follow the Linux package certificate steps or DocumentDB Local for Docker.
• For more verbose Docker diagnostics, re-create DocumentDB Local with -e DOCUMENTDB_LOG_LEVEL=debug (the --log-level flag is currently a no-op); the available runtime options are documented in DocumentDB Local.
• To change your installation choice, open Docker installation or Linux packages installation.

Explore key features

Once you can connect successfully, continue with these guides:

• API Reference - MongoDB command and operator coverage
• Postgres Extension API - PostgreSQL-side functions, types, and operators
• DocumentDB Local - Local runtime options, sample data, certificates, and feature notes
• Architecture under the hood - How the core, extension, and gateway fit together
• Samples Gallery - End-to-end examples you can adapt for your own apps

Community and Support

• Discord Community: Join our Discord server for:
  • Community syncs and office hours
  • Real-time technical support
  • Migration assistance
  • Best practices sharing
• GitHub Repository: documentdb/documentdb
• Documentation: Comprehensive guides and API references
• Issue Tracking: Report bugs and request features on GitHub

Next Steps

After you finish the initial setup:

• Continue with the Mongo Shell Quick Start, Node.js Quick Start, or Python Quick Start
• Explore the API Reference for detailed command and operator documentation
• Join our community to get support and contribute