Database Configuration

bucket

string

Defines the Couchbase Server bucket to be used for this Sync Gateway database bucket

If not specified, then the database name is used as the bucket name.

name

string

Use name to define the Sync Gateway database name.

Change initiates database restart

sync

string

The sync property is a Javascript function that determines which users can access which documents.

This JavaScript function is provisioned using the Admin Rest API Endpoint put /{db}/_config/sync

Add the function as plain javascript in the request body, with the content-Type: application/javascript header.

guest

object

Defines whether a GUEST user is available and able to interacted, unauthenticated, with the Public REST API

guest.disabled

boolean

Set disabled = false to allow GUEST

For example: curl -X PUT username:password@localhost:4985/db/_config -H "Content-Type: application/json" --data-binary '{"guest": {"disabled":false}}

revs_limit

integer

This property defines the maximum depth to which a document's revision tree can grow.

It value governs the point at which to prune a document's revision tree.

For more information see: Revisions page.

import_docs

boolean

Use the import_docs property to define whether the Sync Gateway node should automatically import Couchbase Server documents;

This property works in conjunction with the enable_shared_bucket_access property, which enables Xattrs.

Since Sync Gateway 2.7, all Sync Gateway nodes can be configured as import nodes. This results in performance benefits as the import process is shared across all Sync Gateway nodes.

Prior to version 2.7, import_docs can only be set to true on a single node.

Changes initiate a database restart

import_partitions

integer

Use the import_partitions property to define how many import partitions should be used for import sharding.

Partitions are distributed among all Sync Gateway nodes participating in import processing (import_docs:true), and each process a subset of the server's vbuckets.

Each partition is processed by a separate goroutine, so import_partitions can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node.

import_filter

string

The import_filter controls whether a document written to the Couchbase Server bucket should be made available to Couchbase Mobile clients (that is, whether it ought to be imported).

You should provision the filter as a Javascript function in the request body of a call to the Admin Rest API endpoint put {db}/_config/import_filter.

Set the header's content type to content-Type: application/javascript.

The function takes the document body as parameter and is expected to return a boolean to indicate whether the document should be imported.

If you do not provide a filter function then no filter will be applied and ALL documents will be imported.

import_backup_old_rev

string

Use the import_backup_old_rev property to define whether import should attempt to create a temporary backup of the previous revision body, when available

event_handlers

object

Webhooks in Sync Gateway are designed to minimize performance impacts on Sync Gateway's regular processing.

Sync Gateway manages the number of processes that are spawned for webhook event handling, so that slow response times from the HTTP POST operations don't consume available CPU resources on Sync Gateway nodes.

When a webhook event handler is defined, after Sync Gateway has updated a document, Sync Gateway adds a document_changed event to an asynchronous event-processing queue (the event queue).

New processes are then spawned to apply the filter function to the documents and to perform the HTTP POST operations.

When an event is not added to the event queue, but is instead discarded, a warning message is written to the the Sync Gateway log.

You can configure Sync Gateway to log information about event handling, by including either the log key Event or Events+ in the Log property in your Sync Gateway configuration file. Events+ is more verbose.

See also: Webhook..

event_handlers.db_state_changed

object

Use the db_state_changed property group to define the actions to perform when a db_state change is detected.

event_handlers.db_state_changed.filter

string

Use `db_state_changed.filter``` to define a JavaScript function that determines which state changes to post.

event_handlers.db_state_changed.handler

string

Specify the type of event handler.

This must be webhook currently).

event_handlers.db_state_changed.options

string

Options can be specified per-handler, and are specific to each handler type.

event_handlers.db_state_changed.timeout

integer

Defines the period in seconds to wait for a response to the operation. Default: 60

event_handlers.db_state_changed.url

string

Defines the URL to post to (for a webhook event handler).

event_handlers.max_processes

integer

Maximum number of events that can be processed concurrently, that is, no more than max_processes concurrent processes will be spawned for event handling.

