Skip to content

update db offline settings #937

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: release/4.0
Choose a base branch
from
Open

update db offline settings #937

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions modules/manage/pages/database-offline.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
29 changes: 24 additions & 5 deletions modules/manage/pages/resync.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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



Expand Down