FerretDB — Open Source MongoDB Alternative on PostgreSQL

Introduction

FerretDB was created as a truly open-source alternative to MongoDB after MongoDB switched to the Server Side Public License. It implements the MongoDB wire protocol and translates document queries into SQL, storing data in PostgreSQL or SQLite while letting applications use existing MongoDB drivers and tools unchanged.

What FerretDB Does

• Implements the MongoDB wire protocol so existing MongoDB drivers and tools work without changes
• Translates BSON document operations into SQL queries against PostgreSQL or SQLite
• Supports CRUD operations, aggregation pipeline stages, and common query operators
• Stores documents as JSONB in PostgreSQL, leveraging its indexing and ACID guarantees
• Provides a drop-in replacement path for teams moving away from MongoDB licensing

Architecture Overview

FerretDB acts as a proxy that accepts connections on the MongoDB wire protocol port. Incoming BSON messages are decoded and converted into an internal representation. The query handler translates MongoDB operations (find, insert, update, aggregate) into SQL queries using PostgreSQL JSONB operators or SQLite JSON functions. Results are converted back to BSON and returned to the client through the wire protocol.

Self-Hosting & Configuration

• Run via Docker with a PostgreSQL connection URL as the backend
• Deploy with Docker Compose using the official template for FerretDB plus PostgreSQL
• Configure listen address, TLS certificates, and telemetry via environment variables or flags
• Use SQLite backend for embedded or single-node deployments without a separate database
• Monitor with built-in debug handler and Prometheus-compatible metrics endpoint

Key Features

• Full MongoDB wire protocol compatibility with official MongoDB drivers
• PostgreSQL JSONB storage with GIN indexing for fast document queries
• ACID transactions inherited from the PostgreSQL backend
• No vendor lock-in with standard PostgreSQL backups, replication, and tooling
• SQLite backend option for lightweight embedded deployments

Comparison with Similar Tools

• MongoDB — the original document database; FerretDB offers the same API on open-source PostgreSQL
• PostgreSQL JSONB — raw JSONB queries require SQL; FerretDB provides the familiar MongoDB API
• DocumentDB (AWS) — managed MongoDB-compatible; FerretDB is fully self-hosted and open source
• CouchDB — different query model and replication; FerretDB uses MongoDB's query language
• SurrealDB — multi-model with its own query language; FerretDB maintains MongoDB compatibility

FAQ

Q: Can I migrate from MongoDB to FerretDB? A: Yes. Use mongodump/mongorestore or mongosync. Most applications work without code changes since FerretDB uses the same wire protocol.

Q: Which MongoDB features are supported? A: CRUD operations, most query operators, aggregation pipeline stages, and indexes are supported. Some advanced features like change streams have limited support.

Q: Why use FerretDB instead of plain PostgreSQL JSONB? A: FerretDB lets you use the MongoDB ecosystem (drivers, tools, ODMs like Mongoose) while benefiting from PostgreSQL storage and operations.

Q: How does performance compare to MongoDB? A: For typical workloads, FerretDB performance is comparable. Complex aggregations may be slower due to the translation layer, but PostgreSQL indexing compensates for read-heavy patterns.

Sources

• https://github.com/FerretDB/FerretDB
• https://www.ferretdb.com