Document Database

MongoDB-compatible clusters: FerretDB on managed Postgres, one node or three with failover.

What it is

MongoDB-compatible, powered by FerretDB on PostgreSQL. Applications connect with mongosh, the MongoDB drivers and the tools built on them, over TLS on port 27017. Find it under Document Database in the console. (Until 2026-11 it was called DocumentDB; it is not AWS DocumentDB.)

Coming from AWS DocumentDB or MongoDB Atlas: read the compatibility list first. Multi-document transactions and change streams are not supported, and every user has full access.

Underneath, a cluster is a managed Postgres of our own with two open-source layers on top:

Layer Version What it does
Wire guard Deutsche Cloud Holds 27017 (TLS), refuses transactions, passes every other message to FerretDB unchanged.
FerretDB 2.7 Speaks the MongoDB wire protocol (on loopback, behind the guard) and calls into Postgres.
DocumentDB 0.107 (FerretDB's build) A Postgres extension that stores documents as BSON and runs the query and aggregation engine.
Postgres 17 The storage engine: the same managed Postgres as our database service, with Patroni and backups.
MongoDB compatible reports server version 7.0 to drivers What buildInfo tells a driver; see Compatibility for what that means.

So a cluster has every property of a managed Postgres — encrypted volumes, backups, TLS, OS patching, failover with three nodes — and you never see the Postgres: there is no SQL access. Only 27017 is open, and the storage is managed by DocumentDB.

Concepts

Term Meaning
Cluster One database endpoint, of 1 or 3 nodes, identified by the name you give it. Its id starts with ewdoc-.
Node One machine running Postgres and FerretDB on a data volume of its own. Three nodes are spread over the region's zones.
Primary The node Patroni has made the Postgres leader. Writes go there; the balancer in front of three nodes sends every client to it.
Master user The user the cluster is created with (docdb_admin unless you name another). Its password is generated and filed in Secrets as DOCDB_<NAME>_PASSWORD.
Endpoint The host clients connect to, on port 27017. With publicly accessible on, it answers on the internet too (TLS and a password are still required); otherwise only inside the cluster's network.
Activity The event stream on the cluster page: every provisioning step, every failover, what the nodes reported.

Create a cluster

Console

Document Database → Create cluster. Choose a name, a node type (prices are per node per month), 1 or 3 nodes, the volume size, whether it is publicly accessible, deletion protection, how many days backups are kept and the master user name. A 3-node cluster needs at least 8 GiB of memory per node; the form greys out the smaller types.

CLI

dcloud docdb clusters server-types
dcloud docdb clusters create --identifier catalog --node-type performance-4 --nodes 3 --volume-size-gib 40
dcloud docdb clusters get ewdoc-0123456789ab
dcloud docdb clusters nodes ewdoc-0123456789ab

Other flags: --master-username, --publicly-accessible, --vpc-id, --kms-key-id, --backup-retention-days, --deletion-protection, --tags key=value, --region-id.

API

POST /docdb/api/clusters
{
  "identifier": "catalog",
  "nodeType": "performance-4",
  "nodes": 3,
  "volumeSizeGib": 40,
  "publiclyAccessible": false,
  "backupRetentionDays": 7
}

Needs docdb:CreateDocdbCluster. The cluster is creating until FerretDB answers on 27017 — usually four to eight minutes; the Activity tab shows each step. GET /docdb/api/clusters/{id} returns the endpoint, the versions and connectionStringTemplate.

Terraform

resource "dcloud_docdb_cluster" "catalog" {
  identifier            = "catalog"
  node_type             = "performance-4"
  nodes                 = 3
  volume_size_gib       = 40
  backup_retention_days = 7
}

output "docdb_url" {
  value = dcloud_docdb_cluster.catalog.connection_string_template
}

Computed attributes: status, host, port, address, private_address, master_password_secret_name and connection_string_template. The password never passes through Terraform: read it from Secrets.

Connect

Every connection is TLS. The certificate is signed by the platform CA: deployed apps already trust it; anywhere else, download it from Connection → Download the CA bundle or GET /docdb/api/ca-bundle (dcloud-docdb-ca-bundle.pem).

The connection string, with the password from Secrets in place of <password>:

mongodb://docdb_admin:<password>@<host>:27017/?tls=true&authMechanism=SCRAM-SHA-256&authSource=admin&directConnection=true

directConnection=true matters: the cluster is not a MongoDB replica set and does not advertise one, so a driver must not look for members. With three nodes the balancer sends this one host to the primary. Percent-encode the password if it contains reserved characters.

mongosh

mongosh "mongodb://docdb_admin:<password>@<host>:27017/?tls=true&authMechanism=SCRAM-SHA-256&authSource=admin&directConnection=true" \
  --tlsCAFile dcloud-docdb-ca-bundle.pem

Node.js driver

import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URL, {
  tlsCAFile: 'dcloud-docdb-ca-bundle.pem',
});
await client.connect();
const orders = client.db('shop').collection('orders');
await orders.insertOne({ sku: 'A-1', qty: 2 });

Reader endpoint (3-node clusters)

A 3-node cluster also answers on port 27018 of the same host: the reader endpoint, for the reads you would send with readPreference=secondaryPreferred on MongoDB. The balancer sends its connections to the two replicas only, each reading from its own copy of the data; the primary is left to the writes.

mongodb://docdb_admin:<password>@<host>:27018/?tls=true&authMechanism=SCRAM-SHA-256&authSource=admin&directConnection=true

What to expect:

  • Reads may lag. Replication is asynchronous: a document you just wrote through 27017 may not be visible on 27018 for a moment (usually milliseconds). Read your own writes through 27017. A replica more than 256 MB of changes behind the primary is taken out of the reader endpoint until it catches up.
  • Writes are refused, at once, with code 1: Can't execute write operation, the database is in recovery and waiting for the standby node to be promoted. The same for index builds and anything else that changes data.
  • Find, aggregate, count, cursors (getMore) and explain work. A cursor stays on the replica that opened it.
  • If both replicas are unavailable, port 27018 refuses connections. Fall back to the 27017 connection string. (With both replicas down the cluster has also lost its majority and stops taking writes; see High availability.)
  • After a failover the promoted node leaves the reader endpoint and the old primary joins it once it is back as a replica. Reads through 27018 kept working through a primary failure on dev (599 reads, none failed). A connection that was open to the replica being promoted is closed within about two seconds of its promotion (see Role changes); a write sent on it in that moment can succeed, so do not rely on the reader endpoint as a guard against writes.

The reader connection string is on Connection, in the API as readerPort and readerConnectionStringTemplate (null on a 1-node cluster), and in Terraform as reader_port and reader_connection_string_template. Clusters made before the reader endpoint existed get it from the platform's balancer sweep, with an Activity entry; nothing changes on the machines.

From a deployed app

An app binding to a Document Database cluster sets MONGODB_URL in the app's environment: the full connection string, password included, and on a 3-node cluster MONGODB_READER_URL, the reader endpoint's (absent on a 1-node cluster: fall back to MONGODB_URL). Deployed apps trust the platform CA, so no tlsCAFile is needed there. Bind as the master user or as one of the cluster's users (userName); bind each app as a user of its own so its credential can be rotated or revoked without touching the others.

Users

Document Database users are additional logins for the cluster. Every user has full read/write access to all databases; per-database and read-only roles are not yet available. Use separate users so each application's credential can be rotated or revoked on its own.

Users on the cluster page, the CLI or the API:

Do API IAM
List GET /docdb/api/clusters/{id}/users docdb:DescribeDocdbClusters
Add POST …/users { "name": "orders_service" } docdb:CreateDocdbUser
Rotate a password POST …/users/{userId}/rotate-password docdb:RotateDocdbUserPassword
Remove DELETE …/users/{userId} docdb:DeleteDocdbUser

