FerretDB (MongoDB-compatible)

FerretDB is an open-source (Apache-2.0) database that speaks the MongoDB wire protocol and stores documents in PostgreSQL. Use your existing MongoDB drivers and tools.

Overview

Each instance pairs a FerretDB server with a PostgreSQL cluster that has the DocumentDB extension. You only see the MongoDB endpoint; the PostgreSQL side is managed for you and is what gets backed up.

New instances run FerretDB 2.7. FerretDB 2.4 is deprecated: it is outside FerretDB’s support window, and new 2.4 instances can no longer be ordered from 2027-01-05. A 2.4 instance does not upgrade in place; create a 2.7 instance and move the data with zb migrate.

FerretDB (MongoDB-compatible) at a glance, from the engine catalogue

Status	Available
Category	Document
Versions	2.7, 2.4 (newest is the default)
Protocol and port	MongoDB wire protocol on 27017
Runtime	Single-node engine (ghcr.io/ferretdb/ferretdb)
Storage	PostgreSQL with the DocumentDB extension, rendered alongside the instance
Backups	barman-cloud base backups + WAL
Point-in-time recovery	Yes
Pause	Scale to zero
Free plan	Yes (size f0)
Licence	Apache-2.0

Create an instance

Portal

1. Open the portal and choose New instance.
2. Pick FerretDB (MongoDB-compatible) and a version (2.7, 2.4).
3. Choose a size and region. On the Free plan the size is f0. Secure placement is listed only after your organization has signed the BAA.
4. Check the hourly price and monthly estimate, then confirm. The Connect tab fills in when the instance is ready.

CLI

shell

zb instances create --engine ferretdb --engine-version 2.7 \
  --size s1 --region us-east --name ferretdb-demo --wait
# On the Free plan, use --size f0

# Reveal the credentials once and store them in your secret manager
zb instances credentials reveal ferretdb-demo

API

shell

curl -sS https://api.databasezy.com/v1/orgs/$ZB_ORG/projects/$ZB_PROJECT/instances \
  -H "Authorization: Bearer $ZB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "engine": "ferretdb",
  "engine_version": "2.7",
  "size": "s1",
  "region": "us-east",
  "name": "ferretdb-demo"
}'

The response is 201 with the instance in status requested, or 202 when a team approval policy applies. See the REST API reference.

Connect

Connect with any MongoDB driver using tls=true, SCRAM-SHA-256 and authSource=admin. Each FerretDB connection maps to a PostgreSQL connection, so the size’s connection limit is the real ceiling.

FerretDB (MongoDB-compatible) listens on port 27017 (MongoDB wire protocol). Versions: 2.7, 2.4. Replace the example host with the one on your instance's Connect tab; credentials are shown once at creation.

Connection URI

mongodb://app:<password>@ferret-7f3k.us-east.databasezy.com:27017/app?tls=true&tlsCAFile=databasezy-ca.pem&authSource=admin&authMechanism=SCRAM-SHA-256

Node

db.js

import { MongoClient } from "mongodb";

const uri = `mongodb://app:${process.env.ZB_PASSWORD}@ferret-7f3k.us-east.databasezy.com:27017/app`
  + "?tls=true&authSource=admin&authMechanism=SCRAM-SHA-256";
export const client = new MongoClient(uri, {
  tlsCAFile: "databasezy-ca.pem", // omit if the OS trust store already has the CA
  maxPoolSize: 10,
});
await client.connect();
console.log(await client.db("app").command({ ping: 1 }));

Tested with: FerretDB (MongoDB-compatible) 2.7 · mongodb 6.10 (Node driver)

Python

db.py

import os
from pymongo import MongoClient

uri = (
    f"mongodb://app:{os.environ['ZB_PASSWORD']}@ferret-7f3k.us-east.databasezy.com:27017/app"
    "?authSource=admin&authMechanism=SCRAM-SHA-256"
)
client = MongoClient(uri, tls=True, tlsCAFile="databasezy-ca.pem", maxPoolSize=10)
print(client.app.command("ping"))

Tested with: FerretDB (MongoDB-compatible) 2.7 · pymongo 4.10

Go

main.go

package main

import (
  "context"
  "fmt"
  "os"

  "go.mongodb.org/mongo-driver/v2/bson"
  "go.mongodb.org/mongo-driver/v2/mongo"
  "go.mongodb.org/mongo-driver/v2/mongo/options"
)

