Files
skills/public/hanzo-documentdb.md

2.9 KiB

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