Hanzo DocDB

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:mypass@127.0.0.1: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

On this page