Faz Docs

Connect faz to a CouchDB database. Mango JSON queries plus _all_docs and _view, BasicAuth.

CouchDB's connector talks to the HTTP REST API and accepts queries in Mango (JSON) format or via _all_docs / view paths. Auth is HTTP BasicAuth.

Default port	Query language	Write support	Schema discovery	Driver
5984	Mango (JSON)	Yes (RBAC-gated)	DB enumeration	`aiohttp` (REST)

Quick example

faz.yaml

databases:
  - name: <database>          # used as --database <database> in queries
    type: couchdb
    host: localhost
    port: 5984
    database: <db-name>       # the actual CouchDB database on the host
    username: <username>
    password: <password>

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — find, all_docs, view
    # W    write only          — insertOne, update, delete (no reads)
    # RW   read + write
    # RA   read + append       — reads + insertOne / bulk_docs
    # RWA  read + write, no DELETE
    # A    admin (incl. view creation and DDL)

See Permissions for the full model, per-table overrides, and the operation matrix.

faz query '{"operation":"find","selector":{},"limit":5}' --database <database> --table <db-name> --language couchdb

uv run faz query '{"operation":"find","selector":{},"limit":5}' --database <database> --table <db-name> --language couchdb

python -m faz query '{"operation":"find","selector":{},"limit":5}' --database <database> --table <db-name> --language couchdb

Configuration

Field	Type	Default	Notes
`host`	string	`localhost`	CouchDB host or IP.
`port`	integer	`5984`	CouchDB port. Use `6984` for HTTPS-only deployments.
`database`	string	`""`	The default CouchDB database to query. Other DBs are reachable but `database` drives default routing.
`username`	string	`""`	CouchDB admin or member user.
`password`	string	`""`	Password (sent as HTTP Basic).
`ssl`	boolean	`false`	When `true`, uses HTTPS instead of HTTP.
`extra`	mapping	`{}`	Reserved.

Capabilities

Supported operations (JSON operation field):

Operation	Op class	Notes
`find`	SELECT	Mango selector + `limit` + `fields`.
`all_docs`	SELECT	`_all_docs` view; useful for ID-based reads.
`view`	SELECT	Predefined view name + start/end keys.
`insertOne`	INSERT	`document` (one).
`bulk_docs`	INSERT	Multiple documents in one round trip.
`update`	UPDATE	`id` + new document body.
`delete`	DELETE	`id` + `rev`.

Schema discovery enumerates user databases by listing _all_dbs and excluding system databases (_users, _replicator, _global_changes).

Limitations

Per-document permissions in CouchDB (read/write rights set in _security) are enforced by CouchDB itself; faz's RBAC operates at the database (not document) level.
Views are read-only at the connector level — the view operation runs the precomputed view but doesn't create or update one. Adding views is DDL-equivalent and requires the A access level.
No streaming — full result sets are loaded.

Troubleshooting

ConnectionRefusedError / network timeouts — CouchDB isn't listening on host:port. Try curl http://host:port/; you should get a JSON banner.

401 Unauthorized — credentials are wrong or the user isn't in the database's _security. Test via curl: curl -u user:pass http://host:port/_all_dbs.

Database does not exist — database value in faz.yaml doesn't match any CouchDB database. List them with curl -u user:pass http://host:port/_all_dbs.

For the broader troubleshooting flow, see Connection failed.

Databases overview — cross-connector basics.
MongoDB — sibling document database with a similar query shape.
faz.yaml — the full config schema.

CouchDB

Quick example

Configuration

Capabilities

Limitations

Troubleshooting

Related

On this page