Replication: one-off and continuous jobs via _replicate, persistent
ones as documents in _replicator, and the scheduler that runs them.
If the only tool you have is CouchDB, then everything looks like
{:ok, :relax}
See _replicate and _scheduler at
https://docs.couchdb.org/en/stable/api/server/common.html. A source or
target is a database URL with credentials, or a %Sofa{} handle with
its database set, which endpoint/1 turns into one. The documented
options go along as given: continuous, create_target, doc_ids,
filter, selector, winning_revs_only, source_proxy,
target_proxy, create_target_params.
Scheduler documents and transient states
The _scheduler/docs/{db}/{docid} endpoint lags replication itself.
When a job is being created or finishing, CouchDB briefly answers 200
with a null "state".
See CouchDB https://github.com/apache/couchdb/issues/5008 for details.
doc/3 reports that window as {:error, :no_state} instead of a
stateless document, so poll it until you get a real "state". A
document the scheduler has not seen will return a valid 404, reported as
{:error, :not_found}.
Examples
{:ok, %{"ok" => true, "history" => [_ | _]}} = Sofa.Replication.replicate(server, db_a, db_b, create_target: true)
{:ok, %{"ok" => true, "_local_id" => id}} = Sofa.Replication.replicate(server, db_a, db_b, continuous: true)
{:ok, jobs} = Sofa.Replication.jobs(server)
{:ok, _} = Sofa.Replication.cancel(server, db_a, db_b, continuous: true)
Sofa.Replication.new(db_a, db_b, continuous: true) |> Sofa.Doc.save(%Sofa{server | database: "_replicator"})
Summary
Functions
Cancels a replication started with replicate/4, given the same source,
target and options, as CouchDB identifies it by them.
The scheduler's state for one replication document. While CouchDB is
turning a replication document into or out of a job there is a brief
window where the endpoint answers 200 with a null "state". Those
replies come back as {:error, :no_state} so callers can tell them apart
from a document the scheduler has not seen yet and keep retrying.
The state of every replication document the scheduler knows, across all
replicator databases or for one, as the documented objects with their
"state", "info" and "error_count". Options: limit: and skip:.
A replication endpoint for a handle: its server URL with the credentials and database, as CouchDB wants them. Strings and maps are passed through.
The replication jobs the scheduler is running, as the documented job
objects. Options: limit: and skip:.
A replication document for the _replicator database, where CouchDB
keeps persistent replications: save it with Sofa.Doc.save/2 on a
handle opened on _replicator, delete it to stop. The id is random
unless given as id:.
Starts a replication and, for a one-off one, waits for it: the reply is
the documented result with its "history". A continuous: true
replication is accepted instead, with a "_local_id" to cancel it by.
Server admin only.
Types
@type error() :: Sofa.Response.error() | term()
Functions
Cancels a replication started with replicate/4, given the same source,
target and options, as CouchDB identifies it by them.
The scheduler's state for one replication document. While CouchDB is
turning a replication document into or out of a job there is a brief
window where the endpoint answers 200 with a null "state". Those
replies come back as {:error, :no_state} so callers can tell them apart
from a document the scheduler has not seen yet and keep retrying.
The state of every replication document the scheduler knows, across all
replicator databases or for one, as the documented objects with their
"state", "info" and "error_count". Options: limit: and skip:.
A replication endpoint for a handle: its server URL with the credentials and database, as CouchDB wants them. Strings and maps are passed through.
iex> Sofa.init("http://admin:passwd@couch.example:5984/") |> Map.put(:database, "recipes") |> Sofa.Replication.endpoint()
"http://admin:passwd@couch.example:5984/recipes"
The replication jobs the scheduler is running, as the documented job
objects. Options: limit: and skip:.
@spec new(endpoint(), endpoint(), keyword()) :: Sofa.Doc.t()
A replication document for the _replicator database, where CouchDB
keeps persistent replications: save it with Sofa.Doc.save/2 on a
handle opened on _replicator, delete it to stop. The id is random
unless given as id:.
Starts a replication and, for a one-off one, waits for it: the reply is
the documented result with its "history". A continuous: true
replication is accepted instead, with a "_local_id" to cancel it by.
Server admin only.