diff --git a/modules/manage/pages/database-offline.adoc b/modules/manage/pages/database-offline.adoc index f4797065..1282e84a 100644 --- a/modules/manage/pages/database-offline.adoc +++ b/modules/manage/pages/database-offline.adoc @@ -26,6 +26,22 @@ The change of status (online or offline) of a database occurs only in the specif 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. +== Configuration Mode Considerations + +The workflow for taking databases offline/online differs depending on your configuration mode: + +*Persistent Configuration (Recommended)*:: +* Configuration is stored in Couchbase Server +* Changes propagate automatically to all Sync Gateway nodes +* DO NOT use `/{db}/_offline` and `/{db}/_online` endpoints (these are node-local only) +* Use `POST /{db}/_config` with `{"offline": true/false}` instead +* Can use Load Balancer for configuration changes + +*Non-Persistent Configuration (Legacy)*:: +* Configuration stored in local config files +* Must coordinate changes across all nodes manually +* Must use `/{db}/_offline` and `/{db}/_online` on each individual node +* Cannot use Load Balancer for these operations == Use Cases @@ -41,13 +57,20 @@ Specific uses for the database offline/online functionality include: == Actions -* Taking a database offline: xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_offline[POST /+{db}+/_offline] -* Taking a database online: xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_online[POST /+{db}+/_online] +*For Persistent Configuration:*:: +* Taking a database offline: `POST /{db}/_config` with `{"offline": true}` +* Taking a database online: `POST /{db}/_config` with `{"offline": false}` +* These operations can be performed through a Load Balancer + +*For Non-Persistent Configuration:*:: +* Taking a database offline: `POST /{db}/_offline` (must be called on each node) +* Taking a database online: `POST /{db}/_online` (must be called on each node) +* Do not use Load Balancer - target each node directly 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 {rest-api-admin--xref--database-configuration}. -Later, to bring the database online, you can use the `+POST /{db}/_online+` Admin REST API request. +Later, to bring the database online, you can use the appropriate method for your configuration mode as described above. == Automatic Offlining diff --git a/modules/manage/pages/resync.adoc b/modules/manage/pages/resync.adoc index eb0ab5f9..13688b4c 100644 --- a/modules/manage/pages/resync.adoc +++ b/modules/manage/pages/resync.adoc @@ -82,7 +82,10 @@ xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_onl Resync is run asynchronously. Its status can be monitored using {resync_api_get}. -Be sure to take the database offline using xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_offline[+/{db}/_offline+]. +*Before running resync, take the database offline:* + +* *Persistent Configuration*: Use xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_offline[+/{db}/_offline+] with `{"offline": true}` (can use Load Balancer) +* *Non-Persistent Configuration*: Use xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_offline[+/{db}/_offline+] on each node individually (do not use Load Balancer) === Resync Context @@ -104,11 +107,27 @@ Once you detect the resync is complete, switch back to the main Sync Gateway and === Updating Clusters -In a clustered environment with multiple Sync Gateway instances sharing the load, all the instances need to share the same configuration. -To ensure this happens, you must taken all instances offline using the xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_offline[+/{db}/_offline+] endpoint. +*For Persistent Configuration:* + +In a clustered environment using persistent configuration, the process is simplified: + +. Take the database offline: `POST /{db}/_config` with `{"offline": true}` (via Load Balancer) +. Update the sync function in the configuration +. Run resync: xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_resync[+POST /{db}/_resync?action=start+] (via Load Balancer) +. Monitor resync status: {resync_api_get} +. Bring the database back online: `POST /{db}/_config` with `{"offline": false}` (via Load Balancer) + +All configuration changes propagate automatically to all Sync Gateway nodes. + +*For Non-Persistent Configuration:* + +In a clustered environment with multiple Sync Gateway instances sharing the load, all instances need to share the same configuration: -After the configuration is updated, *one* instance should be brought up so it can update the database--if more than one is running at this time, they'll conflict with each other. -After the first instance finishes opening the database, the others can be started. +. Take all instances offline by calling xref:rest-api:rest_api_admin.adoc#tag/Database-Management/operation/post_db-_offline[+/{db}/_offline+] on each node individually (do not use Load Balancer) +. Update the configuration file on all nodes +. Bring one instance online first to update the database +. After the first instance finishes opening the database, bring the other instances online +. If more than one instance is brought online simultaneously during this process, they may conflict with each other