Df Couchdb Laravel Package

Getting Started

Assumes a working DreamFactory instance (Laravel app) with the admin UI reachable at /admin and a shell in the app root.

1. Install the connector into the DreamFactory codebase — not into your app:

   composer require dreamfactory/df-couchdb
   php artisan dreamfactory:setup
   php artisan cache:clear
   

2. Look here first after install:
   • vendor/dreamfactory/df-couchdb/composer.json — confirms the df-core version it is pinned against (mismatched df-core majors are the most common install failure).
   • vendor/dreamfactory/df-couchdb/src/ — the service provider + connector class (usually extends the NoSQL/Document base from df-core).
   • vendor/dreamfactory/df-couchdb/config/ — the service-type definition that populates the Admin UI form fields (host, port, database, credentials, max_records, SSL flags).
3. Register a service: Admin → Services → Create → CouchDB. Point it at one CouchDB database (CouchDB "databases" map to DreamFactory services here, not to tables). Give it an API key in Role-based access control.
4. First successful call — verify the wire format before writing app code:

   curl -H "X-DreamFactory-Api-Key: <key>" \
     "https://df.example.com/api/v2/couchdb/_schema"
   curl -H "X-DreamFactory-Api-Key: <key>" \
     "https://df.example.com/api/v2/couchdb/_table/people?limit=5"
   

The first real use case is almost always exposing a CouchDB documents database as a governed REST endpoint: your app talks DreamFactory's uniform _table API (same shape as MySQL, MongoDB, S3, etc.), and DreamFactory handles API keys, roles, rate limits, audit logging, and OpenAPI generation — while CouchDB credentials never leave the server.

Implementation Patterns

One service per database. Because CouchDB has no cross-database joins, don't try to make one service span multiple DBs. Register couchdb-crm, couchdb-catalog, etc., and let roles scope which API keys can hit which.

Use the unified API, not the CouchDB REST API. Treat the service like any other DreamFactory resource:

• GET /api/v2/{svc}/_schema — discover what the connector thinks your collections/fields are.
• GET /api/v2/{svc}/_table/{table}?limit=25&offset=0&filter=status='active' — list.
• POST /api/v2/{svc}/_table/{table} — create (accepts an array of records for bulk).
• PUT /api/v2/{svc}/_table/{table}/{id} and DELETE — mutate by document id.

The big win over hitting CouchDB directly is that this URL is byte-for-byte the same shape as every other DreamFactory service, so your front-end client and generated OpenAPI/SDKs don't change when you swap the backing store.

Push business logic into server-side scripts. DreamFactory's scripted services (df-core) run before/after the connector. Use a post-process script on _table/{table} to flatten _rev out of responses before they hit the client, or a pre-process script on PUT to fetch the current _rev and inject it — that keeps clients from having to do the two-step read-modify-write.

Govern at the DreamFactory layer, not CouchDB. Define roles like catalog-reader (GET only) and catalog-writer (POST/PUT/DELETE), bind them to API keys, and use df-oauth / df-jwt if you need user identity. CouchDB's own _security and per-database admin users become an implementation detail; only DreamFactory talks to them.

Pair with df-openapi / LLM tooling. Because the connector exposes services in DreamFactory's standard OpenAPI form, you can hand an LLM or MCP client a single spec covering CouchDB, Postgres, and S3 together — this is the package's real value proposition in the score's "opportunity" sense, and it's exactly what the 2-star repo under-serves in docs.

Combine with other df-* connectors for composite endpoints. A custom scripted service can call couchdb plus df-s3 in one server-side script, giving you a single API endpoint that both writes a document and stashes a binary attachment.

Backfill via bulk POST. For migrations into CouchDB, batch documents through POST /_table/{table} in chunks of a few hundred (CouchDB's _bulk_docs semantics behind the scenes) rather than one request per doc — order-of-magnitude fewer round trips and far fewer _rev conflict races.

Gotchas and Tips

_rev is the #1 source of 409s. CouchDB uses optimistic concurrency. Any PUT without the current _rev (or with a stale one) fails with a conflict that DreamFactory surfaces as a generic 4xx. Either include _rev in the payload from the last GET, or write a pre-process script that does a GET-then-merge server-side. Do not assume DreamFactory will fetch the revision for you.

_id vs id. Responses may carry both, depending on the connector version — CouchDB natively uses _id, but DreamFactory normalizes to id for cross-service consistency. Pin this down on day one by inspecting one GET response; don't code against the docs, code against the wire.

Schema discovery is weak by design. CouchDB is schemaless; the _schema endpoint infers types from a sample of documents. Fields that don't appear in the sample are invisible to DreamFactory's validation, and a field that's sometimes a string and sometimes an array will show an unstable type. If you need strict contracts, back the service with a scripted service that declares fields explicitly, or accept that _schema is advisory only.

Design documents and views are not tables. A _design/foo document is a document, but the connector generally won't let you call the resulting view as a queryable "table." If your app depends on map/reduce views, either materialize them into regular documents, or use a custom scripted service that hits CouchDB's view URL through the connector's client.

offset/skip is O(n) on the server. For large collections, deep pagination gets slow fast. Use CouchDB-native cursor pagination if the connector exposes it (startkey_docid / bookmark), and cap results with the service's max_records setting so a stray ?limit= can't try to pull the whole DB.

Cache the schema, then forget you did. DreamFactory caches service metadata. After editing a design doc or adding fields to your documents, _schema will lie until you php artisan cache:clear (or hit Admin → Cache). Budget for this in CI: any deployment that changes document shape needs a cache flush.

Attachments are not first-class. The _table abstraction doesn't map cleanly to CouchDB attachments. Keep binaries in df-s3 or a filesystem service and store a reference in the document — a pattern the connector implicitly encourages.

Self-signed TLS will bite you. If CouchDB is behind a private CA, the connector's cURL/HTTP client rejects it. Prefer configuring a CA bundle at the service level over disabling verification; if you must disable it for a dev instance, do it in the service config (there's usually an SSL verify toggle) and never commit that config.

Debugging path: check storage/logs/laravel.log for the connector's exception text, then re-issue the failing request directly against CouchDB with the same credentials to isolate whether the problem is the connector or the database. DreamFactory's API debug/X-DreamFactory-* headers are useful here.

Version sensitivity: this connector is pinned to specific df-core releases. If you're on an older DreamFactory, composer require may silently resolve to an ancient tag. Check composer show dreamfactory/df-couchdb and the require block before assuming a bug in your data.

Extension point: the clean way to add behavior (revision handling, custom query translation, view invocation) is a small in-house df-* service provider that extends the connector class from src/ and overrides the resource handler — not forking the vendor package. Keep it as a sibling Composer package so composer update doesn't overwrite you.