func main() {
  uri := fmt.Sprintf("mongodb://app:%s@ferret-7f3k.us-east.databasezy.com:27017/app"+
    "?tls=true&tlsCAFile=databasezy-ca.pem&authSource=admin&authMechanism=SCRAM-SHA-256&maxPoolSize=10",
    os.Getenv("ZB_PASSWORD"))
  client, err := mongo.Connect(options.Client().ApplyURI(uri))
  if err != nil {
    panic(err)
  }
  defer client.Disconnect(context.Background())

  var res bson.M
  if err := client.Database("app").RunCommand(context.Background(), bson.D{{Key: "ping", Value: 1}}).Decode(&res); err != nil {
    panic(err)
  }
  fmt.Println(res)
}

Tested with: FerretDB (MongoDB-compatible) 2.7 · mongo-go-driver v2.0

Rust

main.rs

use mongodb::{bson::doc, options::ClientOptions, Client};

#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    let pw = std::env::var("ZB_PASSWORD").expect("ZB_PASSWORD");
    let uri = format!(
        "mongodb://app:{pw}@ferret-7f3k.us-east.databasezy.com:27017/app?tls=true&tlsCAFile=databasezy-ca.pem&authSource=admin&authMechanism=SCRAM-SHA-256&maxPoolSize=10"
    );
    let opts = ClientOptions::parse(uri).await?;
    let client = Client::with_options(opts)?;
    let res = client.database("app").run_command(doc! { "ping": 1 }).await?;
    println!("{res}");
    Ok(())
}

Tested with: FerretDB (MongoDB-compatible) 2.7 · mongodb 3.1 (rustls)

Java

Db.java

// One-time: keytool -importcert -noprompt -alias databasezy -file databasezy-ca.pem \
//   -keystore databasezy-truststore.p12 -storetype PKCS12 -storepass changeit
// Run with: -Djavax.net.ssl.trustStore=databasezy-truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit
import com.mongodb.client.MongoClients;
import org.bson.Document;

public final class Db {
  public static void main(String[] args) {
    var uri = "mongodb://app:" + System.getenv("ZB_PASSWORD")
        + "@ferret-7f3k.us-east.databasezy.com:27017/app?tls=true&authSource=admin&authMechanism=SCRAM-SHA-256&maxPoolSize=10";
    try (var client = MongoClients.create(uri)) {
      System.out.println(client.getDatabase("app").runCommand(new Document("ping", 1)));
    }
  }
}

Tested with: FerretDB (MongoDB-compatible) 2.7 · mongodb-driver-sync 5.2

.NET

Program.cs

using MongoDB.Bson;
using MongoDB.Driver;

var pw = Environment.GetEnvironmentVariable("ZB_PASSWORD");
var settings = MongoClientSettings.FromConnectionString(
    $"mongodb://app:{pw}@ferret-7f3k.us-east.databasezy.com:27017/app?tls=true&authSource=admin&authMechanism=SCRAM-SHA-256");
settings.MaxConnectionPoolSize = 10;
// The CA is verified against the OS trust store; add databasezy-ca.pem to it if needed.
var client = new MongoClient(settings);
Console.WriteLine(client.GetDatabase("app").RunCommand<BsonDocument>(new BsonDocument("ping", 1)));

Tested with: FerretDB (MongoDB-compatible) 2.7 · MongoDB.Driver 3.1

PHP

db.php

<?php
require "vendor/autoload.php";

$uri = sprintf("mongodb://app:%[email protected]:27017/app?authSource=admin&authMechanism=SCRAM-SHA-256",
    getenv("ZB_PASSWORD"));
$client = new MongoDB\Client($uri, ["tls" => true, "tlsCAFile" => "databasezy-ca.pem", "maxPoolSize" => 10]);
var_dump($client->selectDatabase("app")->command(["ping" => 1])->toArray()[0]);

Tested with: FerretDB (MongoDB-compatible) 2.7 · mongodb/mongodb 1.20 · ext-mongodb 1.20

Ruby

db.rb

require "mongo"

client = Mongo::Client.new(
  "mongodb://app:#{ENV.fetch('ZB_PASSWORD')}@ferret-7f3k.us-east.databasezy.com:27017/app?authSource=admin&authMechanism=SCRAM-SHA-256",
  ssl: true,
  ssl_ca_cert: "databasezy-ca.pem",
  max_pool_size: 10
)
puts client.database.command(ping: 1).first

Tested with: FerretDB (MongoDB-compatible) 2.7 · mongo 2.21

mongosh

shell

mongosh "mongodb://app:$ZB_PASSWORD@ferret-7f3k.us-east.databasezy.com:27017/app?tls=true&authSource=admin&authMechanism=SCRAM-SHA-256" --tlsCAFile databasezy-ca.pem

# or
zb connect ferretdb-7f3k

Tested with: FerretDB (MongoDB-compatible) 2.7 · mongosh 2.3

The FerretDB connection guide lists compatibility notes and pooling advice.

See Connecting to Databasezy for host names, the CA bundle and the allow-list, which work the same for every engine.

Migrate in