A user's password is generated and filed in Secrets as DOCDB_<CLUSTER>_USER_<NAME>_PASSWORD; read it with secrets:GetSecretValue. Rotating files a new version and the old password stops working; apps bound as that user are redeployed with the new one. Removing a user refuses new sign-ins with its password at once (connections already signed in keep working until they close); it is refused while an app is bound as that user. A role or a database in the request is refused rather than ignored.

The MongoDB commands createUser, updateUser and dropUser are refused by the cluster ("permission denied to create role"): FerretDB runs every command as its own service login, which cannot manage roles. Manage users through the platform instead.

High availability

A 1-node cluster is one machine: if it fails, the database is down until the machine is back.

A 3-node cluster runs Postgres under Patroni across the region's zones, FerretDB on every node, and a balancer in front. Patroni keeps one node primary and streams to the two replicas. When the primary fails, Patroni promotes a replica; the balancer's health check follows Patroni's /primary endpoint, so port 27017 moves to the new primary at the same address. Connections to the old primary break and the driver reconnects; a write that had not been acknowledged must be retried by the application.

Role changes close connections

A client connects to FerretDB, not to Postgres, so its connection survives the Postgres underneath being promoted or demoted. On a planned switchover (maintenance, a machine-type change) that used to leave a connection on the old primary refusing every write with Can't execute write operation, the database is in recovery… for as long as it lived: FerretDB answers with a generic error, not MongoDB's NotWritablePrimary, so drivers do not reconnect by themselves. Every node therefore restarts its FerretDB the moment Patroni changes its role (it listens again within about 50 ms): all connections to that node close, the driver reconnects through the balancer, and lands on the new primary (27017) or a replica (27018). Measured on dev: a connection on the old primary was writing to the new primary 8 s after a switchover began, without the application doing anything.

Clusters created before 2026-11-16 do not have this until their nodes are replaced. On those, treat the "in recovery" error on a write as a reason to close the connection and reconnect.

Measured: a lost primary costs about 29 s of failed writes (28.8–30.3 s in four runs) and no acknowledged write (see Failure behaviour). Patroni gives up on a silent primary after 20 s (its leader lease), the shortest it allows; the rest is electing the replica and the balancer following it. Over three hours under write load the cluster never failed over on its own.

Overview → Nodes shows every machine: its role as last observed, its state, zone, addresses, Postgres version, disk use and when it last reported.

Failure behaviour (measured)

Measured on dev on 2026-11-14/15 (3 × performance-4 and 1 × performance-2, Postgres 17.11, FerretDB 2.7.0): a client inserted one document every 250 ms through the endpoint with a 2–3 s timeout and no driver retries, and afterwards checked that every acknowledged insert was there. The failure was injected with the cloud provider's API (a hard reset is a power cut) or Patroni's own restart.

Failure Writes failed for Acknowledged writes lost What happened
Primary powered off (stays down), since 2026-11-16 28.8–30.3 s (4 runs) 0 of 1,456 A replica was promoted 25.5–27.1 s after the power-off; the balancer followed. Reads through the reader endpoint (27018) never stopped.
Primary powered off (stays down), before 33.3 s 0 of 669 A replica was promoted 29.5 s after the power-off; the balancer followed. The old primary rejoined as a replica 39 s after it was powered on.
Primary hard reset (comes straight back), before 38.5 s 0 of 808 The machine rebooted within the leader lock's 30 s and became primary again. (With the 20 s lock a reboot now usually means a failover.)
Primary's Postgres restarted (FerretDB stays up) 1.8 s 0 of 354 FerretDB reconnected to its Postgres by itself; 6 inserts failed.
FerretDB killed (kill -9) 1.6 s (container test) 0 of 56 systemd restarts it after 1 s; it listens 54 ms after starting. Not injected on dev: there is no shell on the nodes.
A replica hard reset 0 s 0 of 480 Longest gap between acknowledgements 356 ms.
1-node cluster hard reset 43.2 s 0 of 549 Postgres and FerretDB came back with the machine.

