A newer version of this documentation is available.

View Latest

Glossary

      +

      Sync Gateway Glossary of Terms

      Index

      A | [B] | C | [D] | [E] | [F] | G | [H] | I | [J] | [K] | L | [M] | N | O | P | [Q] | R | S | T | [U] | [V] | [W] | [X] | [Y] | [Z]

      A

      Active replicator

      The term active replicator, refers to the Sync Gateway endpoint that initiates the replication connection. That is, it s the Sync Gateway where the replicators are configured and from which the changes are pushed.

      Active Sync Gateway node

      The term active Sync Gateway node, refers to Sync Gateway nodes with incoming writes; these may be from Couchbase Lite clients, the REST API, or through the Couchbase Server.

      • SGW Component: Replication

      Adhoc Replication

      The term adhoc replication refers to transient, one-shot, replications that run once and are removed when they stop. They are initialized using the Admin REST API. They do not survive Sync Gateway restarts.

      Ad hoc replications are useful when it is necessary to do one off replication or for troubleshooting.

      Other useful use cases include:

      • Starting a replication on-demand, for instance a replication that needs to be scheduled to be run at midnight every Thursday.
        In this case, it is likely that there is an automation script that schedules the adhoc replication on a predefined schedule.

      • Deploying an emergency one-time update that needs to be pushed out to all edge clusters from primary data clusters.

      Context:

      Automatic conflict resolution

      The goal of automatic conflict resoluton is to return a winning revision based on the consistent application of the configured conflict resolver policyglossary icon.

      The default conflict resolver policy is to always returns a winner determined by the automatic conflict resolution policyglossary icon.

      Automatic conflict resolution policy

      The automatic conflict resoluton policy will return the most recent change as the winning revision unless one of the revisions was a delete; in which case the delete wins. If both revisions are equally recent then the largest change wins.

      The default automatic conflict resolutionglossary icon policy always returns a winner determined by the following rules:

      • If one of the changes is a delete:

        A deleted document (that is, a tombstone revisionglossary icon) always wins over a document update.

      • If both changes are document changes:

        The change with the most revisions (the longest revision history) will win. Typically, this is the revision with the highest version number.

      • If both changes have the same number of revisions: An ASCII comparison of the revisions is done to pick the winner.

      Back to Index

      C

      Checkpoint

      A Checkpoint, in Couchbase Mobile terms, is a “save state” on a replicator, used to enable a restart at the last success-point in the event of a failure during a replication.

      The checkpoint itself is a (meta)document that describes how far in the replication process a given replicator has progressed.

      Note that two checkpointsglossary icon are saved for every replication; one local and one remote.

      The checkpoint documents are compared at the beginning of every replication. If they do not agree, then it indicates a severe error during the last run, and the replication is forced to restart from the beginning.

      Conflict Resolver Policies

      Inter-Sync Gateway replication provides several predefined conflict resolver policies, which you can choose to apply. These include: default; `localWins, remoteWins; and custom.

      Each conflict resolver policy applies a different strategy:

      Default
      Local Wins
      • Always considers the local change the winner.

      • Configured using: "conflict_resolution_type": "localWins"

      Remote Wins
      • Always considers the remote change the winner.

      • Configured using: "conflict_resolution_type": "remoteWins"

      Custom

      Applies the policy defined in the function provided by the custom_conflict_resolver parameter.

      Custom conflict resolver

      The custom_conflict_resolver property specifies a Javascript function used to resolve conflicting changes.

      This is an ENTERPRISE EDITION only feature and is configured like this:

      "conflict_resolution_type": "custom",
      "custom_conflict_resolver":`
        function(conflict) {
          // Always resolve in favor of remote
          console.log("full remoteDoc doc: "+JSON.stringify(conflict.RemoteDocument));
          return conflict.RemoteDocument;
        }`

      Configuration property: custom_conflict_resolver

      Continuous replication mode

      A continuous replication will sit in running state awaiting document changes to process in accordance to its replication definition.

      Cloud-to-Edge Sync

      The term cloud-to-edge refers to the multi-cloud deployment mode commonly know as ship-to-shore or hub-and-spoke. These typically involve a large number of edge clusters (mobiles,, tablets IoT) connected to one or more cloud data centers.

      Each edge can operate autonomously without network connectivity to the cloud data centers. The edge could be, for example a group of retail stores, ships at sea or distribution hubs. The number of edges can range from a few hundred to several thousand.

      Cloud-to-Edge synchronization

      The term cloud-to-edge synchronization refers to scenarios typically involving a hierarchy of couchbase mobile clusters, within which a large number of edge clusters must synchronize data changes with each other and with one or more clusters in cloud data centers.

      Each edge can operate autonomously without network connectivity to the cloud data centers. The edge could be, for example a group of retail stores, ships at sea or distribution hubs. The number of edges can range from a few hundred to several thousand.

      Back to Index

      G

      Grafana

      Grafana is an open source data visualization and alerting platform. It supports Prometheus as a data source and can be used to build comprehensive dashboards.

      Back to Index

      I

      Inter-Sync Gateway Replication

      The term inter-Sync Gateway replication refers to replication between two Sync Gateway clusters and-or between active mobile clusters.

      From 2.8+ inter-Sync Gateway replication within Sync Gateway is delivered by a completely redesigned and re-engineered websocket-base protocol, which enables a Sync Gateway replicator to act as the active replicatorglossary icon, pulling changes from a data source and pushing them to a target. Pre-2.8 inter-Sync Gateway replication used the SG Replicate protocol over https.

      Back to Index

      L

      Leaf revision

      A Leaf revision is the last Document Revision in a series of changes. Documents may have multiple Leaf Revisions (aka Conflict Revisions) due to concurrent updates.

      Back to Index

      N

      No conflicts mode

      No conflicts mode is the process by which write operations that would result in a conflict are rejected by the system. It is an optional feature in Couchbase Lite 2.0 and Sync Gateway 2.0 and above.

      Example 1. Couchbase Lite Conflict Resolution Links
      No op updates

      The term no-op update refers to a change made to the document body that does not impact application logic but does trigger a replication by the Sync Gateway.

      For example, you may include an otherwise redundant counter property, that you increment in response to conflict resolver errors.

      Back to Index

      O

      One-shot replication mode

      A one-shot replication will start, process all existing document changes in accordance to its replication definition and then stop.

      Once finished, persistent one-shot replications return to a 'stopped' state, but adhoc one-shot replications are removed.

      Back to Index

      P

      Passive replicator

      The term passive replicator, refers to the Sync Gateway endpoint that receives an incoming replication connection.

      Context

      Persistent Exponential Backoff

      The wait time between retry attempts is exponentially increased at each attempt, until it reaches a predetermined maximum limit. Subsequent retries may be made after the maximum limit time period has elapsed.

      Persistent Replication

      The term Persistent replication refers to replications that survive Sync Gateway restarts. All replications are persisted by default unless explicitly flagged as not. Persistent replication is defined in the configuration file sync-gateway.json — see Configuration Properties. It is started automatically and survives restarts. The recommended method of defining a persistent replication is by using the configuration file. With Inter-Sync Gateway replication you can configure all nodes with the replicators.

      Prometheus

      Prometheus is an open source systems monitoring and alerting platform and hosted by Cloud Native Computing Foundation. At the core of it is the Prometheus Server that is responsible for polling “Prometheus targets” for stats and storing it as time series data. Prometheus targets are statically configured or can be discovered by Prometheus.

      Back to Index

      R

      Replication definition

      The term Replication definition refers to that set of elements (parameters or properties) that define a replication, dictating what will be replicated and how the replication will be conducted.

      Replication definitions are provided to Sync Gateway in 'JSON' format through either:

      • The Sync Gateway configuration file (sync-gateway-config.json)

      • The Admin REST API’s replication endpoint, using a utility such as curl, or an application such as _Postman.

      Replication definitions comprise the same elements in both the JSON configuration file and the Admin REST API; except configured replications cannot use adhoc or cancel.

      Revision pruning

      Revision Pruning is the process that deletes the metadata and/or JSON bodies associated with old non-leaf revisions. Leaf revisions are not impacted.

      Back to Index

      S

      Synchronization

      The term, Synchronization, refers to the process of replicating the changes made to documents on one database to the same documents in a second instance of that database.

      Sync Function

      The Sync Function is a JavaScript function whose source code is stored in the Sync Gateway’s database configuration file. It is in charge of data validation, and of authorizing both read and write access to documents.

      Sync Gateway Database

      The term Sync Gateway database refers to what you may consider a namespace for documents. It provides Sync Gateway with access to documents that are stored in Couchbase Server.

      T

      Tombstone revision

      A tombstone revision is essentially a marker indicating that a document has been deleted.

      Each Tombstone Revision comprises: document ID, revision ID and a _deleted flag (value=true). They are created to allow all devices to see that a document has been deleted - particularly in the case of devices that may not be online continuously and therefore not syncing regularly.

      Every update — including deletes — creates a document revision. Deleted revisions are also known as Tombstone revisions. They have the '“_deleted”: true' property, are replicated, but are not returned if you do a query using, for example, Couchbase Lite.

      +

      {
        "_deleted": true,
        "_id": "foobar",
        "_rev": "3-db962c6d93c3f1720cc7d3b6e50ac9df"
      }
      Transient Replication

      The term transient replication refers to ad hoc replications — see: Adhoc Replication

      Back to Index