The default value should work well in the majority of cases. You should not need to adjust it to tune performance. However, if you wish to ensure that most webhook posts are sent, you can set it to sufficiently high value.

event_handlers.wait_for_process

string

Maximum wait time in milliseconds before canceling event processing for an event that is detected when the event queue is full.

If you set the value to 0 (zero), then incoming events are discarded immediately if the event queue is full.

If you wish to avoid any blocking of standard Sync Gateway processing this may be a desirable value to use.

The default value should work well in the majority of cases. You should not need to adjust it to tune performance.

allow_empty_password

boolean

Use allow_empty_password to define whether to Sync Gateway users can be created with empty passwords.

cache

object

The cache group of properties define the configuration for this database's channel and revision caches

cache.rev_cache

object

Use the rev_cache properties to configure the revision cache

cache.rev_cache.size

integer

Size of the revision cache, specified as the total number of document revisions to cache in memory for all recently accessed documents.

When the revision cache is full, Sync Gateway removes less recent document revisions to make room for new document revisions. Adjust this property to tune memory consumption by Sync Gateway, for example on servers with less memory and in cases when Sync Gateway creates many new documents and/or updates many documents relative to the number of read operations.

Disabling the revision cache

Disabling the revision cache is an Enterprise Edition feature.

To disable the revision entirely, set this property to 0. Setting this property to 0 on the Community Edition is ignored.

Disabling the revision cache would be useful when there are very large documents or if you expect a very low cache hit rate. Otherwise it could negatively impact the latency of replications. It is generally not recommended to disable the revision cache, unless advised by Couchbase Enterprise Support.

cache.rev_cache.shard_count

integer

Tuning this property is an Enterprise Edition feature. The Community Edition is configured with the default value, and will ignore any value in the configuration file.

Number of shards the rev cache should be split into. More shards allows for lower cache contention when accessing distinct revisions, at the cost of some memory overhead per-shard. This generally should not greatly exceed the number of CPU threads available to Sync Gateway.

It is generally not recommended to set this property, unless advised by Couchbase Enterprise Support.

cache.channel_cache

object

Use the channel_cache group's properties to configure the database's channel cache

Changes initiate a database restart

cache.channel_cache.compact_high_watermark_pct

integer

Use compact_high_watermark_pct to define the trigger value for starting channel cache eviction. Specify the value as a percentage (of max_number)

When the cache size, determined by max_number, reaches the high watermark, the eviction process iterates through the cache, removing inactive channels.

cache.channel_cache.compact_low_watermark_pct

integer

Use compact_low_watermark_pct to define the trigger value for stopping channel cache eviction. Specify the value as a percentage (of max_number)

When the cache size, determined by max_number returns to a value lower than compact_low_watermark_pct, the cache eviction process is stopped.

cache.channel_cache.enable_star_channel

boolean

Use enable_star_channel to define whether Sync GAteway should use the all documents (*) channel - sometimes referred to as the 'star' channel.

cache.channel_cache.expiry_seconds

integer

Use expiry_seconds to define how long (in seconds) Sync Gateway should keep cached entries beyond the minimum retained.

cache.channel_cache.max_length

integer

Maximum number of entries maintained in cache per channel.

cache.channel_cache.max_num_pending

integer

Use max_num_pending to define the maximum number of pending sequences before skipping the sequence.

cache.channel_cache.max_number

integer

Use max_number to define the maximum number of channel caches allowed at any one point. This property is used alongside the associated eviction watermarks compact_low_watermark_pct and compact_high_watermark_pct to control the cache size.

The default value for this property is 50000. Assuming the default channel min_length and max_length values, this would result in a memory usage under 1GB.

Tuning this property is an Enterprise Edition feature - in the Community Edition any change to the default value is ignored.

Enterprise Edition Only: The max_number value can be tuned to optimize for cache hits (requests that are handled using the cache), as opposed to cache misses (requests that require a round-trip to Couchbase Server to fetch data). The cache hit/miss ratio can be obtained with the following:

