Couchbase Premium 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
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
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:
Property | Plaintext Default | SSL Default |
---|---|---|
AnalyticsPort | 8095 | 18095 |
N1QLPort | 8093 | 18093 |
WebConsolePort | 8091 | 18091 |
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:
Certificate Designation | Description |
---|---|
MY | A certificate store holding personal certificates with their associated private keys. |
CA | Certifying authority certificates. |
ROOT | Root certificates. |
SPC | Software publisher certificates. |
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:
Property Value | Description |
---|---|
USER - default | For Windows, this specifies that the certificate store is a certificate store owned by the current user. Note that this store type is not available in Java. |
MACHINE | For Windows, this specifies that the certificate store is a machine store. Note that this store type is not available in Java. |
PFXFILE | The certificate store is the name of a PFX (PKCS12) file containing certificates. |
PFXBLOB | The certificate store is a string (base-64-encoded) representing a certificate store in PFX (PKCS12) format. |
JKSFILE | The certificate store is the name of a Java key store (JKS) file containing certificates. Note that this store type is only available in Java. |
JKSBLOB | The certificate store is a string (base-64-encoded) representing a certificate store in JKS format. Note that this store type is only available in Java. |
PEMKEY_FILE | The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate. |
PEMKEY_BLOB | The certificate store is a string (base64-encoded) that contains a private key and an optional certificate. |
PUBLIC_KEY_FILE | The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate. |
PUBLIC_KEY_BLOB | The certificate store is a string (base-64-encoded) that contains a PEM- or DER-encoded public key certificate. |
SSHPUBLIC_KEY_FILE | The certificate store is the name of a file that contains an SSH-style public key. |
SSHPUBLIC_KEY_BLOB | The certificate store is a string (base-64-encoded) that contains an SSH-style public key. |
P7BFILE | The certificate store is the name of a PKCS7 file containing certificates. |
PPKFILE | The certificate store is the name of a file that contains a PuTTY Private Key (PPK). |
XMLFILE | The certificate store is the name of a file that contains a certificate in XML format. |
XMLBLOB | The certificate store is a string that contains a certificate in XML format. |
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.
Field | Meaning |
---|---|
CN | Common Name. This is commonly a host name like www.server.com. |
O | Organization |
OU | Organizational Unit |
L | Locality |
S | State |
C | Country |
E | Email Address |
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”.
If you have any feedback on Gathr documentation, please email us!