FerretDB is an open-source drop-in replacement for MongoDB that proxies MongoDB’s wire protocol to PostgreSQL with a DocumentDB extension. It allows developers to use existing MongoDB drivers, tools, and query syntax while storing data in a fully open-source, PostgreSQL-based backend. This solves the problem of vendor lock-in and restrictive licensing (like SSPL) that MongoDB adopted after its open-source phase.
Built in Go, FerretDB supports deployment via Docker, native binaries, and cloud providers like Civo, Tembo, and Elestio. It integrates with the entire MongoDB ecosystem — including MongoDB Compass, Studio 3T, and mongosh — while leveraging PostgreSQL’s reliability, scalability, and community-driven development. The project also offers a Go library for embedding FerretDB directly into applications.
What You Get
- MongoDB Wire Protocol Proxy - FerretDB translates MongoDB 5.0+ wire protocol commands (BSON) into SQL queries, allowing unmodified MongoDB drivers and clients to connect without changes.
- PostgreSQL with DocumentDB Extension - Uses PostgreSQL as the storage engine enhanced with a DocumentDB extension to handle document-oriented data structures natively in SQL.
- Drop-in MongoDB Compatibility - Works with MongoDB drivers, tools like MongoDB Compass, Studio 3T, MingoUI, and the mongosh shell without requiring application rewrites.
- Docker-based All-in-One Deployment - Provides pre-built Docker images with embedded PostgreSQL and DocumentDB extension for quick testing and development environments.
- Go Library Embedding - Includes a Go package (github.com/FerretDB/FerretDB/v2/ferretdb) to embed FerretDB directly into Go applications as a library, not just a standalone server.
- Cloud-Managed Options - Officially supported on FerretDB Cloud, Civo, Tembo, Elestio, and Cozystack, enabling managed deployments without self-hosting complexity.
Common Use Cases
- Migrating from MongoDB due to SSPL license - A startup using MongoDB switches to FerretDB to avoid SSPL licensing restrictions while preserving existing MongoDB drivers and tooling.
- Building a document-based app with open-source stack - A developer builds a SaaS application using MongoDB-compatible APIs but requires full control over data and infrastructure using PostgreSQL.
- Legacy MongoDB workload modernization - An enterprise with legacy MongoDB workloads migrates to FerretDB to eliminate vendor lock-in and leverage PostgreSQL’s enterprise-grade features like replication and backups.
- Developing MongoDB-compatible tools without MongoDB dependency - A tool vendor creates a MongoDB UI or migration utility and uses FerretDB as a lightweight, embeddable backend for testing and demos.
Under The Hood
Architecture
- Clear separation of concerns through modular directories handling protocol parsing, document logic, and storage abstraction
- Dependency injection via constructor-based interfaces enables testability and multi-backend support
- Custom BSON serialization layer decouples protocol handling from MongoDB’s official driver
- Storage backends are abstracted behind a unified interface using the Strategy pattern
- Command-dispatch pattern implemented via state machine-driven message handlers for MongoDB wire protocol
- Code generation automates boilerplate while preserving manual control over critical paths
Tech Stack
- Go as the primary language with well-structured internal packages for protocol and query execution
- PostgreSQL and YugabyteDB as primary storage engines with extended DocumentDB capabilities
- MongoDB wire protocol emulation implemented without vendor dependencies
- Comprehensive build and testing infrastructure with automated linting, Dockerized environments, and task automation
- Custom wire protocol parser and internal document model to avoid MongoDB driver lock-in
- Observability integrated via distributed tracing and structured logging in containerized environments
Code Quality
- Extensive test coverage with unit, integration, and benchmark tests using standardized assertion libraries
- Consistent error handling with protocol-compliant error wrappers and preserved stack traces
- Strong type safety enforced through BSON validation, typed constants, and explicit type assertions
- Clear naming conventions and descriptive function names that reflect behavior over implementation
- Structured logging and database instrumentation provide deep observability in production scenarios
What Makes It Unique
- Fully open-source implementation of MongoDB’s wire protocol, enabling seamless client compatibility without modifications
- Pluggable storage architecture supporting multiple backends while preserving MongoDB API semantics
- Formal API contract derived from MongoDB Atlas Data API to ensure precise behavioral parity
- Query translation layer that converts MongoDB aggregation pipelines into native SQL queries
- Distributed query engine that maintains transactional semantics across heterogeneous data sources