cache hit/miss ratio = cache.chan_cache_hits / cache.chan_cache_misses

Increasing the max_number value can increase the cache hit/miss ratio, resulting in better cache utilization.

If the cache size grows to reach the high watermark (compact_high_watermark_pct), channels with no connected replications will be evicted before channels which are associated with an active pull replication (i.e a blip-based pull replication in Couchbase Lite 2.x, or an active /{db}/_changes request in Couchbase Lite 1.x).

The minimum allowed value is 100.

It isn't possible to remove the limit altogether, users who wish to remove the limit would need to set max_number to an arbitrarily high value.

cache.channel_cache.max_wait_pending

integer

Maximum wait time in milliseconds for a pending sequence before skipping sequences.

cache.channel_cache.max_wait_skipped

integer

Maximum wait time in milliseconds for a skipped sequence before abandoning the sequence.

cache.channel_cache.min_length

integer

Minimum number of entries maintained in cache per channel.

cache.channel_cache.query_limit

integer

Limit used for channel queries

offline

boolean

Use offline to determine whether Sync Gateway should start the database in offline mode.

The default of false means the database will be online.

unsupported

object

This group comprises an unrelated collection of unsupported properties that may, potentially, be useful in controlled testing scenarios.

NOTE: Due to the unsupported nature of these options, there is no guarantee on their continued availability.

unsupported.api_endpoints

object

unsupported.api_endpoints.enable_couchbase_bucket_flush

boolean

Determines whether Couchbase buckets can be flushed using the Admin REST API.

Use only for testing purposes if it is necessary to flush data in between tests to start with a clean DB.

unsupported.oidc_tls_skip_verify

boolean

Unsupported option for use in development and testing environment ONLY

oidc_tls_skip_verify can be used to enable the use of self-signed certs for OpenID Connection testing.

unsupported.oidc_test_provider

object

Config settings for OIDC test provider

unsupported.oidc_test_provider.enabled

boolean

Unsupported option for use in development and testing environment ONLY

Determines whether the oidc_test_provider endpoints should be exposed on the public API.

unsupported.remote_config_tls_skip_verify

boolean

Unsupported option for use in development and testing environment ONLY

Use only to enable self signed certificates for testing external JavaScript load.

unsupported.sgr_tls_skip_verify

boolean

Unsupported option for use in development and testing environment ONLY

sgr_tls_skip_verify can be used to skip validation of TLS certs used for Inter-Sync Gateway Replication.

unsupported.user_views

object

Configuration settings for user views

unsupported.user_views.user_views_enabled

boolean

Unsupported option for use in development and testing environment ONLY

Use to determine whether pass-through view query is supported through public API

unsupported.warning_thresholds

object

unsupported.warning_thresholds.access_and_role_grants_per_doc

boolean

Number of access and role grants per document to be used as a threshold for grant count warnings

unsupported.warning_thresholds.channels_per_doc

boolean

Number of channels per document to be used as a threshold for channel count warnings

unsupported.warning_thresholds.channels_per_user

boolean

Number of channels per user to be used as a threshold for channel count warnings

unsupported.warning_thresholds.channel_name_size

boolean

Number of channel name characters to be used as a threshold for channel name warnings

unsupported.warning_thresholds.xattr_size_bytes

boolean

Number of bytes to be used as a threshold for XATTR size limit warnings

unsupported.disable_clean_skipped_query

boolean

Clean skipped sequence processing bypasses final check

oidc

object

Use the oidc object properties to defined any OpenID Connect providers and associated credentials.

oidc.default_provider

string

Use this default_provider property to identify the provider to use for OIDC requests that do not specify a provider.

If only one provider is specified in the providers map, then that is used as the default provider. If multiple providers are defined and default_provider is not specified, requests to /db/_oidc must specify the provider parameter.

oidc.providers

object

Include an entry for each OIDC provider

oidc.providers.this_provider

object

oidc.providers.this_provider.issuer

string

The OpenID Connect Provider issuer.

oidc.providers.this_provider.register

