Getting Started navigation
← Back to Documentation

Recommended flow

Choose an environment, then run your first query

Install with Docker or Linux packages once. Create a working instance, then insert and read a document using a shell, driver, or editor.

1

Choose an install path

Start with Docker on Linux, macOS, or Windows. Use Linux packages when you need a host installation.

Docker: recommended for evaluation and development

With Docker installed, run a local instance on Linux, macOS, or Windows. Replace the credential placeholders before running. The port stays on loopback.

Start Docker

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

Wait for the readiness banner in docker logs documentdb before connecting.

Docker Quick Start

Linux packages

For environments without Docker, or when you need control over PostgreSQL, topology, services, and configuration. Install with apt or dnf on Ubuntu 24.04 (Noble) or EL9, then run the setup wizard.

Pre-GA, fresh installation only; in-place upgrades from earlier releases are not supported.

Linux packages installation

For the full walkthrough, see the Linux Packages Quick Start.

2

Insert and read your first document

Pick the client you prefer. Each guide connects to the instance you already created and verifies an insert and read. Sample data is optional.

Visual Studio Code Quick Start

Or go directly to 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:

  • 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

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.

Linux packages are pre-GA and support fresh installation only, not in-place upgrades from earlier releases. Removing packages preserves database files; reinstalling does not reset data.

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:

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: