CouchDB

Managed Apache CouchDB: a document database with an HTTP/JSON API and multi-master replication, in single-node or clustered high-availability deployments.

Creating a CouchDB instance

From the phase canvas, click + Service → Databases → CouchDB, then Commit. Pick a plan and storage size, and StackBlaze provisions the instance for you.

Attach the instance from the add-on Connections list or the app Add-ons tab. Check the app Variables tab for the injected keys after you Commit.

CouchDB is a document database with an HTTP/JSON API and multi-master replication. That sync model makes it a good fit for offline-first apps, where a client database (for example PouchDB) replicates with the server and resolves changes when connectivity returns.

Adding CouchDB from the Databases catalog and attaching it to the app injects COUCHDB_URL and COUCHDB_DB.

Connecting

CouchDB exposes an HTTP/JSON REST API on port 5984. Services in the same project reach the database over the cluster's private network using its internal endpoint. The internal address takes the form below:

Endpoint (internal)

http://user:password@[service-name]:5984

Any HTTP client works: curl, a language HTTP library, or a CouchDB driver. The value of COUCHDB_URL already includes the credentials, so you can use it directly.

Browse and query with CloudBeaver

Every database add-on ships with CloudBeaver. Open with DB Beaver on the add-on's Overview starts a scoped session where you can browse tables, run SQL, and edit data in the browser.

Open with DB Beaver launches a scoped CloudBeaver session where the users table is browsed, a query runs, and the results appear.

Standard vs high availability

You choose between Standard and high availability when creating the instance. Standard runs a single node, which is a great fit for development and lower-stakes workloads. High availability runs a clustered deployment of multiple nodes with quorum reads and writes, so documents are replicated across nodes and the database stays available during a node loss.

	Standard	High availability
Topology	Single node	Clustered, multiple nodes
Replication	None (one copy)	Documents replicated across nodes
Reads and writes	Single node	Quorum reads and writes
Survives a node loss	No	Yes, the database stays available
Best for	Development and testing	Production and resilient workloads

Working with documents

CouchDB is driven entirely over HTTP. Create a database with PUT, add a document with POST, and read it back with GET, all against COUCHDB_URL:

documents.sh

# Create a database named "app"
curl -X PUT "$COUCHDB_URL/app"

# Create a document in that database
curl -X POST "$COUCHDB_URL/app" \
  -H "Content-Type: application/json" \
  -d '{"_id": "user:1", "name": "Ada"}'

# Read the document back
curl "$COUCHDB_URL/app/user:1"

Backups

StackBlaze takes automated, encrypted backups that follow the platform backup policy applied to all managed databases. For details on schedules, restores, and how the policy works, see /docs/databases/backups.

Under the hood

Apache CouchDB is a document database with an HTTP API and multi-master replication. StackBlaze runs it via a Kubernetes operator with persistent volumes, and in high availability mode it clusters multiple nodes with quorum so the database tolerates the loss of a node.