string

Whether Sync Gateway should automatically create users for successfully authenticated users that don't have an already existing user in Sync Gateway.

Optional.

oidc.providers.this_provider.client_id

string

The client ID defined in the provider for Sync Gateway.

oidc.providers.this_provider.validation_key

string

Client secret associated with the client. Required for auth code flow.

oidc.providers.this_provider.callback_url

string

The callback URL to be invoked after the end-user obtains a client token. When not provided, Sync Gateway will generate it based on the incoming request.

Optional

oidc.providers.this_provider.disable_session

string

By default, Sync Gateway will create a new session for the user upon successful OIDC authentication, and set that session in the usual way on the _oidc_callback and _oidc_refresh responses.

If disable_session is set to true, the session is not created (clients must use the ID token for subsequent authentications).

Optional

oidc.providers.this_provider.scope

string

By default, Sync Gateway uses the scope "openid email" when calling the OP's authorize endpoint.

If the scope property is defined in the config (as an array of string values), it will override this scope.

Optional.

oidc.providers.this_provider.include_access

string

Optional. When true, the oidccallback response will include the access_token, expires_at and token_type properties returned by the OP.

oidc.providers.this_provider.user_prefix

string

Optional. Specifies the prefix for Sync Gateway usernames for the provider. When not specified, defaults to issuer.

oidc.providers.this_provider.discovery_url

string

Optional. Discovery URL used to obtain the OpenID Connect provider configuration. If not specified, the default discovery endpoint of [issuer]/.well-known/openid-configuration will be used.

oidc.providers.this_provider.disable_cfg_validation

boolean

Couchbase Sync Gateway, by default, applies strict validation of the OpenID Connect configuration based on the OIDC specification.

Set "disable_cfg_validation": true when you do not want strict validation of the OIDC configuration.

oidc.providers.this_provider.disable_callback_state

boolean

DisableCallbackState determines whether or not to maintain state between the /_oidc and /_oidc_callback endpoints.

Disabling this action is NOT recommended as it will increase vulnerability to Cross-Site Request Forgery (CSRF, XSRF).

Set "disable_callback_state": true to switch-off callback state.

oidc.providers.this_provider.username_claim

string

You can use username_claim to specify a claim other than subject to use as the Sync Gateway username.

The specified claim must be a string, as numeric claims may be un-marshalled inconsistently between Sync Gateway and the underlying OIDC library.

When authenticating incoming OIDC tokens, Sync Gateway currently treats the username as [userprefix][subject]. By default user_prefix is the issuer, but can be customized in the Sync Gateway provider config. Subject is always the sub claim in the token.

Behavior:

• If username_claim is set but user_prefix is not set, use that claim as the Sync Gateway username.

• If username_claim is set and user_prefix is also set, use [userprefix][username_claim] as the Sync Gateway username.

• If username_claim is not set and user_prefix is set, use [userprefix][subject] as the Sync Gateway username (existing behavior).

• If neither username_claim nor userprefix are set, use [issuer][subject] as the Sync Gateway username (existing behavior).

oidc.providers.this_provider.allow_unsigned_provider_tokens

boolean

Unsigned provider tokens are not accepted.

Set "allow_unsigned_provider_tokens": true to opt-in to accepting unsigned tokens from providers.

old_rev_expiry_seconds

integer

Use the old_rev_expiry_seconds property to define the number of seconds before old revisions are removed from Couchbase Server buckets.

view_query_timeout_secs

integer

Use the view_query_timeout_secs property to define the view query timeout in seconds.

This is the time Sync Gateway should wait for a view query response from Couchbase Server before it times out.

The timeout applies to both view and N1QL queries issued by Sync Gateway.

local_doc_expiry_secs

integer

Use the local_doc_expiry_secs property to define an expiry value for local documents managed on Sync Gateway.

Local documents are used by the Couchbase Lite replicator to track up to which sequence number a given client has synchronized and where it should resume the next time it connects to Sync Gateway.

