Creates a new database, auto-selecting the adapter based on location.

• "http://..." or "https://..." → Adapter::HTTP (remote CouchDB)
• ":memory:" → Adapter::SQLite in-memory (no persistence)
• any other string → Adapter::SQLite file database (.db appended if needed)

Accepts a pre-built adapter directly. Use this to inject a custom adapter implementation or a pre-configured Adapter::HTTP (e.g. with #bearer_token= or TLS already set).

adapter = CouchDB::Adapter::HTTP.new("https://db.example.com/mydb")
adapter.bearer_token = "secret"
db = CouchDB::Database.new(adapter)

Creates a LocalReplica: a local SQLite database that continuously syncs bidirectionally with the remote CouchDB at remote_url.

All reads go to the local store. Writes go to local by default; pass write_upstream: true to write to the remote instead and block until the change replicates locally.

Checkpoints are stored on the remote only, so deleting and recreating the local file resumes from where replication left off.

db = CouchDB::Database.local_replica("notes.db",
  "https://user:pass@mycouch.example.com/notes")
db.on_sync_error { |dir, ex| Log.error { "#{dir}: #{ex.message}" } }
db.close # stops background sync

Returns the underlying adapter (SQLite or HTTP).

Lists all non-deleted documents. Pass include_docs: true for full bodies, limit/skip for pagination, startkey/endkey for range queries (inclusive).

Typed overload — deserializes each row's doc into klass. Implies include_docs: true; all other parameters work identically.

Example:

result = db.all_docs(as: Note, limit: 50)
result[:rows] # => Array(Note)
result[:total_rows]

Sets Bearer token authentication on the HTTP adapter, replacing any URL credentials. No-op for SQLite.

Batch write. Pass new_edits: false for the replication write path (bypasses conflict detection and stores revisions exactly as supplied).

Fetches specific {id, rev} pairs in bulk. Used internally by the replication engine.

Returns changes since a sequence number. Use "0" to fetch all changes. Pass include_docs: true to embed full document bodies in each change entry.

Streams changes continuously, yielding each change entry to the block. Call break from the block to stop. since defaults to "0" (all changes). heartbeat controls polling interval (SQLite) or CouchDB heartbeat (HTTP) in ms.

Releases the underlying adapter's connection or database handle.

Removes an attachment, creating a new document revision. Raises Conflict on rev mismatch.

Runs an in-memory Mango selector query over all documents, PouchDB/CouchDB-style.

selector is a JSON::Any hash describing match conditions (see README for full operator reference). fields limits the keys returned per doc. sort is an array of bare field name strings (ascending) or single-key hashes with "asc"/"desc" values. limit and skip control pagination.

result = db.find(JSON.parse(%({"type": "note"})))
result[:docs].each { |doc| puts doc["title"] }
result[:warning] # => always present (full scan, no index)

Typed overload — deserializes the stored document into a specific Document subclass.

Example:

note = db.get("note-1", as: MyNote)
note.title # strongly-typed field

Fetches the winning revision of a document. Raises NotFound if absent or deleted.

Returns raw bytes and content-type for an attachment. Raises NotFound if absent.

Reads a _local/ checkpoint document. Used internally by replication.

Returns {db_name:, doc_count:, update_seq:} for the underlying database.

Register a block invoked when #put raises Conflict. Return a Document to retry (system sets the correct rev automatically). Return nil to re-raise. Raise to propagate a custom exception.

Register a block invoked when #remove raises Conflict. Return true to retry the delete with the current rev. Return nil to re-raise.

Registers a before-request interceptor on the HTTP adapter. No-op for SQLite.

Registers an after-response interceptor on the HTTP adapter. No-op for SQLite.

Creates or updates a document. Pass doc.rev for updates. Raises Conflict on a rev mismatch. Returns {ok: true, id:, rev:}.

Stores binary data as an attachment, creating a new document revision. Raises Conflict on rev mismatch.

Writes a _local/ checkpoint document. Used internally by replication.

Runs an in-memory map/reduce query over all documents, PouchDB-style.

The map block receives each document and an emit proc; call emit.call(key, value) to include a row in the result set. Rows are sorted by key using CouchDB collation order.

result = db.query do |doc, emit|
  emit.call(JSON::Any.new(doc["type"].as_s), JSON::Any.new(1_i64))
end
result[:rows].each { |r| puts "#{r["key"]} → #{r["value"]}" }

Soft-deletes a document by writing a tombstone. Raises Conflict on rev mismatch.

Pulls changes from source into this database. Returns a Replication::Session.

Pass doc_ids to replicate only specific documents by ID. Pass selector (a Mango selector as JSON::Any) to filter by document content. Pass filter for an ad-hoc Proc(Document, Bool) predicate.

Pushes local changes to target. Returns a Replication::Session with transfer stats.

Pass doc_ids to replicate only specific documents by ID. Pass selector (a Mango selector as JSON::Any) to filter by document content. Pass filter for an ad-hoc Proc(Document, Bool) predicate. selector and filter are mutually exclusive; filter takes precedence.

Returns missing revisions for the given id → [revs] map. Used internally by the replication engine.

Bidirectional sync: pulls from remote then pushes to remote. Equivalent to replicate_from(remote) followed by replicate_to(remote). Accepts the same doc_ids, selector, and filter options as #replicate_to/#replicate_from.

Assigns a TLS client context used for mutual TLS (mTLS) on HTTPS connections. No-op when the underlying adapter is SQLite.

ctx = OpenSSL::SSL::Context::Client.new
ctx.certificate_file = "client.crt"
ctx.private_key_file = "client.key"
db.tls = ctx