CouchDB

Tested with: CouchDB 3.5 on Databasezy · zb CLI 0.1

Apache CouchDB stores JSON documents behind a plain HTTP API and replicates in both directions with other CouchDB servers and with PouchDB in browsers and mobile apps, so offline-first apps can sync when they reconnect.

Overview

Each instance runs the official Apache CouchDB 3 image as a single node. The generated credential is a CouchDB server admin (admin). Use it to create databases and per-application users, not as the login your app or its end users share. The Fauxton web interface is served at /_utils on the same HTTPS endpoint.

CouchDB at a glance, from the engine catalogue
Status	Available
Category	Document (sync)
Versions	3.5, 3.4 (newest is the default)
Protocol and port	HTTPS on `443`
Runtime	Single-node engine (couchdb)
Backups	data directory snapshot
Point-in-time recovery	No
Pause	Scale to zero
Free plan	No, paid plans only
Licence	Apache-2.0

When to use it

Offline-first mobile and web apps that sync with PouchDB.
Field data collection and multi-device apps that write while disconnected and resolve conflicts later.
A document store you want to reach with nothing but HTTP and JSON.

Pick FerretDB or MongoDB for MongoDB drivers and richer queries, and PostgreSQL when you need joins and transactions across records.

Create an instance

Open the portal and choose New instance.
Pick CouchDB and a version (3.5, 3.4).
Choose a size and region. Secure placement is listed only after your organization has signed the BAA.
Check the hourly price and monthly estimate, then confirm. The Connect tab fills in when the instance is ready.

zb instances create --engine couchdb --engine-version 3.5 \
  --size s1 --region us-east --name couchdb-demo --wait

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

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": "couchdb",
  "engine_version": "3.5",
  "size": "s1",
  "region": "us-east",
  "name": "couchdb-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

Endpoint and credentials

How a CouchDB instance is reached: host, ports, TLS and credentials
Host	`couchdb-<id>.<region>.databasezy.com`, for example `couchdb-7f3k.us-east.databasezy.com`
Port `443`	HTTP API, including the replication protocol
Single-IP regions	Single-IP regions use `8443` for HTTP engines instead of `443`. The portal Connect page always shows the right port.
TLS	Required on every port; plaintext is refused. Verify the server: https:// (or the driver's TLS flag) with normal certificate verification; the certificate is publicly trusted.
Credentials	Username admin and a generated password, presented as HTTP Basic authentication or a _session cookie. Shown once at creation; reveal or rotate it from the Connect tab.

Every request is HTTPS with HTTP Basic authentication or a session cookie from POST /_session. Replication targets and sources are plain https:// URLs.

Drivers and clients

CouchDB listens on port 443 (HTTP API, including the replication protocol). Versions: 3.5, 3.4. Replace the example host with the one on your instance's Connect tab; credentials are shown once at creation.

https://couchdb-7f3k.us-east.databasezy.com:443

import Nano from "nano";

const couch = Nano({
  url: "https://couchdb-7f3k.us-east.databasezy.com:443", // TLS, publicly trusted certificate
  requestDefaults: { auth: { username: "admin", password: process.env.ZB_PASSWORD } },
});

await couch.db.create("inspections").catch((err) => {
  if (err.statusCode !== 412) throw err; // 412: already exists
});
const db = couch.use("inspections");
await db.insert({ _id: "insp-2291", site: "north-yard", passed: false });
console.log(await db.find({ selector: { passed: false }, limit: 10 }));

Tested with: CouchDB 3.5 · nano 10

import PouchDB from "pouchdb";

// Give each app user their own CouchDB user (POST /_users); never ship the
// instance's admin credentials to a browser or mobile app.
const local = new PouchDB("inspections");
const remote = new PouchDB("https://couchdb-7f3k.us-east.databasezy.com:443/inspections", {
  auth: { username: "field-app", password: sessionPassword },
});

local
  .sync(remote, { live: true, retry: true }) // resumes from the last checkpoint
  .on("change", (info) => console.log("synced", info.direction, info.change.docs.length))
  .on("error", (err) => console.error(err));

Tested with: CouchDB 3.5 · PouchDB 9

curl -sS -u admin:$ZB_PASSWORD https://couchdb-7f3k.us-east.databasezy.com:443/
curl -sS -u admin:$ZB_PASSWORD -X PUT https://couchdb-7f3k.us-east.databasezy.com:443/inspections
curl -sS -u admin:$ZB_PASSWORD https://couchdb-7f3k.us-east.databasezy.com:443/_all_dbs

Tested with: CouchDB 3.5 · curl 8

For apps, create a user per application or per end user in the _users database and grant it access to a database through that database’s _security object, instead of handing out the admin credential:

curl -sS -u admin:$ZB_PASSWORD -X PUT \
https://couchdb-7f3k.us-east.databasezy.com:443/_users/org.couchdb.user:field-app \
-H "Content-Type: application/json" \
-d '{"name": "field-app", "password": "<app-password>", "roles": [], "type": "user"}'

curl -sS -u admin:$ZB_PASSWORD -X PUT \
https://couchdb-7f3k.us-east.databasezy.com:443/inspections/_security \
-H "Content-Type: application/json" \
-d '{"members": {"names": ["field-app"], "roles": []}, "admins": {"names": [], "roles": []}}'

Browsers enforce CORS, so a PouchDB app served from your own origin also needs CORS enabled for that origin. Set it once through CouchDB’s configuration API; configuration changes are kept across restarts, pauses, resizes and upgrades, and they travel with backups and branches:

curl -sS -u admin:$ZB_PASSWORD -X PUT \
https://couchdb-7f3k.us-east.databasezy.com:443/_node/_local/_config/chttpd/enable_cors -d '"true"'

curl -sS -u admin:$ZB_PASSWORD -X PUT \
https://couchdb-7f3k.us-east.databasezy.com:443/_node/_local/_config/cors/origins -d '"https://app.example.com"'

The platform keeps a few settings under its control and resets them at the next restart: the admin password (rotate it from the portal or API instead), the HTTP port and bind address, and the data directories.

See Connecting to Databasezy for the CA bundle, the IP allow-list and credential rotation, which work the same for every engine.

Migrate in

Where you can migrate a CouchDB database from, how, and whether continuous sync is available
Source	How	Continuous sync	Guide status
Self-hosted server	Connection string, Local tools (zb migrate --from local)	No	Available
Another Databasezy instance	Instance to instance	No	Coming soon · phase 2

CouchDB’s own replication is the simplest way in: start a push replication on the source server, targeting the new instance, and it copies every document, revision and attachment, then resumes where it stopped if interrupted.

curl -sS -X POST http://localhost:5984/_replicate -u admin:<source-password> \
-H "Content-Type: application/json" \
-d '{"source": "inspections", "target": {"url": "https://couchdb-7f3k.us-east.databasezy.com:443/inspections", "auth": {"basic": {"username": "admin", "password": "<password>"}}}, "create_target": true}'

Run it with "continuous": true to keep the target current until you switch your apps over.

How migrations work explains preflight, verification and cutover, and engine conversions covers moves between compatible engines.

Backups and restore

A backup is a snapshot of the CouchDB data directory, including every database and its indexes.

CouchDB backups use data directory snapshot. 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 not available for CouchDB. A restore returns the data as of a scheduled or manual backup. 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.

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

Pause and scale to zero

CouchDB 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.

zb instances pause couchdb-demo
zb instances resume couchdb-demo

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

Pausing closes live replications and _changes feeds. PouchDB with retry: true reconnects and resumes from its last checkpoint after you resume the instance.

Limits, versions and lifecycle

Versions and lifecycle

Supported versions: 3.5 , 3.4 . New instances default to 3.5; pick another at creation with --engine-version or in the portal.
Minor and patch releases are applied for you in the maintenance window, always after a pre-change backup.
New majors are added within 60 days of the upstream release. A major reaches end of life on Databasezy six months after upstream ends support, with notices 90, 30 and 7 days ahead.
Moving between majors is a new instance plus an instance-to-instance migration, so you can test the new version before cutting over.

Sizes and limits

CouchDB is not offered on the Free plan; it runs on the paid sizes below. 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 CouchDB: vCPU, memory, storage ceiling, connection limit and monthly price
Size	vCPU	Memory	Max storage	Max connections	≈ $ / month
`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.

Documents are limited by CouchDB’s max_document_size (8 MB by default) and request bodies by max_http_request_size. Keep attachments small; put large files in object storage and store a link. Views and Mango indexes are built on first query after writes, so query them regularly or warm them after bulk loads.

Licence

Databasezy runs CouchDB under the Apache-2.0 licence, as listed in the engine catalogue. Your data and schemas are yours whatever the server's licence; the licence governs the server software we run.

Apache CouchDB is Apache-2.0, as are PouchDB and the official CouchDB clients.

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 HTTPS with certificate verification. 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

Can I sync with PouchDB?

Yes. PouchDB replicates with CouchDB over HTTPS in both directions. Give each app or end user their own CouchDB user rather than the admin credential.

Can I replicate to and from my own CouchDB servers?

Yes. Replication is a CouchDB feature, not a Databasezy one: any CouchDB 2.x or 3.x server, or Cloudant, can push to or pull from an instance over HTTPS.

Which CouchDB versions can I run?

CouchDB 3.5 (the default) and 3.4. An instance on 3.4 can be upgraded to 3.5 in place; databases, users and configuration are kept.

Is CouchDB on the Free plan?

No. It is a paid-plan engine.