Clients failing to replicate within the expiry window are forced to restart their replication from the beginning (sequence zero).

This property is intended to minimize accumulation of obsolete replication checkpoint documents in the Couchbase Server bucket.

The default is 7776000 seconds (90 days).

enable_shared_bucket_access

boolean

Use the enable_shared_bucket_access property to define whether to use extended attributes to store sync metadata. This is required to enable mobile-to-server data sync (mobile convergence).

You can learn more about this functionality in Syncing with Couchbase Server

This property works in conjunction with the import_docs property, which determines whether a node participates in import processing. Leave enable_shared_bucket_access true on all nodes participating in such a configuration.

On start-up, Sync Gateway will generate the mobile-specific metadata for all the pre-existing documents in the Couchbase Server bucket. From then on, documents can be inserted on the Server directly (with N1QL or SDKs) or through the Sync Gateway REST API.

Change initiates a database restart

session_cookie_secure

boolean

Override secure cookie flag (that is, disable secure cookies).

If SSLCert is set, then secure cookies are also used by default. However, this flag can be set false to override this behavior and allow insecure cookies to be used alongside SSL.

If SSLCert is not set then this flag defaults to false.

session_cookie_name

string

Starting in Sync Gateway 2.0, it is possible to customize the session cookie name that is used for this database.

This property is mostly used by web applications interacting with multiple Sync Gateway databases.

Browsers typically have two methods of determining which cookie to use for a given request: the URL path, or the cookie name.

Use this property, to set different cookie names for each database specified in the configuration file. Let's consider the following configuration file:

{
    "databases": {
      "db1": {
        "session_cookie_name": "CustomName1",
        "bucket": "bucket-1"
        },
        "db2": {
          "session_cookie_name": "CustomName2",
          "bucket": "bucket-2"
        }
      }
    }
}

With this configuration, the Set-Cookie response header of the POST :4984/{db}/_session endpoint (Public REST API) would then have the form "CustomName1=3cad4b95524179bf144fe0d92b8f09877bb86bf5;path=/db1/".

When using POST :4985/{db}/_session (Admin REST API) to create a session, the cookie value is returned in the response body instead of the Set-Cookie header. In this case, it could also be set by the client, for web applications it would be the following in JavaScript:

cookie1String = "CustomName1=3cad4b95524179bf144fe0d92b8f09877bb86bf5;path=/db1/";
document.cookie = cookie1String;

session_cookie_http_only

boolean

This flag disallows cookies from being used by Javascript; by default javascript CAN use them

allow_conflicts

boolean

Use allow_conflict to define whether Sync Gateway will handle conflicts.

The default of true indicates that conflicts are handled.

Set the value to false to cause Sync Gateway to reject any attempt to write conflicting revisions (returning a 409 HTTP status code). It will be up to the client to resolve the conflict.