You can bring an existing FerretDB (MongoDB-compatible) database in from these sources. Each links to a step-by-step guide.

Where you can migrate a FerretDB (MongoDB-compatible) database from, how, and whether continuous sync is available

Source	How	Continuous sync	Guide status
MongoDB Atlas	Connection string	No	Available
Self-hosted server	Connection string, Local tools (zb migrate --from local)	No	Available
Local files and dumps	File upload, Local tools (zb migrate --from local)	No	Available
Another Databasezy instance	Instance to instance	No	Coming soon · phase 2

MongoDB sources are copied with mongodump and mongorestore. Preflight and the restore report features FerretDB does not support. There is no continuous sync for document engines.

How migrations work explains preflight, verification and cutover.

Backups and restore

Because the data lives in PostgreSQL, backups are taken from the backing PostgreSQL store and you get point-in-time recovery.

FerretDB (MongoDB-compatible) backups use barman-cloud base backups + WAL. They run inside the instance's namespace, stream straight to the cell's object storage and are checksummed on upload. How often they run and how long they are kept follows your plan's backup policy. A backup is always taken before a resize or a version upgrade.

Point-in-time recovery is supported: you can restore to any moment inside the PITR window of your plan or the PITR add-on. Restores create a new instance by default and leave the original untouched; an in-place restore asks you to type the instance name and takes a pre-change backup first.

shell

zb backups create ferretdb-demo --label before-release      # manual snapshot
zb backups list ferretdb-demo
zb backups restore ferretdb-demo <backup-id> --name ferretdb-demo-restore

# Point in time (RFC 3339) inside the PITR window
zb backups pitr-window ferretdb-demo
zb backups restore ferretdb-demo <backup-id> --at "2026-09-27T08:15:00Z" --name ferretdb-demo-pitr

Pause and scale to zero

FerretDB (MongoDB-compatible) can scale to zero. A paused instance has no running pods and bills no compute; its storage and backups are kept and billed as usual. Connections are refused until you resume it. On the Free plan an instance pauses by itself after 15 minutes without connections and wakes on the next one; the gateway holds that connection for up to 30 seconds while it starts.

shell

zb instances pause ferretdb-demo
zb instances resume ferretdb-demo

See Pause and resume for schedules, wake times and billing while paused.

Limits and sizes

One logical database per FerretDB instance.

FerretDB (MongoDB-compatible) runs on every size, including the Free plan's f0. The size sets the CPU, memory, storage ceiling and connection limit; the gateway refuses connections over the limit with a protocol error. Storage grows in steps up to the ceiling, and you can resize at any time.

Sizes available for FerretDB (MongoDB-compatible): vCPU, memory, storage ceiling, connection limit and monthly price

Size	vCPU	Memory	Max storage	Max connections	≈ $ / month
f0	0.063	512 MiB	1 GB	20	Free
s0	0.25	1 GiB	20 GB	60	$10
s1	0.5	2 GiB	50 GB	100	$15
s2	1	4 GiB	200 GB	200	$60
m2	2	8 GiB	500 GB	400	$110
m4	4	16 GiB	1 TB	800	$210
l8	8	32 GiB	4 TB	1,500	$410
l16	16	64 GiB	8 TB	3,000	$960
xl32	32	128 GiB	16 TB	5,000	$1,870

Full details, including hourly prices and burst CPU, are in the size catalogue; plan quotas are in limits and quotas.

Security

• TLS on every connection. TLS 1.2 is the minimum and TLS 1.3 is preferred; plaintext is never offered. Verify the server, not just the encryption: use tls=true with the CA bundle. See TLS and the CA bundle.
• IP allow-list. The gateway checks the client address before authentication, on every plan. Manage it under Network → Allow-list in the portal or with PUT /v1/orgs/{org}/instances/{id}/network.
• Credentials. Generated inside the cell, shown once, never stored by the control plane. Rotate them with an overlap window so nothing breaks.
• Secure hosting. Secure placement (HIPAA-ready) is a per-instance option once your organization has signed the BAA: dedicated nodes, customer-managed keys and immutable backups. See Secure hosting and the BAA.
• Staff access. Databasezy staff cannot read your data without a grant you issue. See data confidentiality.

FAQ

Which MongoDB features are missing?

Change streams, $text search, GridFS and multi-document transactions are the usual gaps. Run your test suite against an instance before you migrate production, and check the restore report.

FerretDB or MongoDB (Percona Server)?

FerretDB is available now, runs on the Free plan and has an Apache-2.0 licence. Choose the MongoDB engine when it ships if you depend on features FerretDB lacks.

Which version does my instance run?

Run db.runCommand({ buildInfo: 1 }). The ferretdb.version field is the FerretDB release (for example v2.7.0); the top-level version is the MongoDB version FerretDB is compatible with.