The Evolution of Document Databases and the Licensing Dilemma

For over a decade, MongoDB has been the de facto standard for developers seeking a flexible, document-oriented database. Its schemaless design, intuitive query language, and scalable architecture powered thousands of modern applications. However, the landscape shifted dramatically when MongoDB transitioned from the open-source GNU Affero General Public License (AGPL) to the Server Side Public License (SSPL). This change sent shockwaves through the enterprise software ecosystem.

The SSPL introduces strict compliance requirements, demanding that anyone offering MongoDB as a service must open-source their entire management platform. For many businesses, enterprises, and cloud providers, this created significant legal and financial risks, effectively ending MongoDB's era as a purely open-source technology. Organizations now face a difficult choice: accept restrictive vendor lock-in, pay steep commercial licensing fees, or undergo a costly, risk-heavy database migration. Fortunately, a disruptive alternative has emerged: FerretDB combined with PostgreSQL.

What is FerretDB? The Open-Source MongoDB Proxy

FerretDB is an open-source, production-ready translation proxy that allows developers to run MongoDB workloads on top of relational database engines, primarily PostgreSQL. Written in Go and distributed under the permissive Apache 2.0 license, FerretDB acts as a compatibility layer. It intercepts standard MongoDB wire protocol queries and translates them into native SQL commands execution by the backend database.

By implementing FerretDB, organizations gain a powerful architectural advantage:

Zero Application Rewrites: Your existing application code, drivers, and toolkits (such as Mongoose, Prisma, or the official MongoDB SDKs) communicate with FerretDB exactly as they would with a native MongoDB instance.
True Open-Source Compliance: Both FerretDB (Apache 2.0) and PostgreSQL (PostgreSQL License) are genuinely open-source, eliminating any threat of sudden licensing changes or commercial audits.
Leveraging PostgreSQL Reliability: Instead of managing a separate, specialized NoSQL infrastructure, you benefit from the decades of engineering, ACID compliance, data integrity, and robust ecosystem built around PostgreSQL.

Architectural Blueprint: How FerretDB Translates NoSQL to SQL

To fully understand the reliability of this setup, we must look at how FerretDB maps document data structures into a relational framework. In a standard MongoDB deployment, data is stored in collections as BSON documents. When using FerretDB with a PostgreSQL backend, the proxy creates an elegant relational mapping system automatically.

Database and Collection Mapping

Each MongoDB database corresponds directly to a PostgreSQL schema. Within that schema, every MongoDB collection is represented as a PostgreSQL table. This clear, structural mapping ensures that your database administrators can easily inspect, analyze, and optimize the underlying storage using standard SQL tools.

Document Storage via JSONB

The core magic relies on PostgreSQL's advanced JSON capabilities. Every MongoDB document within a collection is stored as a row inside a table featuring a specialized binary JSON column called jsonb. FerretDB automatically extracts the MongoDB _id field to serve as the table's primary key, ensuring rapid lookups and maintaining document uniqueness constraint requirements.

"FerretDB does not reinvent the storage engine. Instead, it builds a highly efficient bridge that transforms MongoDB’s document model into PostgreSQL's battle-tested JSONB format, combining the best of both worlds."

Step-by-Step Guide: Configuring FerretDB with PostgreSQL

Setting up FerretDB alongside PostgreSQL is straightforward, particularly when utilizing containerized environments. Below is a comprehensive guide to deploying this stack using Docker Compose, which is ideal for development, testing, and microservices environments.

1. Preparing the Deployment Environment

Ensure you have Docker and Docker Compose installed on your host system. Create a new directory for your project and navigate into it. Inside this directory, you will define the multi-container architecture.

2. Creating the Docker Compose Configuration

Create a file named docker-compose.yml and populate it with the following multi-service configuration:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: ferretdb_backend_postgres
    environment:
      POSTGRES_USER: ferret_user
      POSTGRES_PASSWORD: secure_password_123
      POSTGRES_DB: ferretdb_store
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always

  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:latest
    container_name: ferretdb_proxy
    environment:
      FERRETDB_POSTGRESQL_URL: "postgres://ferret_user:secure_password_123@postgres:5432/ferretdb_store"
      FERRETDB_LISTEN_ADDR: "0.0.0.0:27017"
    ports:
      - "27017:27017"
    depends_on:
      - postgres
    restart: always

volumes:
  pgdata:

3. Launching the Services

Execute the following command in your terminal to spin up the infrastructure in detached mode:

docker-compose up -d

This command downloads the lightweight Alpine-based PostgreSQL 16 image and the latest FerretDB proxy image. It establishes a secure backend bridge, opening port 27017—the default MongoDB port—to the host machine.

Connecting Your Existing Applications and Tools

Once the containers are running, verifying the deployment is simple. You can use standard MongoDB administrative tools like Mongosh (the MongoDB Shell) or graphical user interfaces like MongoDB Compass to connect to your new, completely open-source backend.

Verifying via Mongosh

Run the following command to connect directly via the standard MongoDB connection string format:

mongosh "mongodb://127.0.0.1:27017/test_db"

Once connected, you can execute standard CRUD operations flawlessly. For example, inserting a document and querying it looks identical to native MongoDB:

db.customers.insertOne({ name: "Acme Corp", industry: "Technology", active: true });
db.customers.find({ active: true });

Behind the scenes, FerretDB intercepts these commands, parses the BSON, and executes highly optimized SQL queries against your ferretdb_store database in PostgreSQL. If you connect to your PostgreSQL container via psql, you will find a schema named test_db and a table named customers containing a _id column and a _jsonb data object.

Performance, Production Readiness, and Key Trade-offs

While the prospect of running MongoDB applications for free without licensing compliance stress is highly appealing, engineering teams must evaluate the technical considerations before moving large production environments to this architecture.

When is FerretDB the Perfect Choice?

FerretDB is exceptionally well-suited for several business scenarios:

SaaS Providers and Independent Software Vendors (ISVs): If you distribute software that requires a document store, bundling native MongoDB forces your customers into complex SSPL licensing agreements or demands expensive commercial sub-licenses. FerretDB lets you ship a fully open-source NoSQL stack.
Enterprise Migration and Standardization: Many enterprises have standard IT policies prioritizing PostgreSQL due to existing vendor relationships, security hardening, and internal DBA expertise. FerretDB allows development teams to build with document structures while satisfying enterprise database infrastructure mandates.
Greenfield Applications and Startups: Teams that appreciate MongoDB’s rapid prototyping speed but want to guarantee absolute freedom from future vendor pricing shocks can safely build on FerretDB from day one.

Current Limitations and Engineering Trade-offs

Because FerretDB is a translation layer, it does not yet support 100% of MongoDB's extensive feature set. Highly complex, niche aggregation pipeline stages, specific geospatial indexing strategies, or internal administrative database commands might return compatibility warnings. It is critical to execute automated integration test suites for your application against a FerretDB staging environment to confirm feature coverage. Additionally, high-throughput, ultra-low-latency workloads may experience minor processing overhead due to the query translation layer compared to native, bare-metal C++ MongoDB binaries.

Conclusion: Embracing Architectural Independence

The combination of FerretDB and PostgreSQL represents a massive win for the open-source community and corporate technology strategists alike. It breaks down artificial licensing walls, empowers developers to write code using preferred document abstractions, and provides financial peace of mind to stakeholders. By deploying FerretDB, your organization secures a future-proof data layer built upon the unmatched reliability of PostgreSQL—completely free from commercial licensing audits and vendor lock-in.

FerretDB and PostgreSQL: Running MongoDB Applications Without Commercial Licensing Worries