Restarting Sync Gateway with this property enabled will not automatically result in disk space savings (compaction on a document won't occur until a document is updated).

Constraints:

• Push replications to pre-2.8 targets do not support the "allow_conflicts": false setting; the target must use "allow_conflicts": true.

Change initiates a database restart.

num_index_replicas

integer

use num_index_replicas property to define the number of index replicas used when creating the core Sync Gateway indexes.

Only applicable if databases.$db.use_views is set to false (default value).

Change initiates a database restart.

use_views

boolean

If set to true, Sync Gateway will use views instead of GSI for system functions like authentication and replication.

send_www_authenticate_header

boolean

Whether to send WWW-Authenticate header in 401 responses.

bucket_op_timeout_ms

integer

Use bucket_op_timeout_ms to define how long Sync Gateway will wait for a bucket operation to complete before timing out and trying again.

You may increase this value where there is a heavy load on Couchbase Server and operations are likely to take more than 2.5 seconds to complete.

The default value is 2500 milliseconds.

Changes initiate a database restart.

delta_sync

object

NOTE: Delta Sync is an Enterprise Edition feature on Sync Gateway and Couchbase Lite.

Use the delta_sync object to specify the delta sync configuration properties.

In this context, delta-sync, is the ability to replicate only those parts of a Couchbase mobile document that have changed. This results in significant savings in bandwidth consumption as well as throughput improvements; both useful benefits when network bandwidth is typically constrained.

Delta Sync does not apply to attachment contents.

Delta Sync is disabled by default on the Sync Gateway. You can enable it through the enabled property.

If delta sync is enabled on Sync Gateway, then Couchbase Lite clients will switch to using delta sync automatically. Similarly, if delta sync is disabled on Sync Gateway, clients will switch to normal mode.

Changes initiate a database reload

delta_sync.enabled

boolean

Use the delta_sync.enabled property to turn delta sync mode on or off for the given database.

The following configuration example enables delta sync.

{
  "databases": {
    "db": {
      "delta_sync": {
        "enabled": true,
        "rev_max_age_seconds": 86400
      }
    }
  }
}

Footnotes

• Use of Delta Sync incurs additional bucket storage requirements which can be tuned with the rev_max_age_seconds property.

• Delta Sync is automatically enabled for peer-to-peer sync between Couchbase Lite clients.

• Delta sync is disabled for Couchbase Lite database replicas.

• Push replications do not use Delta Sync when pushing to a pre-2.8 target.

delta_sync.rev_max_age_seconds

integer

Use delta_sync.rev_max_age_seconds to adjust the time box within which deltas can be generated.

On a write operation, the revision body is backed up in the bucket and retained for rev_max_age_seconds to calculate future revision deltas. As a result, new deltas can only be generated for read requests that come in within the rev_max_age_seconds time window. The storage of backed up revision bodies for delta sync incurs additional bucket storage requirements.

The additional storage can be calculated with the following formula: (doc_size * updates_per_day * 86400) / rev_max_age_seconds.

For example, with rev_max_age_seconds's default value, an average document size of 4 KB and 100 writes/day, enabling delta sync would take up an additional 400 KB of storage on Couchbase Server ((4 * 100 * 86400)/86400).

Setting this value to 0 will generate deltas opportunistically on pull replications, with no additional storage requirements.

compact_interval_days

number

Use `` property to define the interval between scheduled compaction runs (in days).

Set a zero (0) value to suppress running compactions.

Change initiates a database restart.

isgr_enabled

boolean

Use the isgr_enabled property to define whether this Sync Gateway node can be assigned inter-Sync Gateway replications for this database.

If set to false, the Sync Gateway node will not participate in inter-Sync Gateway replications.

isgr_websocket_heartbeat_secs

integer

If set, this duration (in seconds) is used as a custom heartbeat interval for websocket ping frames in inter-Sync Gateway replications.

serve_insecure_attachment_types

boolean

The sending of a content-disposition header for attachments with headers such as "text/html" forces a download, rather than browser rendering.

Use this option to suppress sending the content-disposition, allowing the browser to render the attachment.

query_pagination_limit

integer

Use the query_pagination_limit property to define the Query limit to be used during pagination of large queries.

Change initiates a database restart.

slow_query_warning_threshold

integer

The maximum wait time, in milliseconds,for N1QL or View queries made by Sync Gateway

Log warnings if the run time of a N1QL or View query, made by Sync Gateway, exceeds this value.

user_xattr_key

string

The user_xattr_key identifies the user xattr used to hold the channel access grants for documents in this database.

If it is not specified or its value is spaces or null then this feature is disabled (default).

If you change the value of this key, no existing grant assignments will be changed until a document mutation is triggered. This can be done in a number of ways:

• a mutation to the document which we'll see via DCP
• an on-demand import either through write or get
• by using the resync function.

Dependencies: The user_xattr_key feature requires that --

• enable_shared_bucket_access be = true

• xattrs be supported on the connected Couchbase Server

Change initiates a database restart

client_partition_window_secs

string

Use the client_partition_window_secs property to define how long clients can remain offline for without losing replication metadata.

Default 2 592 000 seconds (30 days)