FerretDB

FerretDB is a proxy server written in Go that converts MongoDB 5.0+ wire protocol queries into SQL and uses PostgreSQL with the DocumentDB extension as its storage engine. It enables any application using a MongoDB driver — without any code changes — to run against a fully open-source, PostgreSQL-backed database stack, eliminating the SSPL licensing restrictions that MongoDB introduced.

The project addresses a real gap: most MongoDB users do not need MongoDB’s advanced proprietary features, yet they are locked into a commercially restrictive license. FerretDB lets teams keep their MongoDB driver, tooling, and query syntax while gaining the operational benefits of PostgreSQL: ACID transactions, robust replication, mature backup tooling, and a thriving open-source ecosystem.

FerretDB supports deployment via Docker, pre-built Linux packages, or directly as a Go library embedded into an application. It integrates with the broader MongoDB tooling ecosystem — MongoDB Compass, Studio 3T, mongosh, mongodump/mongorestore — as well as cloud-managed offerings through FerretDB Cloud, Civo, Tembo, Elestio, and Cozystack. A built-in MCP (Model Context Protocol) server was added in v2.7.0, enabling AI agents to query FerretDB databases using natural language tools.

Version 2.x introduced a major architectural shift: the storage engine moved from a custom Go-based SQL translation layer to a dedicated PostgreSQL extension called DocumentDB, which handles document semantics natively at the database level. This change significantly improved compatibility coverage and performance, and aligns FerretDB’s roadmap with upstream DocumentDB improvements.

What You Get

• MongoDB Wire Protocol Translation - FerretDB listens on the standard MongoDB port (27017), accepts BSON-encoded wire protocol messages from any MongoDB 5.0+ compatible driver, and forwards translated SQL calls to PostgreSQL — no driver changes required.
• PostgreSQL with DocumentDB Extension - Document data is stored in PostgreSQL using the open-source DocumentDB extension, which handles BSON-to-SQL mapping, indexing, and query execution natively inside the database engine.
• Drop-in Tooling Compatibility - Works out of the box with MongoDB Compass, Studio 3T, mongosh, mongodump, mongorestore, and application frameworks that target MongoDB, letting teams migrate without rewriting tooling or operational scripts.
• Embeddable Go Library - The github.com/FerretDB/FerretDB/v2/ferretdb package lets Go developers embed a full FerretDB instance directly inside their application process, useful for testing or single-binary distribution.
• MCP Server for AI Agents - A built-in Model Context Protocol server (added in v2.7.0) exposes tools like find, listCollections, and listDatabases, letting AI coding assistants and LLM agents query the database in natural language workflows.
• Data API over HTTP - An optional HTTP-based Data API provides REST access to documents, useful for serverless environments or clients that cannot use the MongoDB binary protocol.
• Prometheus Metrics and OpenTelemetry Tracing - Built-in observability with Prometheus metrics and OpenTelemetry distributed tracing for production monitoring and debugging.
• Cloud-Managed Deployments - Available as a managed service through FerretDB Cloud, Civo, Tembo, Elestio, and Cozystack for teams that want MongoDB compatibility without self-hosting PostgreSQL.

Common Use Cases

• Escaping MongoDB SSPL licensing - A startup that built on MongoDB’s community edition discovers SSPL prevents them from distributing their SaaS product; they migrate to FerretDB and keep the same driver, queries, and tooling while moving storage to a license-clean PostgreSQL stack.
• Building new apps on an open-source document stack - A developer starting a new project wants MongoDB’s flexible document model but needs a fully open-source backend; FerretDB on PostgreSQL gives them both without adopting a proprietary product.
• Migrating legacy MongoDB workloads to PostgreSQL - An enterprise running MongoDB for years wants to unify on PostgreSQL for operational simplicity — single backup strategy, familiar DBA tooling, existing replication — and uses FerretDB as the compatibility shim during migration.
• Developing and testing MongoDB-backed tools without MongoDB - A vendor building a MongoDB GUI or migration utility uses FerretDB as a lightweight embeddable backend in CI/CD pipelines and integration tests, avoiding MongoDB licensing fees in non-production environments.
• AI agent database access via MCP - A team building an LLM-powered application registers FerretDB’s MCP server with their AI coding assistant, enabling natural-language queries against MongoDB-compatible collections stored in PostgreSQL.

Under The Hood

