Sofa.Replication (sofa v0.8.1)

Copy Markdown View Source

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

endpoint()

@type endpoint() :: String.t() | Sofa.t() | map()

error()

@type error() :: Sofa.Response.error() | term()

Functions

cancel(sofa, source, target, opts \\ [])

@spec cancel(Sofa.t(), endpoint(), endpoint(), keyword()) ::
  {:ok, map()} | {:error, error()}

Cancels a replication started with replicate/4, given the same source, target and options, as CouchDB identifies it by them.

doc(sofa, replicator_db, id)

@spec doc(Sofa.t(), String.t(), String.t()) :: {:ok, map()} | {:error, error()}

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.

docs(sofa, replicator_db \\ nil, opts \\ [])

@spec docs(Sofa.t(), String.t() | nil, keyword()) ::
  {:ok, [map()]} | {:error, error()}

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:.

endpoint(url)

@spec endpoint(endpoint()) :: String.t() | map()

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"

jobs(sofa, opts \\ [])

@spec jobs(Sofa.t(), keyword()) :: {:ok, [map()]} | {:error, error()}

The replication jobs the scheduler is running, as the documented job objects. Options: limit: and skip:.

new(source, target, opts \\ [])

@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:.

replicate(sofa, source, target, opts \\ [])

@spec replicate(Sofa.t(), endpoint(), endpoint(), keyword()) ::
  {:ok, map()} | {:error, error()}

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.