FerretDB

Runs FerretDB 2 · macOS and Linux · registry page ↗

Run a document database your MongoDB drivers, mongosh and Compass connect to unchanged, without running MongoDB.

MongoDB moved its server to the SSPL in 2018, a licence the OSI never approved. This module speaks the MongoDB wire protocol instead: a FerretDB v2 gateway (Apache-2.0) in front of a private PostgreSQL that carries Microsoft’s DocumentDB extension. You declare one block; doze runs the Postgres and the gateway and shows you only the Mongo side. The block type is ferret, after the gateway.

A database

module ferret "docs" {
  version = "2.7"
}

version is the FerretDB gateway’s; the Postgres underneath comes with it.

doze url docs
# mongodb://docs.shop.doze:27017/
mongosh "$(doze url docs)" --eval 'db.runCommand({ ping: 1 })'

Hand it to an app by reference:

app "api" {
  run  = "bun run dev"
  port = 3000
  env  = { MONGODB_URI = module.docs.url }
}

The first start does more work than later ones: doze creates the private Postgres and its extension once. After that it wakes like any other service. To get the first start out of the way, run doze wake docs.

Databases, collections and seed data

module ferret "shop" {
  version = "2.7"

  database "catalog" {
    collection "products" { seed = "./seed/products.json" }
    collection "orders" {}
  }
}

seed is a JSON array loaded into the collection when it is empty.

Use it like Mongo

mongosh "$(doze url docs)" --eval '
  db.users.insertOne({ name: "Ada", roles: ["admin"] });
  printjson(db.users.find().toArray());
'

What to expect

FerretDB aims at broad MongoDB compatibility, not all of it. If one command matters to you, check the FerretDB docs.

Reference

A MongoDB-wire database you connect to with any Mongo client. Under the hood it is FerretDB v2 fronting a private PostgreSQL with Microsoft’s DocumentDB extension — no MongoDB server, no license worries.

Every field at once

module ferret "shop" {
  version = "2.7"

  database "catalog" {

    collection "products" {

    seed = "./seed/products.json"

  }
    collection "orders" {}
  }
}

Versions you can declare

The version = you write is the engine’s own version. Declare a series and doze pins its newest published build, or declare an exact build. Either way it is fetched, verified and pinned in doze.lock, so it never moves on its own.

version =	pins (today)	exact builds
2	2.7.0	1

Every exact build, per series

2: 2.7.0

Fields

Field	Type	Default	Description
version	string	—	FerretDB v2.x gateway version Required.
seed	string	—	path to a JSON array seeded into an empty collection
settings	map(string)	—	extra FERRETDB_* gateway settings
auth	bool	false	enable auth + user convergence (scaffold; needs validation)

Every module block also takes doze’s own fields: port, listen, sleep, after, enabled, routes, count and for_each (doze.hcl reference).

Nested blocks

database "<name>" { … } — a Mongo database to ensure (repeatable; label = name)

The module does not list this block’s fields yet.

collection "<name>" { … } — a collection within a database (repeatable; label = name)

The module does not list this block’s fields yet.

index { … } — an index on a collection (keys = {field=1|-1}, unique)

The module does not list this block’s fields yet.

user { … } — a Mongo user when auth is on (name, password, database, roles)

The module does not list this block’s fields yet.

Module releases

The releases of the module that provide this engine. doze picks the newest one that fits your doze and your version =, and pins it in doze.lock; you never write these. Older releases stay available for pinned lockfiles.

Release	Engine versions	Platforms
0.2.3	2	3	stable
0.2.2	2	3
0.2.1	2	3

Signed data: index.yaml ↗ · meta.yaml ↗