Back to Documentation

Getting Started

Recommended flow

Install and verify DocumentDB

Choose one install path first. After DocumentDB is running, verify the connection with mongosh before moving to a driver quick start.

1

Choose an install path

Use Docker for the fastest local setup, or Linux packages for a persistent host installation.

Run locally with Docker

Best for evaluation, local development, and quick testing.

Docker
docker run -dt --name documentdb \
  -p 10260:10260 \
  ghcr.io/documentdb/documentdb/documentdb-local:latest \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD>
Docker Quick Start

Install from Linux packages

Use the repository-backed package flow when you want a persistent server install. Generate the exact apt or rpm command with the Package Finder.

Linux Packages Quick Start
2

Recommended: verify with mongosh

This is the fastest shared validation path after either install option because it confirms authentication, TLS, and a working endpoint before you add editor or driver setup. If you already know your target workflow, you can skip this and continue directly with VS Code or a driver quick start.

Mongo Shell Quick Start

Or go directly to Visual Studio Code Quick Start, Node.js Quick Start or Python Quick Start.

Getting Started

DocumentDB is an open-source document database platform built on PostgreSQL. It offers developers a fully permissive, open-source platform for document data stores.

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-compatible document operations through the pg_documentdb extension and pg_documentdb_gw gateway
  • Native BSON document support via the pg_documentdb_core PostgreSQL extension
  • Advanced indexing capabilities including single field, multi-key, compound, text, and geospatial indexes
  • Vector search functionality powered by the pg_vector 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:

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: