Skip to content
LayerbaseLayerbase

Run FerretDB on Windows (No Docker, No WSL)

7 min readFerretDBWindowsDatabasesMongoDB

Short version: FerretDB v2 cannot run natively on Windows, because it depends on the postgresql-documentdb PostgreSQL extension, which is written in C against POSIX APIs and does not build there. The FerretDB proxy binary exists for Windows; the backend it needs does not. So we built custom binaries for FerretDB v1, which stores documents in plain PostgreSQL with no extension, and run it natively through Layerbase Desktop or the Layerbase CLI. No Docker, no WSL.

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 the Layerbase CLI (formerly 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 the Layerbase CLI 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/desktop/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: The Layerbase CLI

The Layerbase CLI gives you the same setup from the terminal. (What is the Layerbase CLI?)

Install the Layerbase CLI:

bash
npm i -g layerbase

Create and start a FerretDB instance:

bash
lbase create myferret -e ferretdb --start

The Layerbase CLI 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, the Layerbase CLI automatically uses FerretDB v1.

Get the connection URL:

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

Manage the instance:

bash
lbase stop myferret   # Stops both FerretDB and its PostgreSQL backend
lbase start myferret  # Starts both back up
lbase 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 the Layerbase CLI 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 the Layerbase CLI and Layerbase Desktop automatically.

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

FAQ

Why can't FerretDB v2 run on Windows?

Because v2 moved document storage into postgresql-documentdb, a PostgreSQL extension written in C that depends on POSIX APIs and Linux build tooling. The FerretDB team does ship a Windows binary for the proxy, but without that extension loaded into PostgreSQL, v2 fails at startup because its backend is not there.

What do I give up by running v1 instead?

Performance and some newer capability. v2 pushes indexing, query planning, and document operations down into the database through the extension, where v1 translates MongoDB wire protocol commands into SQL in the proxy. For Windows development work the practical difference is speed rather than whether your code runs.

Does my application code change?

No. You connect with mongosh and standard MongoDB drivers against a mongodb:// connection string either way. The visible difference is on the storage side: your documents are rows in PostgreSQL, which you can also query with SQL if it is ever useful.

Should I use this for production on Windows?

Use it for development. If you want FerretDB backing a running application, the sensible path is a hosted FerretDB endpoint, where v2 runs on Linux with the extension and you do not maintain the PostgreSQL backend yourself. Your Windows machine connects to it with the same driver.

Will v2 come to Windows?

We are working on it, and the honest status is that porting the extension is a real piece of work rather than a configuration problem. If it lands, it arrives through the Layerbase CLI and Layerbase Desktop without you doing anything. Until then, macOS and Linux run v2 by default and Windows runs v1.

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. The Layerbase CLI 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 21 engines available through the Layerbase CLI and Layerbase Desktop. See the full list at layerbase.com/docs/cli.

Keep reading