A newer version of this documentation is available.

View Latest

Database Configuration

      +

      Using Sync Gateway’s Admin REST API to configure and manage databases

      Pre-3.0 Legacy Configuration Equivalents

      This content describes configuration for Sync Gateway 3.0 and higher — for legacy configuration, see: Legacy Pre-3.0 Configuration

      Introduction

      From Sync Gateway 3.0 you can use the Admin REST API to provision persistent configuration changes. This content introduces the Create Database and Configure Database endpoints for convenience — see Database Configuration for a full description of the endpoints available.

      You can define 1 custom scope per database with up to 1000 custom collections. If you don’t specify a custom scope and collection, any documents you create will be saved in the default scope and collection.

      Create Database

      PUT {url}/{dbname}/

      This is to create a new database for Sync Gateway.

      The new database name will be the name specified in the URL, not what is specified in the request body database configuration.

      If the bucket is not provided in the database configuration, Sync Gateway will attempt to find and use the database name as the bucket.

      By default, the new database will be brought online immediately. This can be avoided by including "offline": true in the configuration in the request body.

      Required Sync Gateway RBAC roles:

      • Sync Gateway Architect

      Parameters

      Path Parameters

      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      Body Parameter

      Name Description Schema

      Body
      optional

      The configuration to use for the new database

      DatabaseConfig

      Query Parameters

      Name Description Schema

      disable_oidc_validation
      optional

      If set, will not attempt to validate the configured OpenID Connect providers are reachable.

      Default: false

      Boolean

      Responses

      HTTP Code Description Schema

      201

      Database created successfully

      400

      There was a problem with your request

      HTTP_Error

      403

      An authentication failure occurred

      HTTP_Error

      409

      A database already exists for this bucket

      HTTP_Error

      412

      A database under that name already exists

      HTTP_Error

      500

      A server error occurred

      HTTP_Error

      Example

      Example 1. Create database

      Here we create a new sync gateway database.

      • Curl

      • HTTP

      curl --location --request PUT 'http://127.0.0.1:4985/traveldb/' \ (1)
      --header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \ (2)
      --header 'Content-Type: application/json' \
      --data-raw '{
      "bucket": "todo", (3)
      "num_index_replicas": 0}'
      PUT /traveldb/ HTTP/1.1 (1)
      Host: 127.0.0.1:4985
      Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk (2)
      Content-Type: application/json
      Content-Length: 44
      
      {
      "bucket": "todo", (3)
      "num_index_replicas": 0}
      1 Here we create a sync gateway database called traveldb
      2 Note we are using Basic Authentication here to authenticate against an existing Couchbase Server RBAC user
      3 Here we point to the Couchbase Server bucket called todo

      Configure Database

      PUT {url}/{db}/_config

      This is used to update the database configuration fields specified. Only the fields specified in the request will have their values replaced.

      The bucket and database name cannot be changed. If these need to be changed, the database will need to be deleted then recreated with the new settings.

      Required Sync Gateway RBAC roles:

      • Sync Gateway Architect
      • Sync Gateway Application

      Parameters

      Path Parameters

      Name Description Schema

      db
      required

      The name of the database to run the operation against.

      String

      Body Parameter

      Name Description Schema

      Body
      optional

      The database configuration fields to update

      DatabaseConfig

      Header Parameters

      Name Description Schema

      If-Match
      optional

      If set to a configuration's Etag value, enables optimistic concurrency control for the request. Returns HTTP 412 if another update happened underneath this one.

      String

      Responses

      HTTP Code Description Schema

      201

      Database configuration successfully updated

      400

      There was a problem with your request

      HTTP_Error

      404

      Not Found

      412

      Precondition Failed The supplied If-Match header did not match the current version of the configuration. Returned when optimistic concurrency control is used, and there has been an update to the configuration in between this update.

      HTTP_Error

      Example

      Example 2. Configure database

      Here we configure an existing sync gateway database.

      • Curl

      • HTTP

      curl --location --request PUT 'http://127.0.0.1:4985/traveldb/_config/' \ (1)
      --header 'Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk' \ (2)
      --header 'Content-Type: application/json' \
      --data-raw '{
        "enable_shared_bucket_access": true,
        "import_docs": true
      }' (3)
      PUT /traveldb/_config/ HTTP/1.1  (1)
      Host: 127.0.0.1:4985
      Authorization: Basic c3luY19nYXRld2F5OnBhc3N3b3Jk  (2)
      Content-Type: application/json
      Content-Length: 120
      
      {
      "enable_shared_bucket_access": true,
      "import_docs": true
      } (3)
      1 Here we choose to configure (_config) a sync gateway database called traveldb
      2 Note we are using Basic Authentication here to authenticate against an existing Couchbase Server RBAC user
      3 Here we toggle a couple of database properties

      Schema

      This section shows Sync Gateway’s database configuration settings in schema format for convenience in constructing JSON models for use in the Admin REST API.

      The configuration settings described here are provisioned through the Database Configuration endpoints.

      {
         allow_empty_password: false,
         bucket: "The database name",
         bucket_op_timeout_ms: 0,
         cacertpath: "string",
         cache: {
            channel_cache: {
               compact_high_watermark_pct: 80,
               compact_low_watermark_pct: 60,
               enable_star_channel: true,
               expiry_seconds: 60,
               max_length: 500,
               max_num_pending: 10000,
               max_number: 50000,
               max_wait_pending: 5000,
               max_wait_skipped: 3600000,
               min_length: 50
            },
            rev_cache: {
               shard_count: "16",
               size: "5000"
            }
         },
         certpath: "string",
         client_partition_window_secs: 2592000,
         compact_interval_days: 1,
         cors: {
            headers: [],
            login_origin: [],
            origin: []
         },
         delta_sync: {
            enabled: false,
            rev_max_age_seconds: 86400
         },
         disable_password_auth: false,
         enable_shared_bucket_access: true,
         event_handlers: {
            db_state_changed: {
               filter: "string",
               handler: "string",
               options: {
                  {additionalProperties...}: {
      
                  }
               },
               timeout: 0,
               url: "string"
            },
            document_changed: {
               filter: "string",
               handler: "string",
               options: {
                  {additionalProperties...}: {
      
                  }
               },
               timeout: 0,
               url: "string"
            },
            max_processes: "string",
            wait_for_process: "string"
         },
         guest: {
            admin_channels: [],
            admin_roles: [],
            all_channels: [],
            collection_access: {
               {scopename...}: {
                  {collectionname...}: {
                     admin_channels: [],
                     all_channels: [],
                     jwt_channels: [],
                     jwt_last_updated: "string"
                  }
               }
            },
            disabled: true,
            email: "string",
            jwt_channels: [],
            jwt_issuer: "string",
            jwt_last_updated: "string",
            jwt_roles: [],
            name: "string",
            password: "string",
            roles: []
         },
         import_backup_old_rev: false,
         import_docs: true,
         import_filter: "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
         import_partitions: 16,
         javascript_timeout_secs: 60,
         keypath: "string",
         kv_tls_port: 11207,
         local_doc_expiry_secs: 7776000,
         local_jwt: {
            {providername...}: {
               algorithms: [],
               channels_claim: "string",
               client_id: "string",
               disable_session: true,
               issuer: "string",
               keys: [],
               register: true,
               roles_claim: "string",
               user_prefix: "string",
               username_claim: "string"
            }
         },
         logging: {
            console: {
               log_keys: [CRUD,HTTP,Query],
               log_level: "debug"
            }
         },
         max_concurrent_query_ops: 1000,
         name: "string",
         num_index_replicas: 1,
         offline: false,
         oidc: {
            default_provider: "string",
            providers: {
               {providername...}: {
                  InsecureSkipVerify: false,
                  IsDefault: true,
                  Name: "string",
                  allow_unsigned_provider_tokens: true,
                  callback_url: "string",
                  channels_claim: "string",
                  client_id: "string",
                  disable_callback_state: false,
                  disable_cfg_validation: false,
                  disable_session: true,
                  discovery_url: "string",
                  include_access: true,
                  issuer: "string",
                  register: true,
                  roles_claim: "string",
                  scope: [],
                  user_prefix: "string",
                  username_claim: "string",
                  validation_key: "string"
               }
            }
         },
         old_rev_expiry_seconds: 300,
         password: "string",
         query_pagination_limit: 5000,
         replications: {
            replication_id: {
               adhoc: false,
               batch_size: 200,
               collections_enabled: false,
               collections_local: [scope1.collection1,scope1.collection3,scope1.collection6],
               collections_remote: [scope1.collectionA,,scope1.collectionF],
               conflict_resolution_type: "default",
               continuous: false,
               custom_conflict_resolver: "none",
               direction: "string",
               enable_delta_sync: false,
               filter: "string",
               initial_state: "running",
               max_backoff_time: 5,
               purge_on_removal: false,
               query_params: [],
               remote: "string",
               remote_password: "string",
               remote_username: "string",
               replication_id: "string",
               run_as: "string"
            }
         },
         revs_limit: 100,
         roles: (unknown),
         scopes: {
            {scopename...}: {
               collections: {
                  {collectionname...}: {
                     import_filter: "function(doc) { if (doc.type != 'mobile') { return false; } return true; }",
                     sync: "function(doc){channel("collection name");}"
                  }
               }
            }
         },
         send_www_authenticate_header: true,
         serve_insecure_attachment_types: false,
         server: "string",
         session_cookie_http_only: false,
         session_cookie_name: "string",
         session_cookie_secure: true,
         sgreplicate_enabled: true,
         sgreplicate_websocket_heartbeat_secs: 300,
         slow_query_warning_threshold: 500,
         suspendable: false,
         sync: "function(doc){channel(doc.channels);}",
         unsupported: {
            api_endpoints: {
               enable_couchbase_bucket_flush: true
            },
            dcp_read_buffer: 0,
            force_api_forbidden_errors: true,
            guest_read_only: true,
            kv_buffer: 0,
            oidc_test_provider: {
               enabled: true
            },
            oidc_tls_skip_verify: true,
            remote_config_tls_skip_verify: true,
            sgr_tls_skip_verify: true,
            user_views: {
               enabled: true
            },
            warning_thresholds: {
               access_and_role_grants_per_doc: 0,
               channel_name_size: 0,
               channels_per_doc: 0,
               channels_per_user: 0,
               xattr_size_bytes: 0
            }
         },
         use_views: false,
         user_xattr_key: "string",
         username: "string",
         users: (unknown),
         view_query_timeout_secs: 75
      }
      

      allow_empty_password

      Type

      boolean

      Description

      This controls whether users that are created can have an empty password or not.

      bucket

      Type

      string

      Description

      The Couchbase Server backing bucket for the database.

      bucket_op_timeout_ms

      Type

      number

      Description

      This is the amount of milliseconds should pass before a bucket operation times out. An error will be returned if the bucket operation times out saying: operation timed out.

      cacertpath

      Type

      string

      Description

      The root CA cert path for X.509 bucket authentication.

      cache.channel_cache

      Type

      object

      Description

      The channel cache config settings.

      cache.channel_cache.compact_high_watermark_pct

      Type

      integer

      Description

      The trigger value for starting the channel cache eviction process.

      Specify this as a percentage which will be the percentage used on `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

      Type

      integer

      Description

      The trigger value for stopping the channel cache eviction process.

      Specify this as a percentage which will be the percentage used on `max_number).

      When the cache size, determined by max_number returns to a value lower than the percentage of it set here, the cache eviction process is stopped.

      cache.channel_cache.enable_star_channel

      Type

      boolean

      Description

      Used to control whether Sync Gateway should use the all documents (*) channel.

      cache.channel_cache.expiry_seconds

      Type

      integer

      Description

      The amount of time (in seconds) to keep entries in the cache beyond the minimum retained.

      cache.channel_cache.max_length

      Type

      integer

      Description

      The maximum number of entries to maintain in the cache per channel.

      cache.channel_cache.max_num_pending

      Type

      integer

      Description

      The maximum number of pending sequences before skipping sequences.

      cache.channel_cache.max_number

      Type

      integer

      Description

      The maximum number of channel caches which can exist at any one point.

      cache.channel_cache.max_wait_pending

      Type

      number

      Description

      The maximum time (in milliseconds) for waiting for a pending sequence before skipping it.

      cache.channel_cache.max_wait_skipped

      Type

      number

      Description

      The maximum amount of time (in milliseconds) to wait for a skipped sequence before abandoning it.

      cache.channel_cache.min_length

      Type

      integer

      Description

      The minimum number of entries to maintain in the cache per channel.

      cache.rev_cache

      Type

      object

      Description

      The revision cache config settings.

      cache.rev_cache.shard_count

      Type

      string

      Description

      The number of shards the revision cache should be split into.

      cache.rev_cache.size

      Type

      string

      Description

      The maximum number of revisions that can be stored in the revision cache.

      certpath

      Type

      string

      Description

      The cert path (public key) for X.509 bucket auth.

      client_partition_window_secs

      Type

      integer

      Description

      How long (in seconds) clients can remain offline for without losing replication metadata.

      Defaults to 30 days (in seconds)

      compact_interval_days

      Type

      number

      Description

      The interval between scheduled tombstone compaction runs (in days). This can be a floating point number.

      If set to 0, compaction will not run automatically.

      cors

      Type

      object

      Description

      CORS configuration for this database; if present, overrides server's config.

      cors.headers

      Type

      array

      Description

      List of allowed headers

      cors.login_origin

      Type

      array

      Description

      List of allowed login origins

      cors.origin

      Type

      array

      Description

      List of allowed origins, use ['*'] to allow access from everywhere

      delta_sync

      Type

      object

      Description

      Delta sync configuration settings.

      This is an enterprise-edition feature only

      delta_sync.enabled

      Type

      boolean

      Description

      Whether delta sync is enabled.

      This is an enterprise-edition feature only

      delta_sync.rev_max_age_seconds

      Type

      number

      Description

      The number of seconds deltas for old revisions are available for.

      This defaults to 24 hours (in seconds).

      disable_password_auth

      Type

      boolean

      Description

      Whether to disable username/password authentication and only allow OIDC and guest access.

      enable_shared_bucket_access

      Type

      boolean

      Description

      Whether to use extended attributes to store Sync Gateway document (_sync) metadata.

      event_handlers

      Type

      object

      Description

      These are the settings for webhooks.

      event_handlers.db_state_changed.filter

      Type

      string

      Description

      The Javascript function to use to filter the webhook events.

      event_handlers.db_state_changed.handler

      Type

      string

      Description

      The handler type.

      event_handlers.db_state_changed.options

      Type

      object

      Description

      The options for the event.

      event_handlers.db_state_changed.options.{additionalProperties…​}

      Type

      object

      Description

      The option key and value.

      event_handlers.db_state_changed.timeout

      Type

      number

      Description

      The amount of time (in seconds) to attempt connect to the webhook before giving up.

      event_handlers.db_state_changed.url

      Type

      string

      Description

      The URL of the webhook.

      event_handlers.document_changed.filter

      Type

      string

      Description

      The Javascript function to use to filter the webhook events.

      event_handlers.document_changed.handler

      Type

      string

      Description

      The handler type.

      event_handlers.document_changed.options

      Type

      object

      Description

      The options for the event.

      event_handlers.document_changed.options.{additionalProperties…​}

      Type

      object

      Description

      The option key and value.

      event_handlers.document_changed.timeout

      Type

      number

      Description

      The amount of time (in seconds) to attempt connect to the webhook before giving up.

      event_handlers.document_changed.url

      Type

      string

      Description

      The URL of the webhook.

      event_handlers.max_processes

      Type

      string

      Description

      The maximum amount of concurrent event handling independent functions that can be running at the same time.

      event_handlers.wait_for_process

      Type

      string

      Description

      The maximum amount of time (in milliseconds) to wait when the even queue is full.

      guest

      Type

      object

      Description

      Properties associated with a user

      guest.admin_channels

      Type

      array

      Description

      A list of channels to explicitly grant to the user for the default collection.

      guest.admin_roles

      Type

      array

      Description

      A list of roles to explicitly grant to the user.

      guest.all_channels

      Type

      array (readOnly)

      Description

      All the channels that the user has been granted access to for the default collection.

      Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

      guest.collection_access

      Type

      object

      Description

      A set of access grants by scope and collection.

      guest.collection_access.{scopename…​}

      Type

      object

      Description

      An object keyed by scope, containing a set of collections.

      guest.collection_access.{scopename…​}.{collectionname…​}

      Type

      object

      Description

      An object keyed by collection name, defines access for the collection.

      guest.collection_access.{scopename…​}.{collectionname…​}.admin_channels

      Type

      array

      Description

      A list of channels to explicitly grant to the user.

      guest.collection_access.{scopename…​}.{collectionname…​}.all_channels

      Type

      array (readOnly)

      Description

      All the channels that the user has been granted access to.

      Access could have been granted through the sync function, roles, or explicitly on the user under the admin_channels property.

      guest.collection_access.{scopename…​}.{collectionname…​}.jwt_channels

      Type

      array (readOnly)

      Description

      The channels that the user has been granted access to through channels_claim.

      guest.collection_access.{scopename…​}.{collectionname…​}.jwt_last_updated

      Type

      string (readOnly)

      Description

      The last time that the user's JWT roles/channels were updated.

      guest.disabled

      Type

      boolean

      Description

      If true, the user will not be able to login to the account as it is disabled.

      guest.email

      Type

      string

      Description

      The email address of the user.

      guest.jwt_channels

      Type

      array (readOnly)

      Description

      The channels that the user has been granted access to through channels_claim.

      guest.jwt_issuer

      Type

      string (readOnly)

      Description

      The issuer of the last JSON Web Token that the user last used to sign in.

      guest.jwt_last_updated

      Type

      string (readOnly)

      Description

      The last time that the user's JWT roles/channels were updated.

      guest.jwt_roles

      Type

      array (readOnly)

      Description

      The roles that the user has been added to through roles_claim.

      guest.name

      Type

      string

      Description

      The name of the user.

      User names can only have alphanumeric ASCII characters and underscores.

      guest.password

      Type

      string

      Description

      The password of the user.

      Mandatory. unless allow_empty_password is true in the database configs.

      guest.roles

      Type

      array (readOnly)

      Description

      All the roles that the user has been granted access to.

      Access could have been granted through the sync function, roles_claim, or explicitly on the user under the admin_roles property.

      import_backup_old_rev

      Type

      boolean

      Description

      This controls whether import should attempt to create a temporary backup of the previous revision body (if available) when the document is modified in the bucket.

      import_docs

      Type

      boolean

      Description

      If true, documents will be imported in to Sync Gateway from the bucket when requested. Documents will be ran through the set import_filter if any is set.

      The default value depends on the edition of Sync Gateway being used. If the edition is the community-edition, then this will default to false or else in the enterprise-edition, it will default to true.

      This can also be set to the string continuous which maps to true.

      import_filter

      Type

      string

      Description

      This is the function that all imported documents in the default scope and collection are ran through in order to filter out what to import and what not to import. This allows you to control what is made available to Couchbase Mobile clients. If it is not set, then no documents are filtered when imported.

      import_docs must be true to make this field applicable.

      If scopes parameter is set, this is ignored.

      import_partitions

      Type

      number

      Description

      ** This is an enterprise-edition feature only**

      This is 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 an independent function that runs simultaneously to others, so import_partitions can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node.

      javascript_timeout_secs

      Type

      number

      Description

      The maximum number of seconds the sync, import filter, and custom conflict resolver JavaScript functions are allowed to run for before timing out. Set to 0 to allow the JS functions to run uncapped.

      keypath

      Type

      string

      Description

      The key path (private key) for X.509 bucket auth

      kv_tls_port

      Type

      integer

      Description

      The Memcached TLS port.

      local_doc_expiry_secs

      Type

      integer

      Description

      The number of seconds before a _local document should expire.

      local_jwt

      Type

      object

      Description

      Configuration for Local JWT authentication.

      local_jwt.{providername…​}

      Type

      object

      Description

      The providers name.

      local_jwt.{providername…​}.algorithms

      Type

      array

      Description

      The JWT signing algorithms to accept for authentication.

      local_jwt.{providername…​}.channels_claim

      Type

      string

      Description

      If set, the value(s) of the given JSON Web Token claim will be added to the user's channels.

      The value of this claim must be either a string or an array of strings, any other type will result in an error.

      local_jwt.{providername…​}.client_id

      Type

      string

      Description

      The value to match against the "aud" claim of JWTs. Set to an empty string to disable audience validation.

      local_jwt.{providername…​}.disable_session

      Type

      boolean

      Description

      Disable Sync Gateway session creation on successful JWT authentication.

      local_jwt.{providername…​}.issuer

      Type

      string

      Description

      The value to match against the "iss" claim of JWTs.

      local_jwt.{providername…​}.keys

      Type

      array

      Description

      The JSON Web Keys to use to validate JWTs.

      local_jwt.{providername…​}.register

      Type

      boolean

      Description

      If to register a new Sync Gateway user account when a user logs in with a JWT.

      local_jwt.{providername…​}.roles_claim

      Type

      string

      Description

      If set, the value(s) of the given JSON Web Token claim will be added to the user's roles.

      The value of this claim must be either a string or an array of strings, any other type will result in an error.

      local_jwt.{providername…​}.user_prefix

      Type

      string

      Description

      This is the username prefix for all users created through this provider.

      local_jwt.{providername…​}.username_claim

      Type

      string

      Description

      Allows a different OpenID Connect field to be specified instead of the Subject (sub).

      The field name to use can be specified here.

      logging

      Type

      object

      Description

      Per-database logging configuration.

      logging.console

      Type

      object

      Description

      Console logging configuration.

      logging.console.log_keys

      Type

      array

      Description

      Log Keys for the console output

      logging.console.log_level

      Type

      string

      Description

      Log Level for the console output

      max_concurrent_query_ops

      Type

      integer

      Description

      The maximum amount of query operations that can be running at any one point.

      name

      Type

      string

      Description

      The name of the database.

      num_index_replicas

      Type

      number

      Description

      This is the number of Global Secondary Indexes (GSI) to use for core indexes.

      offline

      Type

      boolean

      Description

      Start the database in an offline state.

      oidc

      Type

      object

      Description

      Configuration for OpenID Connect authentication.

      oidc.default_provider

      Type

      string

      Description

      The default provider to use when the provider is not specified in the client.

      oidc.providers

      Type

      object

      Description

      List of OpenID Connect issuers.

      oidc.providers.{providername…​}

      Type

      object

      Description

      The providers name.

      oidc.providers.{providername…​}.InsecureSkipVerify

      Type

      boolean

      Description

      Determines whether the TLS certificate verification should be disabled for this provider.

      oidc.providers.{providername…​}.IsDefault

      Type

      boolean

      Description

      Indicates if this is the default OpenID Connect provider.

      oidc.providers.{providername…​}.Name

      Type

      string

      Description

      The name of the OpenID Connect Provider.

      oidc.providers.{providername…​}.allow_unsigned_provider_tokens

      Type

      boolean

      Description

      Allows users accept unsigned tokens from providers.

      oidc.providers.{providername…​}.callback_url

      Type

      string

      Description

      The URL that the OpenID Connect will redirect to after authentication.

      If not provided, a callback URL will be generated.

      oidc.providers.{providername…​}.channels_claim

      Type

      string

      Description

      If set, the value(s) of the given OpenID Connect authentication token claim will be added to the user's channels.

      The value of this claim must be either a string or an array of strings, any other type will result in an error.

      oidc.providers.{providername…​}.client_id

      Type

      string

      Description

      The OpenID Connect provider client ID.

      oidc.providers.{providername…​}.disable_callback_state

      Type

      boolean

      Description

      Controls whether to maintain state between the auth request and callback endpoints (/_oidc and /_oidc_callback).

      This is not recommended as it would cause OpenID Connect authentication to be vulnerable to Cross-Site Request Forgery (CSRF, XSRF).

      oidc.providers.{providername…​}.disable_cfg_validation

      Type

      boolean

      Description

      This bypasses the configuration validation based on the OpenID Connect specifications. This may be required for some OpenID providers that don't strictly adhere to the specifications.

      oidc.providers.{providername…​}.disable_session

      Type

      boolean

      Description

      Disable Sync Gateway session creation on successful OpenID Connect authentication.

      oidc.providers.{providername…​}.discovery_url

      Type

      string

      Description

      The non-standard discovery endpoint.

      oidc.providers.{providername…​}.include_access

      Type

      boolean

      Description

      This is whether the _oidc_callback response should include the OpenID Connect access token and associated fields (such as token_type, and expires_in).

      oidc.providers.{providername…​}.issuer

      Type

      string

      Description

      The URL for the OpenID Connect issuer.

      oidc.providers.{providername…​}.register

      Type

      boolean

      Description

      If to register a new Sync Gateway user account when a user logs in with OpenID Connect.

      oidc.providers.{providername…​}.roles_claim

      Type

      string

      Description

      If set, the value(s) of the given OpenID Connect authentication token claim will be added to the user's roles.

      The value of this claim must be either a string or an array of strings, any other type will result in an error.

      oidc.providers.{providername…​}.scope

      Type

      array

      Description

      The scope sent for the OpenID Connect request.

      oidc.providers.{providername…​}.user_prefix

      Type

      string

      Description

      This is the username prefix for all users created through this provider.

      oidc.providers.{providername…​}.username_claim

      Type

      string

      Description

      Allows a different OpenID Connect field to be specified instead of the Subject (sub).

      The field name to use can be specified here.

      oidc.providers.{providername…​}.validation_key

      Type

      string

      Description

      The OpenID Connect provider client secret.

      old_rev_expiry_seconds

      Type

      number

      Description

      The number of seconds before old revisions are removed from the Couchbase Server bucket.

      password

      Type

      string

      Description

      The password for authenticating to the server.

      query_pagination_limit

      Type

      integer

      Description

      The query limit to be used during pagination of large queries.

      replications.replication_id

      Type

      object

      Description

      Properties of a replication

      replications.replication_id.adhoc

      Type

      boolean

      Description

      Set to true to run the replication as an adhoc replication instead of a persistent one.

      This means that the replication will only last the period of the replication until the status is changed to stopped and then it will be removed automatically. It will also be removed if Sync Gateway restarts or if removed due to user action.

      replications.replication_id.batch_size

      Type

      integer

      Description

      The amount of changes to be sent in one batch of replications. Changing this is an enterprise-edition only feature.

      replications.replication_id.collections_enabled

      Type

      boolean

      Description

      If true, the replicator will run with collections, and will replicate all collections, unless otherwise limited by keyspace_map.

      If false, the replicator will only replicate the default collection.

      replications.replication_id.collections_local

      Type

      array

      Description

      Limits the set of collections replicated to those listed in this array.

      The replication will use all collections defined on the database if this list is empty.

      replications.replication_id.collections_remote

      Type

      array

      Description

      Remaps the local collection name to the one specified in this array when replicating with the remote.

      If only a subset of collections need remapping, elements in this array can be specified as null to preserve the local collection name.

      The same index is used for both collections_remote and collections_local, and both arrays must be the same length.

      replications.replication_id.conflict_resolution_type

      Type

      string

      Description

      This defines what conflict resolution policy Sync Gateway should use to apply when resolving conflicting revisions.

      Changing this is an enterprise-edition only feature.

      Behaviour

      • default - In priority order, this will cause
        • Deletes to always win (the delete with the longest revision history wins if both revisions are deletes)
        • The revision with the longest revision history to win. This means the the revision with the most changes and therefore the highest revision ID will win.
      • localWins - This will result in local revisions always being the winner in any conflict.
      • remoteWins - This will result in remote revisions always being the winner in any conflict.
      • custom - This will result in conflicts going through your own custom conflict resolver. You must provide this logic as a Javascript function in the custom_conflict_resolver parameter. This is an enterprise-edition only feature.

      Note: replications created prior to Sync Gateway 2.8 will default to default.

      replications.replication_id.continuous

      Type

      boolean

      Description

      If true, changes will be immediately synced when they happen. This is known as a continuous replication.

      If false, all changes will be synced until they have been processed. The replication will then cease and not process any future changes (unless started again by the user). This is known as a one-shot replication.

      replications.replication_id.custom_conflict_resolver

      Type

      string

      Description

      This specifies the Javascript function to use to resolve conflicts between conflicting revisions.

      This must be used when conflict_resolution_type=custom. This property will be ignored when conflict_resolution_type is not custom.

      The Javascript function to provide this property should be in backticks (like the sync function). The function takes 1 parameter which is a struct that represents the conflict. This struct has 2 properties:

      • LocalDocument - The local document. This contains the document ID under the _id key.
      • RemoteDocument - The remote document The function should return the new documents body. This can be the winning revision (for example, return conflict.LocalDocument), a new body, or nil to resolve as a delete.

      Example:

      "custom_conflict_resolver":\`
      	function(conflict) {
      		console.log("Doc ID: "+conflict.LocalDocument._id);
      		console.log("Full remote doc: "+JSON.stringify(conflict.RemoteDocument));
      		return conflict.RemoteDocument;
      	}
      \`
      

      Using complex custom_conflict_resolver functions can noticeably degrade performance. Use a built-in resolver whenever possible.

      This is an enterprise-edition only feature.

      replications.replication_id.direction

      Type

      string

      Description

      This specifies which direction the replication will be replicating with the remote replicator.

      The directions are:

      • pull - changes are pulled from the remote database
      • push - changes are pushed to the remote database
      • pushAndPull - changes are both push-to and pulled-from the remote database

      Replications created prior to Sync Gateway 2.8 derive their direction from the source/target URL of the replication.

      replications.replication_id.enable_delta_sync

      Type

      boolean

      Description

      This will turn on delta- sync for the replication. This works in conjunction with the database level setting delta_sync.enabled

      If set to true, delta-sync will be used as long as both databases involved in the replication have delta-sync enabled. If a database does not have delta-sync enabled, then the replication will run without delta-sync.

      Replications created prior to Sync Gateway 2.8 must have delta-sync disabled.

      Enabling this is an enterprise-edition only feature.

      replications.replication_id.filter

      Type

      string

      Description

      This defines whether to filter documents by their channels or not.

      If set to sync_gateway/bychannel then a pull replication will be limited to a specific set of channels specified by the query_params.channels property.

      This only can be used with pull replications.

      replications.replication_id.initial_state

      Type

      string

      Description

      This is what state to start the replication in when creating a new replication.

      This allows you to control if the replication starts in a stopped start or running state.

      Replications prior to Sync Gateway 2.8 will run in the default state running.

      replications.replication_id.max_backoff_time

      Type

      integer

      Description

      Specifies the maximum time-period (in minutes) that Sync Gateway will attempt to reconnect to a lost or unreachable remote.

      When a disconnection happens, Sync Gateway will do an exponential backoff up to this specified value. When this value is met, it will attempt to reconnect indefinitely every max_backoff_time minutes.

      If this is set to 0, Sync Gateway will do the normal exponential backoff after the disconnect happens but then attempting 10 minutes and stop the replication.

      Note: this defaults to 5 minutes for replications created prior to Sync Gateway 2.8.

      replications.replication_id.purge_on_removal

      Type

      boolean

      Description

      Specifies whether to purge a document if the remote user loses access to all of the channels on the document when attempting to pull it from the remote.

      If false, documents will not be replicated and not be purged when the user loses access.

      replications.replication_id.query_params

      Type

      array

      Description

      This is a set of key/value pairs used in the query string of the replication.

      If filters=sync_gateway/bychannel then this can be used to set the channels to filter by in a pull replication. To do this, set the channels key to a string array of the channels to filter by. For example:

      "filter":"sync_gateway/bychannel",
      "query_params": {
        "channels":["chanUser1"]
      },
      

      replications.replication_id.remote

      Type

      string

      Description

      This is the endpoint of the database for the remote Sync Gateway that is the subject of this replication's push, pull, or pushAndPull action.

      Typically this would include the URI, port, and database name. For example, http://localhost:4985/db.

      How this remote is used depends on the direction of the replication:

      • pull - this replicator pulls changes from the remote
      • push - this replicator pushes changes to this remote
      • pushAndPull - this replicator pushes changes to this remote, while also pulling receiving changes

      replications.replication_id.remote_password

      Type

      string

      Description

      The password to use to authenticate with the remote.

      This password will be redacted in the replication config.

      This can only be used for a pull replication.

      replications.replication_id.remote_username

      Type

      string

      Description

      The username to use to authenticate with the remote.

      This can only be used for a pull replication.

      replications.replication_id.replication_id

      Type

      string

      Description

      This is the ID of the replication.

      When creating a new replication using a POST request, this will be set to a random UUID if not explicitly set.

      When the replication ID is specified in the URL, this must be set to the same replication ID if specifying it at all.

      replications.replication_id.run_as

      Type

      string

      Description

      This is used if you want to specify a user to run the replication as. This means that the replication will only be able to replicate what the user access to what the user has access to.

      revs_limit

      Type

      number

      Description

      The maximum depth a document's revision tree can grow too.

      The minimum is 20 if conflicts are allowed and 0 if not. It is not recommended to go below 100 when conflicts are allowed.

      scopes

      Type

      object

      Description

      An object keyed by scope name containing config for the specific collection.

      scopes.{scopename…​}

      Type

      object

      Description

      Scope-specific configuration.

      scopes.{scopename…​}.collections

      Type

      object

      Description

      An object keyed by collection name containing config for the specific collection.

      scopes.{scopename…​}.collections.{collectionname…​}

      Type

      object

      Description

      Collection-specific configuration.

      scopes.{scopename…​}.collections.{collectionname…​}.import_filter

      Type

      string

      Description

      This is the function that all imported documents in this collection are ran through in order to filter out what to import and what not to import. This allows you to control what is made available to Couchbase Mobile clients. If it is not set, then no documents are filtered when imported.

      import_docs in the database config must be true to make this field applicable.

      scopes.{scopename…​}.collections.{collectionname…​}.sync

      Type

      string

      Description

      The Javascript function that newly created documents in this collection are ran through.

      send_www_authenticate_header

      Type

      boolean

      Description

      Controls whether to send a WWW-Authenticate header in 401 Unauthorized HTTP responses.

      serve_insecure_attachment_types

      Type

      boolean

      Description

      If set, always serve attachments with the Content-Type header set to the type of the attachment.

      When serving an attachment, usually the Content-Type header is set to the type of the attachment but the Content-Disposition response header will be set instead if the content type is vulnerable to a phishing attack, causing the browser to download the file instead of display it. This option will override that behaviour and always set the Content-Type header.

      server

      Type

      string

      Description

      This is the Couchbase Server address or addresses that the database connect to.

      Type

      boolean

      Description

      Make all session cookies for the database set the HttpOnly flag so they are inaccessible to JavaScript.

      Type

      string

      Description

      This can be used to define a custom per-database session cookie name.

      Type

      boolean

      Description

      Override the session cookie secure flag. If set, the cookie will have the secure flag.

      This will default to true if startup config api.https.tls_cert_path is set otherwise it will default to false.

      sgreplicate_enabled

      Type

      boolean

      Description

      Whether the node should accept assign replications (true) or not (false).

      sgreplicate_websocket_heartbeat_secs

      Type

      integer

      Description

      Use a custom heartbeat interval (in seconds) for websocket ping frames.

      slow_query_warning_threshold

      Type

      number

      Description

      The amount of milliseconds a N1QL query should run before logging a warning.

      suspendable

      Type

      boolean

      Description

      Set to true to allow the database to be suspended.

      Defaults to true when running in serverless mode otherwise defaults to false.

      sync

      Type

      string

      Description

      The Javascript function that newly created documents are ran through for the default scope and collection. If scopes parameter is set, this is ignored.

      unsupported

      Type

      object

      Description

      These are unsupported options and therefore it is not recommended to use them.

      unsupported.api_endpoints.enable_couchbase_bucket_flush

      Type

      boolean

      Description

      Setting for test purposes only

      Whether Couchbase buckets can be flushed via Admin REST API.

      unsupported.dcp_read_buffer

      Type

      number

      Description

      Set the dcp feed to use a different read buffer size.

      unsupported.force_api_forbidden_errors

      Type

      boolean

      Description

      Force REST API errors to return forbidden

      unsupported.guest_read_only

      Type

      boolean

      Description

      Restrict GUEST document access to read-only.

      unsupported.kv_buffer

      Type

      number

      Description

      Set the kv pool to use a different buffer size.

      unsupported.oidc_test_provider.enabled

      Type

      boolean

      Description

      Whether the oidc_test_provider endpoints should be exposed on the public API.

      unsupported.oidc_tls_skip_verify

      Type

      boolean

      Description

      Enable self-signed certificates for OIDC testing.

      unsupported.remote_config_tls_skip_verify

      Type

      boolean

      Description

      Enable self-signed certificates for external JavaScript load.

      unsupported.sgr_tls_skip_verify

      Type

      boolean

      Description

      Enable self-signed certificates for SG-replicate testing.

      unsupported.user_views.enabled

      Type

      boolean

      Description

      Whether pass-through view query is supported through public API.

      unsupported.warning_thresholds.access_and_role_grants_per_doc

      Type

      number

      Description

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

      unsupported.warning_thresholds.channel_name_size

      Type

      number

      Description

      The number of channel name characters to be used as a threshold for channel name warnings.

      unsupported.warning_thresholds.channels_per_doc

      Type

      number

      Description

      The number of channels per document to be used as a threshold for the channel count warnings.

      unsupported.warning_thresholds.channels_per_user

      Type

      number

      Description

      The number of channels per user to be used as a threshold for channel count warnings.

      unsupported.warning_thresholds.xattr_size_bytes

      Type

      number

      Description

      The number of bytes to be used as a threshold for xattr size limit warnings.

      use_views

      Type

      boolean

      Description

      Force the use of views instead of GSI.

      user_xattr_key

      Type

      string

      Description

      The key to use for the user xattr that will be accessible from the sync function. IF empty, the feature will be disabled.

      username

      Type

      string

      Description

      The username for authenticating to the server.

      view_query_timeout_secs

      Type

      integer

      Description

      The number of seconds before a view query should timeout.