Couchbase Connection

See the Connector Marketplace topic. Please request your administrator to start a trial or subscribe to the Premium Couchbase connector.

Couchbase is a NoSQL database that combines the flexibility of JSON with the power of SQL-like querying for high-performance, distributed, and scalable data management.

This topic describes how to authenticate to Couchbase and configure any necessary connection properties in the Couchbase connection connector.

Connection Configuration #

Each connection property available in the Couchbase connector is explained below.

Connection Name #

The name of the connection to be created should be provided. This is the name that will display on the list of available connections.

Server #

The address of the Couchbase server or servers to which you are connecting.

This value can be set to a hostname or an IP address, like “couchbase-server.com” or “1.2.3.4”.

It can also be set to an HTTP or HTTPS URL, such as “https://couchbase-server.com” or “http://1.2.3.4”.

If Connection Mode is set to Cloud then this should be the hostname of the Couchbase Cloud instance.

If the URL form is used, then setting this option will also set the UseSSL option: if the URL scheme is “https://”, then UseSSL will be set to true, and a URL with “http://” will set UseSSL to false.

A port value cannot be used as part of this option, so values like “http://couchbase-server.com:8093” are not allowed. Please use WebConsolePort, N1QLPort and AnalyticsPort.

This value can also accept multiple servers in the above format separated by commas, such as “1.2.3.4, couchbase-server.com”. This will allow the connector to recover the connection in case some of the servers listed are inaccessible.

Note that while the connector will try to recover the connection as a whole, it may lose individual operations. For example, while a long-running query will fail if the server becomes inaccesssible while that query is running, that query can be retried on the same connection and the connector will execute it on the next active server.

Couchbase Service #

Determines the Couchbase service to connect to.

Possible Values

• N1QL

• Analytics

Default is N1QL.

N1QL #

If N1QL is selected, additional configuration parameter will get listed.

N1QLPort #

The port or URL for connecting to the Couchbase N1QL Endpoint.

This port is used for submitting queries when Couchbase Service is set to N1QL. Any requests to manage indices will also go through this port. It defaults to 8093 when not using SSL, and 18093 when using SSL.

This option can be set one of two ways:

• As a port number like “1234”. With this setting the connector will send N1QL queries to the endpoint http://Server:N1QLPort/query/service. (or https:// if Server is https:// or UseSSL is enabled).

• As a full URL like “http://couchbase.example:1234/proxy”. With this setting the connector send N1QL queries using the endpoint you specify. For example, if you use that URL then N1QL requests will go to http://couchbase.example:1234/proxy/query/serivce. Server and UseSSL are ignored for N1QL requests.

Use Transactions #

Specifies whether to use N1QL transactions when executing queries.

Possible Values:

• Never, Always, Explicit

By default the connector does not use transactions for compatibility with older versions of Couchbase. All of the other options require a connection to Couchbase 7 or above. The N1QL service must also be enabled using Couchbase Service.

Setting this to Always means that all queries will use transactions. An explicit transaction may be created on the connection and queries will use that transaction while it is active. If there is no explicit transaction then queries will use implicit transactions instead.

Setting this to Explicit enables support for explicit transactions only. Explicit transactions may be created but if one is not currently active, then statements will not create an implicit transaction.

Transaction Durability #

Specifies how a document must be stored for a transaction to succeed. Specifies whether to use N1QL transactions when executing queries.

Possible Values

• None, Majority, MajorityAndPersistActive, PersistToMajority

If UseTransactions is enabled, then this option can be set to determine when Couchbase will allow writes in transactions to commit. The Couchbase documentation on Durability and Transactions contains the full details, below is a high-level summary.

This option controls requirements on both quorum and persistence. The quorum may either require no bucket replicas to receive the document (None), or a majority of replicas to have the document (all others). The persistence level requires either that the document be stored in the replica memory (Majoriy) or on the replica disk (MajorityAndPersistActive, PersistToMajority).

None is only useful if the bucket you are using is not configured for replicas. The other options can be used depending on the required performance and durability tradeoffs. Persisting to more replicas is slower but provides greater resilience against a node crashing.

Analytics #

If Analytics is selected, additional configuration parameter will get listed.

Analytics Port #

The port or URL for connecting to the Couchbase Analytics Endpoint.

This port is used for submitting queries when CouchbaseService is set to Analytics. It defaults to 8095 when not using SSL, and 18095 when using SSL.

This option can be set one of two ways:

• As a port number like “1234”. With this setting the connector will send Analytics queries to the endpoint http://Server:AnalyticsPort/analytics/service (or https:// if Server is https:// or UseSSL is enabled).

