hanzo-documentdb

DocDB is a MongoDB-compatible document database server.

Hanzo DocDB - MongoDB-Compatible Document Database

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-kv-go.md, hanzo/go-sdk.md

Overview

DocDB is a MongoDB-compatible document database server. It is a proxy that converts MongoDB 5.0+ wire protocol queries to SQL, using PostgreSQL with the DocumentDB extension as the storage engine. This is a full server, not a client library. Any MongoDB driver or tool can connect to it directly.

Fork of FerretDB. Repo: hanzoai/documentdb, branch: main.

Quick reference

| Item | Value | |------|-------| | Module | github.com/hanzoai/docdb | | Binary | docdb | | Go | 1.26+ | | Repo | github.com/hanzoai/documentdb | | Branch | main | | License | Apache-2.0 | | Wire protocol | MongoDB 5.0+ | | Backend | PostgreSQL + DocumentDB extension | | Default port | 27017 | | Docker image | ghcr.io/hanzoai/docdb-eval:2 |

Architecture

Application (any MongoDB driver)
 |
 | MongoDB wire protocol (BSON)
 v
 DocDB proxy (this project)
 |
 | PostgreSQL protocol (SQL)
 v
 PostgreSQL + DocumentDB extension

Quick start (Docker)

docker run -d --rm --name docdb -p 27017:27017 \
 -e POSTGRES_USER=myuser \
 -e POSTGRES_PASSWORD=mypass \
 ghcr.io/hanzoai/docdb-eval:2

Connect with any MongoDB client:

mongosh "mongodb://myuser:[email protected]:27017/"

Or connect to the embedded PostgreSQL:

docker exec -it docdb psql -U myuser postgres

Building from source

go build -o docdb ./cmd/docdb
./docdb --listen-addr=:27017 --postgresql-url=postgres://user:pass@localhost:5432/dbname

Go library embedding

DocDB can be embedded in Go applications:

import "github.com/hanzoai/docdb/v2/docdb"

See pkg.go.dev/github.com/hanzoai/docdb/v2/docdb for the embeddable API.

Key features

Drop-in MongoDB replacement for most 5.0+ workloads
Uses PostgreSQL as the storage backend (ACID, proven reliability)
Any MongoDB driver or tool works (mongosh, Compass, pymongo, etc.)
SCRAM authentication
Prometheus metrics endpoint
OpenTelemetry tracing
MCP (Model Context Protocol) integration
Health/readiness endpoints

Project structure

| Path | Purpose | |------|---------| | cmd/docdb/ | Main binary entry point | | cmd/envtool/ | Development environment tool | | docdb/ | Embeddable library package | | internal/ | Core implementation (handlers, backends, wire protocol) | | integration/ | Integration test suite | | build/ | Build configurations, certs, Docker deps |

Build and test

# Build
go build ./cmd/docdb

# Unit tests
go test ./...

# Integration tests (requires PostgreSQL)
go test ./integration/...

# Task runner (alternative to make)
task test
task build

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: documentdb, mongodb, postgresql, database, server Prerequisites: Go 1.26+, PostgreSQL with DocumentDB extension