A newer version of this documentation is available.

View Latest

Take Database Offline/Online


      How to take a Sync Gateway database offline and bring back online.


      Sync Gateway enables a database to be taken offline and brought back online. This is done without stopping the Sync Gateway instance and without affecting other databases served by it.

      The change of status (online or offline) of a database occurs only in the specific Sync Gateway instance addressed. It is not reflected by other Sync Gateway instances using that database. To achieve that, you need to coordinate individual change operations in each of the required Sync Gateway instances.

      Use Cases

      Specific uses for the database offline/online functionality include:

      • Taking a database offline, without affecting other databases.

      • Changing configuration properties for a database (while it is offline), without needing to restart Sync Gateway.

      • Resynchronizing a database while it is offline.

      • Detecting a lost DCP or TAP feed, and taking the database offline automatically.

      • Creating a database in an offline state, so that the start of service delivery for the database can be postponed or coordinated across Sync Gateway instances.

      • Performing a Couchbase Server upgrade.


      By default, when Sync Gateway starts, it brings all databases that are defined in the configuration file online. To keep a database offline when Sync Gateway starts, you can add the offline configuration property to the database configuration properties — see Database Configuration.

      Later, to bring the database online, you can use the POST /\{tkn-db}/_online Admin REST API request.

      Automatic Offlining

      Sync Gateway will take a database offline automatically if it loses the database’s DCP and-or TAP feed. This enables the cause to be investigated and rectified.

      Use an Admin REST API request to bring the database back online when the cause is addressed and the feed(s) restored.

      State Diagram

      The state diagram represents the states for Sync Gateway and the connection between it and a Couchbase Server database — see: Figure 1.

      state diagram offline 12
      Figure 1. State Change Diagram

      In the state diagram (fig-state-diag):

      • To the left of the gray dashed line, starting or stopping a Sync Gateway instance affects the connections to all of the databases that the instance serves.

      • To the right of the gray dashed line, you perform operations on specific databases. For example, two databases could be online, while a third database could be taken offline, resynchronized, and then brought back online.