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:

• Full compatibility with the MongoDB wire protocol through the pg_documentdb_gw gateway
• 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
• Enterprise-grade security with SCRAM authentication
• 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
• Cloud Ready: Supports multi-cloud deployments across major cloud providers with native integration in Azure Cosmos DB
• Developer Friendly: Rich ecosystem of tools and extensions, including VS Code integration and MongoDB compatibility

Architecture Components

DocumentDB consists of three 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.

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

If you're new to DocumentDB, use this order:

1. Docker Quick Start - Fastest local install for evaluation and development
2. Mongo Shell Quick Start - Verify connectivity, authentication, and your first queries
3. Node.js Quick Start or Python Quick Start - Connect from an application driver
4. Linux Packages Quick Start or the Package Finder - Use this when you need a persistent Linux installation instead of Docker

If you prefer an editor-first workflow, start with the Visual Studio Code Quick Start.

Verify your setup

Before moving on to application code, confirm that DocumentDB is reachable and you can run a simple query.

docker ps --filter "name=documentdb"

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

Then run:

db.runCommand({ ping: 1 })

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:

• 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 certificate steps in DocumentDB Local.
• For more verbose local diagnostics, restart DocumentDB Local with --log-level debug; the available runtime options are documented in DocumentDB Local.
• If you are installing on a host instead of Docker, use Linux Packages Quick Start or the Package Finder to get the correct apt or rpm flow.

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