• As a full URL like “http://couchbase.example:1234/proxy”. With this setting the connector send Analytics queries using the endpoint you specify. For example, if you use that URL then Analytics requests will go to http://couchbase.example:1234/proxy/analytics/serivce. Server and UseSSL are ignored for Analytics requests.

Auth Scheme #

The type of authentication to use when connecting to Couchbase.

Possible Values

• Basic

• Credentials File

• SSL Certificate

Basic #

If Basic is selected, additional configuration parameter will get listed.

User #

The Couchbase user account used to authenticate.

Password #

The password used to authenticate the user.

Credentials File #

Use this property if you need to provide credentials for multiple users or buckets. This file takes priority over other forms of authentication.

Set Credentials File to the path to a file that has the same markup as below:

[{“user”: “YourUserName1”, “pass”:“YourPassword1”}, {“user”: “YourUserName2”, “pass”:“YourPassword2”}]

SSL Certificate #

Uses SSL client certificate authentication.

Requires that Use SSL be enabled and that SSL Client Cert and SSL Client Cert Type be set.

Connection Mode #

Determines how to connect to the Couchbase server. Must be either Direct or Cloud.

Possible Values

• Direct

• Cloud

By default the connector connects to Couchbase directly using the address given in the Server option. The Server must be running the appropriate CouchbaseService to accept the connection. This will work in most on-premise or basic cloud deployments.

This should be set to Cloud when connecting to Couchbase Capella or a custom deployment that uses service records. These records will allow the connector to determine the exact Couchbase servers that provide the appropriate CouchbaseService. You must also set the DNSServer property so that the connector is able to fetch these service records.

Note that enabling Cloud mode will override these connection properties with the values discovered by contacting the cluster:

• Server

• N1QL Port

• Analytics Port

DNS Server #

Determines what DNS server to use when retrieving Couchbase Capella information.

In most cases any public DNS server can be provided here such as the ones provided by OpenDNS, Cloudflare or Google.

If these are not accessible then you will need to use the DNS server configured by your network administrator.

Web Console Port #

The port or URL for connecting to the Couchbase Web Console.

This port is used for API operations like managing buckets. It defaults to 8091 when not using SSL, and 18091 when using SSL. See UseSSL.

This option can be set one of two ways:

• As a port number like “1234”. With this setting the connector will send management requests to http://Server:WebConsolePort/. The exact endpoint depends upon the operation being used. For example, the cluster status request will go to the endpoint http://Server:WebConsolePort/pools.

• As a full URL like “http://couchbase.example:1234/proxy”. With this setting the connector will send Web Console queries using the endpoint you specify. For example, if you use that URL then the cluster status request (normally at /pools) will go to http://couchbase.example:1234/proxy/pools. Server and UseSSL are ignored for web console requests.

Enable SSL #

Option to enable SSL. This field sets whether the connector will attempt to negotiate TLS/SSL connections to the server. By default, the connector checks the server’s certificate against the system’s trusted certificate store.

Use SSL #

Whether to negotiate TLS/SSL when connecting to the Couchbase server.

When this is set to true, the defaults for the following options change:

This option should be enabled when connecting to Couchbase Capella because all Capella deployments use SSL by default.

SSL Client Certificate #

The TLS/SSL client certificate store for SSL Client Authentication (2-way SSL).

The name of the certificate store for the client certificate.

If the store is password protected, specify the password in the SSL Client Cert Password field.

Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file.

When the type is PFXBlob, the property must be set to the binary contents of a PFX file (for example, PKCS12 certificate store).

SSL Client Cert Type #

The type of key store containing the TLS/SSL client certificate.

This property can be set to one of the following values:

SSL Client Cert Password #

If the certificate store is of a type that requires a password, this property is used to specify that password to open the certificate store.

SSL Client Cert Subject #

The subject of the TLS/SSL client certificate.

When loading a certificate the subject is used to locate the certificate in the store.

If an exact match is not found, the store is searched for subjects containing the value of the property. If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value “*” picks the first certificate in the certificate store.

The certificate subject is a comma separated list of distinguished name fields and values. For example, “CN=www.server.com, OU=test, C=US, E=support@company.com”.

The common fields and their meanings are shown below.

Upload Keystore File #

If SSL is enabled, a keystore file has to be uploaded using this option.

Add Configuration: Additional properties can be added using this option as key-value pairs.

After entering all the details, click on the TEST button.

If the connection service identification and authentication details are provided correctly, a success message stating “connection available” is generated.

Click on the CREATE button to save the changes.

If the details are incorrect or the server is down, you will get a message “Connection unavailable”.