Architecture FerretDB follows a clean layered proxy architecture: an inbound TCP listener accepts MongoDB wire protocol connections, passes them through a middleware layer that handles authentication, tracing, and metrics, then dispatches to per-command handlers. Each handler extracts the relevant BSON parameters and delegates to a DocumentDB connection pool, which executes SQL functions against PostgreSQL with the DocumentDB extension. The v2 architecture removes the earlier custom Go-based SQL translation in favour of pushing document semantics down into the PostgreSQL extension, which drastically simplifies the Go code and improves correctness. A separate Data API listener handles HTTP-based REST access through a generated OpenAPI server. An MCP server sits alongside these listeners and reuses the same middleware and handler stack, avoiding duplication. Cursor state is managed in-process, and connection pooling is handled explicitly to avoid unnecessary pool exhaustion.

Tech Stack The server is written in Go 1.25 using only the standard library and a small set of carefully chosen dependencies: the custom FerretDB/wire package for MongoDB wire protocol parsing and serialization, jackc/pgx/v5 for PostgreSQL connection pooling, modelcontextprotocol/go-sdk for the MCP server, prometheus/client_golang for metrics, and OpenTelemetry for distributed tracing. The DocumentDB PostgreSQL extension handles all document-level SQL translation. Build automation runs through Taskfile, Docker-based integration environments, and GitHub Actions CI covering linting, security scanning, and cross-backend compatibility tests against both standard PostgreSQL and YugabyteDB.

Code Quality The codebase demonstrates strong discipline: each MongoDB command has a dedicated handler file (e.g. msg_find.go, msg_aggregate.go), making the command surface easy to audit. Error handling uses the lazyerrors package to preserve stack traces without the overhead of structured error wrapping everywhere. Test coverage is extensive — the integration/ directory contains hundreds of compatibility tests that run against both FerretDB and real MongoDB to detect behavioral differences. The compat test pattern explicitly marks known divergences rather than silently skipping them. A Codecov integration tracks flaky tests, and linting is enforced via golangci-lint in CI. Go’s type system is used throughout; there are no interface{} escapes in core paths.

What Makes It Unique FerretDB’s most distinctive technical choice is protocol-level compatibility: by speaking MongoDB’s binary wire protocol and BSON encoding directly, rather than emulating a MongoDB REST API, it is genuinely transparent to unmodified drivers and tools. The shift in v2 to delegate document storage to the DocumentDB PostgreSQL extension means FerretDB itself is no longer in the business of SQL generation — it routes BSON to a purpose-built extension that understands document semantics, then routes the result back as BSON. This architecture makes FerretDB’s compatibility ceiling determined by the DocumentDB extension rather than by hand-written Go SQL logic, which accelerates coverage of MongoDB’s command surface. The addition of an MCP server in v2.7.0 is an early but concrete move toward making the database natively accessible to AI agent workflows.

Self-Hosting

FerretDB is released under the Apache License 2.0, one of the most permissive open-source licenses available. You can use it commercially, modify the source, distribute it as part of a product, and embed it in proprietary software without copyleft obligations. There is no SSPL, no Commons Clause, and no contributor license agreement that restricts how you use your own data. The license applies to the FerretDB Go codebase; the DocumentDB PostgreSQL extension that FerretDB depends on for storage is separately licensed under the Apache License 2.0 by Amazon.

Running FerretDB yourself means operating two pieces of infrastructure: PostgreSQL with the DocumentDB extension installed, and the FerretDB proxy process itself. The Docker quickstart bundles both into a single container for evaluation, but production deployments should treat them as separate services with independent lifecycle management. You are responsible for PostgreSQL backups, replication configuration, major version upgrades, and performance tuning. The DocumentDB extension adds a non-trivial PostgreSQL customization that may require careful planning for upgrades and is not part of standard managed PostgreSQL offerings like AWS RDS or Google Cloud SQL — you would need a compatible deployment such as Tembo, or a self-managed PostgreSQL instance.

Compared to FerretDB Cloud or other managed FerretDB offerings, self-hosting gives you full data sovereignty and eliminates per-usage costs, but you give up managed upgrades, SLA guarantees, automated backups, and infrastructure monitoring. The open community support channels — Slack and GitHub Discussions — are active and responsive, but there is no formal support contract available unless you engage FerretDB Inc. directly. Teams evaluating self-hosting should also track the compatibility matrix at docs.ferretdb.io to understand which MongoDB commands and operators are fully supported versus partially implemented or delegated to the DocumentDB extension roadmap.