LayerbaseLayerbase

Run FerretDB on Windows (No Docker, No WSL)

FerretDBWindowsDatabasesMongoDB

FerretDB gives you the MongoDB API backed by PostgreSQL. You write MongoDB queries using standard drivers and tools like mongosh, and FerretDB translates them into PostgreSQL operations. Your data lives in PostgreSQL tables with full ACID guarantees, but your application code looks like any other MongoDB project.

Running FerretDB on Windows is complicated. FerretDB v2 (the current version) depends on postgresql-documentdb, a PostgreSQL extension that handles document storage. That extension doesn't build on Windows. The FerretDB binary itself is available for Windows, but without the backend extension, it won't start.

We built custom binaries that let you run FerretDB v1 natively on Windows through Layerbase Desktop or SpinDB. FerretDB v1 uses plain PostgreSQL for storage (no extension required), so it works on Windows without any Linux dependency.

Contents

The Windows Problem: v1 vs v2

FerretDB has two major versions with fundamentally different architectures:

FerretDB v1 stores documents in plain PostgreSQL using JSONB columns. The FerretDB process sits between your application and PostgreSQL, translating MongoDB wire protocol commands into SQL queries. It only needs a standard PostgreSQL server. Nothing platform-specific.

FerretDB v2 moved document storage into postgresql-documentdb, a custom PostgreSQL extension written in C. This extension handles indexing, query planning, and document operations at the database level instead of in the FerretDB proxy. It's faster and more capable, but the extension only compiles on Linux. It depends on POSIX APIs and Linux-specific build tooling that don't have Windows equivalents.

The FerretDB team distributes Windows binaries for the FerretDB proxy itself, but without the postgresql-documentdb extension loaded into PostgreSQL, v2 won't start. You get a startup error because the required backend isn't available.

On Windows, your options are:

  1. Docker/WSL: Run everything in a Linux environment. This works but defeats the purpose of running natively.
  2. FerretDB v1 via Layerbase: Run the v1 proxy with a standard PostgreSQL backend. No extension needed, no Linux dependency.

What You Get with FerretDB v1

FerretDB v1 supports the MongoDB operations that cover most application development needs:

  • CRUD: insertOne, insertMany, find, findOne, updateOne, updateMany, deleteOne, deleteMany
  • Query operators: $eq, $gt, $lt, $in, $regex, $exists, $and, $or, and more
  • Array operations: $elemMatch, $push, $pull, $addToSet
  • Aggregation pipeline: $match, $group, $sort, $project, $limit, $skip
  • Indexes: createIndex, dropIndex, single-field and compound indexes
  • Database commands: listDatabases, listCollections, drop, ping

The MongoDB wire protocol compatibility means mongosh, Compass, and every MongoDB driver library (Node.js, Python, Go, Java) connects to FerretDB v1 without changes.

Where v1 has limitations compared to v2: more complex aggregation stages, change streams, and some edge cases in query behavior. For local development and most application workloads, v1 covers what you need.

Running FerretDB on Windows with Layerbase

Both Layerbase Desktop and SpinDB handle the complexity of running FerretDB by starting a PostgreSQL instance as the backend, configuring it, and starting FerretDB pointing at that PostgreSQL server. You don't need to set up PostgreSQL separately.

Option 1: Layerbase Desktop (GUI)

Layerbase Desktop makes this a point-and-click operation.

  1. Download Layerbase Desktop from layerbase.com/download
  2. Open the app and click Create Database
  3. Select FerretDB as the engine
  4. Give it a name and click Create

The app sets up both FerretDB and its PostgreSQL backend automatically. You get a MongoDB connection URL that works with any MongoDB client.

Option 2: SpinDB (CLI)

SpinDB gives you the same setup from the terminal. (What is SpinDB?)

Install SpinDB:

bash
npm i -g spindb

Create and start a FerretDB instance:

bash
spindb create myferret -e ferretdb --start

SpinDB downloads the FerretDB binary and a PostgreSQL binary for Windows, initializes the PostgreSQL data directory, starts PostgreSQL, and starts FerretDB configured to use it as a backend. On Windows, SpinDB automatically uses FerretDB v1.

Get the connection URL:

bash
spindb url myferret
text
mongodb://127.0.0.1:27017/myferret

Manage the instance:

bash
spindb stop myferret   # Stops both FerretDB and its PostgreSQL backend
spindb start myferret  # Starts both back up
spindb list            # See all instances

Hosted FerretDB with Layerbase Cloud

This post focuses on native Windows development with FerretDB v1. If you want a managed MongoDB-compatible endpoint instead, FerretDB is also available on Layerbase Cloud. Cloud FerretDB runs on Linux infrastructure with the PostgreSQL backend handled for you, plus TLS, backups, and connection details in the Quick Connect panel.

Use Layerbase Desktop or SpinDB when you want FerretDB running directly on your Windows machine. Use Layerbase Cloud when you want a hosted FerretDB endpoint your app can reach from anywhere.

Connecting with MongoDB Tools and Drivers

FerretDB speaks the MongoDB wire protocol, so connect with any MongoDB tool or driver.

With mongosh:

bash
mongosh "mongodb://127.0.0.1:27017/myferret"
javascript
db.products.insertOne({
  name: "Mechanical Keyboard",
  price: 149.99,
  tags: ["electronics", "peripherals"],
  inStock: true
})

db.products.find({ price: { $lt: 200 } })

With the Node.js MongoDB driver:

typescript
import { MongoClient } from 'mongodb'

const client = new MongoClient('mongodb://127.0.0.1:27017/myferret')
await client.connect()

const db = client.db('myferret')
const products = db.collection('products')

await products.insertMany([
  { name: 'USB Hub', price: 29.99, tags: ['electronics'] },
  { name: 'Desk Lamp', price: 45.00, tags: ['office'] },
])

const results = await products.find({ tags: 'electronics' }).toArray()
console.log(results)

await client.close()

Everything works the same way it would against a MongoDB server. The difference is that your data is stored in PostgreSQL tables, which you can also query directly with SQL if you need to.

What About FerretDB v2?

We're actively working on bringing FerretDB v2 to Windows. The blocker is postgresql-documentdb, the PostgreSQL extension that v2 requires. This extension is written in C with Linux-specific dependencies, and porting it to Windows is a non-trivial effort.

We haven't given up on this. We're exploring compilation approaches and working to understand exactly which dependencies need to be addressed. If and when we get v2 working on Windows, it will be available through SpinDB and Layerbase Desktop automatically.

In the meantime, FerretDB v1 is a fully functional MongoDB-compatible database for Windows development. On macOS and Linux, SpinDB runs FerretDB v2 by default and takes advantage of the postgresql-documentdb backend.

Wrapping Up

FerretDB gives you the MongoDB API without the MongoDB license. On Linux and macOS, FerretDB v2 runs with full postgresql-documentdb performance. On Windows, the required extension isn't available yet, but FerretDB v1 runs natively through our custom binaries and covers the MongoDB operations you need for development.

Layerbase Desktop sets up FerretDB and its PostgreSQL backend with a few clicks. SpinDB does the same from the command line. Layerbase Cloud gives you a hosted FerretDB endpoint when you do not want to manage the backend yourself.

FerretDB is one of 20+ engines available through SpinDB, Layerbase Desktop, and Layerbase Cloud. See the full list at layerbase.com/spindb.

Something not working?