Writes are acknowledged by the primary alone (asynchronous replication), so a primary that dies the instant after acknowledging can lose that write; none was lost in these runs.

Compatibility

Document Database clusters are compatible with MongoDB drivers and tools, not MongoDB itself. What follows was tested against a cluster.

What works

  • CRUD: insertOne/insertMany, find with filters, projections, sort, skip and limit, updateOne/updateMany with the update operators, replaceOne, deleteOne/deleteMany, countDocuments, distinct.
  • findOneAndUpdate, findOneAndReplace, findOneAndDelete.
  • bulkWrite, ordered and unordered.
  • Indexes: single-field, compound, unique, partial, TTL, text and 2dsphere.
  • Aggregation, including $lookup, $facet, $graphLookup, $setWindowFields, $merge and $out.
  • explain.
  • Vector search, through a cosmosSearch index (DocumentDB's vector index type).

What does not

  • Multi-document transactions are refused. On a cluster created since 2026-11-17 the first command of a transaction (anything carrying startTransaction or autocommit) is answered with error 115 CommandNotSupported by the wire guard and nothing is written; withTransaction fails at once, and retryable writes (txnNumber alone) work. A cluster created before that has no guard: FerretDB acknowledges the transaction and keeps the writes made inside it even after an abort. Its Connection page says which of the two it is. Design for single-document atomicity.
  • Change streams (watch).
  • $where and mapReduce: not supported; mapReduce dropped the connection in our tests. Use the aggregation pipeline.
  • Collation is accepted but not honoured: a case-insensitive match with collation: { locale: 'en', strength: 2 } returned 0 documents.
  • $jsonSchema validators are accepted on createCollection but not enforced: invalid documents are inserted.
  • createRole and killOp are not implemented.
  • createUser, updateUser, dropUser are refused; users are managed by the platform, and every user has full access (see Users).
  • Sharding: none.
  • Replica-set topology: the cluster does not present itself as a replica set; connect with directConnection=true. Read preferences that target secondaries have nowhere to go.

Health, metrics and logs

Monitoring shows what the health check found and charts per node. Every two minutes the control plane asks each node's FerretDB for a MongoDB hello over TLS on 27017, the way a client would, and looks at Postgres under it (replication, disk, WAL, the certificate):

  • FerretDB on the primary not answering while Postgres is up is critical: no MongoDB client can connect. FerretDB restarts a second after it dies, so the problem is raised only when it is still down three minutes later (a crash loop), and mailed to the organization's admins with the other open problems.
  • FerretDB on a replica not answering is a warning: a failover to that node would leave the cluster without an endpoint.

The metric docdb_up (1 answers, 0 does not) is recorded per node every two minutes; alarm on min < 1 to hear about it your own way (Monitoring → Alarms). GET /docdb/api/clusters/{id}/health returns the open problems.

Logs shows FerretDB's log and the Postgres server log from every node, newest first, kept seven days; filter by source, severity and text. FerretDB's lines start with [ferretdb]; its INFO reads as LOG and WARN as WARNING. GET /docdb/api/clusters/{id}/logs?source=ferretdb&severity=error (docdb:DescribeDocdbLogs, sensitive: the logs carry user names, client addresses and statement text). Nodes built before 2026-11-15 send the Postgres log only.

Backups and restore

Backups are the managed Postgres backups underneath: pgBackRest, encrypted, in the platform's object storage, a full backup every night in the backup window and the write-ahead log continuously, kept for the retention you set (0 to 35 days; 0 turns them off).

  • Backups lists them, the window a restore may name, and the restores made from this cluster. Back up now (POST /docdb/api/clusters/{id}/backups, docdb:CreateDocdbBackup) takes a full backup within a minute.
  • Restore… builds a new cluster from this one's backups: to the latest moment, to any second in the window (point in time), or to the end of one backup (a snapshot). The source keeps running untouched. The new cluster has the same users and documents as of that moment, 1 or 3 nodes, and its own master password in Secrets.
POST /docdb/api/clusters/{id}/restore
{ "targetIdentifier": "catalog-before-import", "recoveryTarget": "time", "recoveryTargetTime": "2026-11-15T09:41:00Z" }

Needs docdb:RestoreDocdbCluster (and kms:Encrypt on a customer key for the new disks). recoveryTarget is latest, time (with recoveryTargetTime) or label (with recoveryTargetLabel, a backup's label); nodes, nodeType and kmsKeyId are optional. It answers 202 with the restore and the new cluster, creating until FerretDB answers on it. CLI: dcloud docdb backups restore <id> --target-identifier … --recovery-target time --recovery-target-time ….

Change a cluster

Settings, the API or Terraform (node_type, backup_retention_days, deletion_protection change in place):

Change API Effect
Machine type PATCH /docdb/api/clusters/{id}/node-type { "nodeType": "performance-8" } 3 nodes: one node at a time, replicas first, a switchover before the primary; the cluster stays available. 1 node: one restart (about a minute).
Deletion protection PATCH …/deletion-protection { "enabled": true } While on, a delete is refused everywhere.
Backups PATCH …/backup-settings { "backupRetentionDays": 14, "backupWindow": "02:00-03:00" } The node applies both within a minute.
Master password POST …/master-password/rotate A new password, filed as a new version of the secret; the old one stops working at once. Apps bound to the cluster are redeployed with it.

The first three need docdb:ModifyDocdbCluster, the rotation docdb:RotateDocdbMasterPassword. Each is on Activity.

Delete a cluster

Danger zone → Delete cluster (type the cluster's name to confirm), dcloud docdb clusters delete <id>, or DELETE /docdb/api/clusters/{id} (docdb:DeleteDocdbCluster). A cluster with deletion protection on refuses the delete until protection is turned off.

With a final backup (the console's Take a final backup box, on by default when backups are on; ?finalBackup=true in the API): a full backup is taken first and waited for; if it fails, nothing is deleted and the cluster is available again. Then the machines, their volumes (and the volumes' keys) and the balancer are removed, and the cluster stays listed under its own name as Deleted, backups kept for its backup retention period, with Backups, Activity and Danger zone. Every backup of the window is kept, the ones you took by hand too, with the master password; restore from them into a new cluster until then. Danger zone → Remove backups removes them at once. The dialog says what keeping them costs (free up to the cluster's volume size, then the backup rate per GiB-month).

Without it, the backups (the ones you took by hand included) and the master password go with the cluster, and the documents cannot be recovered.

A backup you take with Back up now is kept until you delete it (at most 20 per cluster; Backups → Delete, or DELETE /docdb/api/clusters/{id}/backups/{backupId}, docdb:DeleteDocdbBackup), also after the cluster is deleted; it restores to its own end. On clusters built before 2026-11-18 (keepsByHand: false in GET …/backups) it follows the retention period like the daily ones until its machines' backup scripts are replaced.

Third-party software

Software Licence Source
FerretDB 2.7 Apache-2.0 https://github.com/FerretDB/FerretDB
DocumentDB extension MIT https://github.com/documentdb/documentdb (FerretDB's build: https://github.com/FerretDB/documentdb)
pg_cron, RUM, pgvector PostgreSQL licence https://github.com/citusdata/pg_cron, https://github.com/postgrespro/rum, https://github.com/pgvector/pgvector
PostGIS GPL-2.0 https://postgis.net

The FerretDB and DocumentDB packages a node installs are the upstream release files, pinned by SHA-256 in Deutsche Cloud's code. A node downloads them from the Deutsche Cloud control plane first (which fetched and checked them when its image was built) and from GitHub only if that fails, so a GitHub outage does not stop a cluster from being created or a node from being replaced.

MongoDB is a trademark of MongoDB, Inc.; Deutsche Cloud is not affiliated with MongoDB, Inc. Document Database clusters are compatible with MongoDB drivers and tools, not MongoDB itself.

Did this page help you?