Introduction: The Database Dilemma and the Rise of FerretDB

In the modern application development landscape, choosing the right database architecture is a critical decision. For years, developers have faced a structural trade-off: the rigorous consistency and relational integrity of PostgreSQL versus the rapid, document-oriented flexibility of MongoDB. However, as MongoDB transitioned to the Business Source License (BSL), many enterprises and open-source advocates found themselves searching for a truly open alternative that wouldn't require rewriting entire application codebases.

Enter FerretDB. FerretDB serves as an open-source, drop-in replacement for MongoDB that translates MongoDB wire protocol queries into SQL, executing them against a PostgreSQL backend. This innovative architecture allows engineering teams to utilize standard MongoDB drivers, syntax, and tools while storing data in a trusted, ACID-compliant PostgreSQL database. In this comprehensive guide, we will explore the underlying architecture of FerretDB and provide a step-by-step blueprint for deploying it on a Virtual Private Server (VPS).

Why Combine PostgreSQL with the MongoDB API?

Before diving into the technical implementation, it is essential to understand the strategic and operational advantages of this hybrid approach. Running FerretDB on top of PostgreSQL offers several key benefits:

Licensing Peace of Mind: FerretDB is licensed under the Apache 2.0 license, eliminating the compliance and regulatory concerns associated with MongoDB's SSPL/BSL licensing models.
Infrastructure Consolidation: Instead of managing separate clusters for relational and document data, operations teams can standardize on a single, well-understood database backend (PostgreSQL) while still supporting document-store workloads.
ACID Reliability: By leveraging PostgreSQL as the storage engine, your document data inherits PostgreSQL’s battle-tested reliability, advanced indexing, and strict write-ahead logging (WAL).
Ecosystem Compatibility: Because FerretDB emulates the MongoDB wire protocol, existing applications written in Node.js, Python, Go, or Java can connect to it seamlessly using standard MongoDB client drivers.

Operational efficiency is achieved not by multiplying technologies, but by maximizing the utility of proven infrastructure. FerretDB transforms PostgreSQL into a multi-model powerhouse.

Architecture Overview: How FerretDB Bridges the Gap

FerretDB operates as a stateless proxy layer. When an application issues a command using a standard MongoDB driver, FerretDB intercepts the BSON (Binary JSON) payload over the MongoDB wire protocol. It then parses the query, translates the document-based operations into equivalent PostgreSQL JSONB queries, and executes them over a standard PostgreSQL connection.

To achieve this, FerretDB relies heavily on PostgreSQL's advanced jsonb data type. Each MongoDB collection corresponds to a table in PostgreSQL, where the document structure is stored directly within a binary JSON column. This ensures that query performance remains high, as PostgreSQL natively optimizes indexing and searching within JSONB structures.

Step-by-Step Deployment Guide on a VPS

This technical walkthrough assumes you have a clean Virtual Private Server (VPS) running Ubuntu 24.04 LTS, with root or sudo access. We will configure PostgreSQL, install FerretDB, and verify the connection using the official MongoDB shell (mongosh).

Step 1: System Update and Core Prerequisites

First, connect to your VPS via SSH and ensure all system packages are fully updated to secure the environment.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl gnupg2 software-properties-common wget

Step 2: Installing and Configuring PostgreSQL

FerretDB requires PostgreSQL version 14 or higher to properly utilize advanced JSONB processing capabilities. We will install the latest available version from the official PostgreSQL repository.

Add the PostgreSQL repository signing key:

sudo mkdir -p /etc/apt/keyrings
wget --quiet -O - [https://www.postgresql.org/media/keys/ACCC4CF8.asc](https://www.postgresql.org/media/keys/ACCC4CF8.asc) | sudo gpg --dearmor -o /etc/apt/keyrings/postgresql.gpg

Add the repository configuration to your system sources:

echo "deb [signed-by=/etc/apt/keyrings/postgresql.gpg] [http://apt.postgresql.org/pub/repos/apt](http://apt.postgresql.org/pub/repos/apt) $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list

Update the package list and install PostgreSQL:

sudo apt update
sudo apt install -y postgresql postgresql-contrib

Once installed, verify that the PostgreSQL service is active and configured to start automatically on system boot:

sudo systemctl status postgresql
sudo systemctl enable postgresql

Step 3: Creating the Database and User for FerretDB

FerretDB needs a dedicated PostgreSQL database and a user account with sufficient privileges to manage tables and execute queries dynamically.

Access the PostgreSQL prompt as the administrative user:

sudo -i -u postgres psql

Execute the following SQL commands to set up the environment. Replace SecurePassword123 with a robust, enterprise-grade credential:

CREATE USER ferretdb WITH PASSWORD 'SecurePassword123';
CREATE DATABASE ferretdb_backend OWNER ferretdb;
GRANT ALL PRIVILEGES ON DATABASE ferretdb_backend TO ferretdb;
\q

Step 4: Installing and Configuring FerretDB

We will download and install the official Debian package provided by the FerretDB team. Navigate to the GitHub releases page or fetch the package directly via wget.

wget [https://github.com/FerretDB/FerretDB/releases/download/v1.21.0/ferretdb_1.21.0_amd64.deb](https://github.com/FerretDB/FerretDB/releases/download/v1.21.0/ferretdb_1.21.0_amd64.deb)
sudo apt install ./ferretdb_1.21.0_amd64.deb

With FerretDB installed, we must configure its operational parameters. The configuration file is located at /etc/ferretdb/ferretdb.conf. Open it using a text editor such as nano:

sudo nano /etc/ferretdb/ferretdb.conf

Modify or add the following directives to point FerretDB toward your local PostgreSQL backend and bind it to the correct interface:

# The address FerretDB listens on for MongoDB client connections
FERRETDB_LISTEN_ADDR="127.0.0.1:27017"

# The connection URI for the underlying PostgreSQL database
FERRETDB_POSTGRESQL_URL="postgres://ferretdb:SecurePassword123@127.0.0.1:5432/ferretdb_backend"

Save the file and exit the editor. Restart the FerretDB service to apply your changes:

sudo systemctl restart ferretdb
sudo systemctl enable ferretdb

Verifying the Connection and Executing MongoDB Queries

To validate that our proxy layer is functional, we will install the official MongoDB Shell (mongosh) on the VPS and attempt to perform standard CRUD operations.

Installing mongosh

wget -qO- [https://www.mongodb.org/static/pgp/server-7.0.asc](https://www.mongodb.org/static/pgp/server-7.0.asc) | sudo gpg --dearmor -o /etc/apt/keyrings/mongodb.gpg
echo "deb [signed-by=/etc/apt/keyrings/mongodb.gpg] [https://repo.mongodb.org/apt/ubuntu](https://repo.mongodb.org/apt/ubuntu) $(lsb_release -cs)/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
sudo apt update
sudo apt install -y mongodb-mongosh

Testing CRUD Operations

Connect to FerretDB using the standard MongoDB connection string format:

mongosh "mongodb://127.0.0.1:27017/test"

Once connected, you will notice that the shell interacts with the system exactly as if it were a native MongoDB instance. Run the following commands to create a collection, insert a document, and query it:

// Insert a document
db.products.insertOne({ name: "Enterprise VPS Hosting", vcpu: 4, ram: "16GB", active: true });

// Query the document
db.products.find({ active: true });

// Update the document
db.products.updateOne({ name: "Enterprise VPS Hosting" }, { $set: { storage: "100GB NVMe" } });

To prove that this data is living inside PostgreSQL, you can open a separate terminal session, log into psql, and query the ferretdb_backend database. You will discover a table mapping to your products collection containing standard JSONB data.

Production Considerations and Best Practices

While deploying FerretDB on a single VPS is straightforward, scaling it for high-concurrency enterprise workloads requires strict adherence to system optimization principles:

Connection Pooling: Because FerretDB opens connections to PostgreSQL for incoming MongoDB queries, implementing a pooler like PgBouncer between FerretDB and PostgreSQL is highly recommended to mitigate connection overhead.
Index Mapping: While standard MongoDB indexing commands (e.g., db.collection.createIndex()) are translated by FerretDB into PostgreSQL index creation commands, always monitor query performance using PostgreSQL’s EXPLAIN ANALYZE tool if complex aggregation pipelines are slow.
Security and Firewalls: Never expose the FerretDB port (27017) directly to the public internet without proper authentication, TLS encryption, and rigorous firewall boundaries (via ufw or cloud security groups).

Conclusion

FerretDB represents a major paradigm shift in database flexibility. By decoupling the application-facing API from the underlying storage layer, it grants engineering teams the freedom to use the highly productive MongoDB syntax without sacrificing the structural integrity, maturity, and open-source licensing of PostgreSQL. Deploying this architecture on a reliable VPS empowers businesses to build modern, scale-ready applications with lower infrastructure footprint and absolute architectural control.

Unlocking MongoDB Compatibility on PostgreSQL: A Comprehensive Guide to Deploying FerretDB on a VPS