Skip to content

JDBC driver and connection string

Jump to bottom
Maxime Wiewiora edited this page Jul 27, 2024 · 6 revisions

Basic usage

Connect to a Cassandra cluster using the following arguments:

  • JDBC driver class: com.ing.data.cassandra.jdbc.CassandraDriver
  • JDBC URL: jdbc:cassandra://host1[:port1][--host2[:port2]...--hostN[:portN]]/<keyspace>[?<options>]

The possible options are detailed below in the section "Connection options". If not specified, the default port is the standard Cassandra port (9042).

An example of basic JDBC URL is: jdbc:cassandra://localhost:9042/keyspace?localdatacenter=datacenter1

Tip

To connect to a DBaaS cluster, please read the section "Connection to cloud databases (DBaaS)".

To use a configuration file, please read the section "Using a configuration file".

Important

You also have to specify the name of the local data center (localdatacenter) to use when the default load balancing policy is defined (see section about connection options below about load balancing policies) and no configuration file is specified.

Using multiple contact points

You can give the driver any number of hosts you want separated by "--". You can optionally specify a port for each host. If only one port is specified after all the listed hosts, it applies to all hosts. If no port is specified at all, the default Cassandra port (9042) is used.

They will be used as contact points for the driver to discover the entire cluster. Give enough hosts taking into account that some nodes may be unavailable upon establishing the JDBC connection.

Here are some examples of connection strings with single or multiple contact points:

Valid JDBC URL Contact points used for connection
jdbc:cassandra://localhost/keyspace localhost:9042
jdbc:cassandra://localhost:9043/keyspace localhost:9043
jdbc:cassandra://host1--host2/keyspace host1:9042, host2:9042
jdbc:cassandra://host1--host2:9043/keyspace host1:9043, host2:9043
jdbc:cassandra://host1:9042--host2--host3:9043/keyspace host1:9042, host2:9043, host3:9043

Using a configuration file

If you want to use a configuration file, specify the location with the query parameter configfile. When this parameter is specified, any other configuration mentioned into the JDBC URL, except the contact points and the keyspace, will be ignored and overridden by the values defined in the configuration file. For example:

jdbc:cassandra://host1--host2--host3:9042/keyspace?configfile=/path/to/configuration/application.conf

Execution profiles

The configuration file allows to define several execution profiles. If nothing is specified, the default profile will be used for any query executed by the driver. If you want to initialize a connection with a different profile, you can specify the profile name using the parameter activeprofile:

jdbc:cassandra://host1--host2--host3:9042/keyspace?configfile=/path/to/configuration/application.conf&activeprofile=customProfile

Once the connection is established, you can switch to another execution profile at any moment using the method CassandraConnection.setActiveExecutionProfile(String). For example:

// Assuming connection is a CassandraConnection using the default execution profile.
// Switch to the execution profile named 'customProfile'.
connection.setActiveExecutionProfile("customProfile");
// Perform some queries.
connection.createStatement().executeQuery("INSERT INTO ...");
// Restore the default execution profile for the next queries performed with the connection.
connection.restoreLastExecutionProfile();

Warning

For versions prior to 4.13.0, the JDBC wrapper only supports the default profile defined in the driver configuration.

Connection options

The different acceptable options in the JDBC URL for this driver are:

Parameter Type Description Example(s)
localdatacenter String The local datacenter to use when DefaultLoadBalancingPolicy is applied (it's the default load balancing policy, see Load balancing documentation). jdbc:cassandra://host1--host2--host3:9042/keyspace?localdatacenter=DC1
loadbalancing String The custom load balancing policy to apply. The value must be the full package of the policy's class implementing LoadBalancingPolicy interface. jdbc:cassandra://host1--host2--host3:9042/keyspace?loadbalancing=com.company.package.CustomPolicy
retry String The custom retry policy to apply. The value must be the full package of the policy's class implementing RetryPolicy interface. By default, the driver will use DefaultRetryPolicy (see Retries documentation). jdbc:cassandra://host1--host2--host3:9042/keyspace?retry=com.company.package.CustomPolicy
reconnection String The custom reconnection policy to apply. By default, the driver will use ExponentialReconnectionPolicy (see Reconnection documentation). But if you want to define a custom base delay (in seconds, by default 1 second) and a custom max delay (in seconds, by default 60 seconds), you can specify it as following: ExponentialReconnectionPolicy((long)<delay>,(long)<maxDelay>)
You can also use the ConstantReconnectionPolicy as policy using ConstantReconnectionPolicy() or with a custom base delay (in seconds, by default 1 second): ConstantReconnectionPolicy((long)<baseDelay>)
If you want to use a custom policy, specify the full package of the policy's class.
Make sure you always cast the policy's arguments appropriately.		 Default policy with custom parameters: jdbc:cassandra://host1--host2--host3:9042/keyspace?reconnection=ExponentialReconnectionPolicy((long)2,(long)120)
Using the constant reconnection policy with default parameters: jdbc:cassandra://host1--host2--host3:9042/keyspace?reconnection=ConstantReconnectionPolicy()
Using the constant reconnection policy with custom parameters: jdbc:cassandra://host1--host2--host3:9042/keyspace?reconnection=ConstantReconnectionPolicy((long)10)
Using a custom reconnection policy: jdbc:cassandra://host1--host2--host3:9042/keyspace?reconnection=com.company.package.CustomPolicy()
consistency String The consistency level per connection (it cannot be specified per query). The consistency level defaults to LOCAL_ONE as defined in the configuration reference if not specified (see Consistency levels documentation for further details about the valid values for this argument). jdbc:cassandra://host1--host2--host3:9042/keyspace?consistency=LOCAL_QUORUM
requesttimeout int A custom timeout for the queries in milliseconds. By default, the timeout for queries is 2 seconds (see the property basic.request.timeout in the Configuration reference page). To define a timeout of 5 seconds for the queries: jdbc:cassandra://host1--host2--host3:9042/keyspace?requesttimeout=5000
connecttimeout int A custom connection timeout in milliseconds. By default, the connection timeout is 5 seconds (see the property advanced.connection.connect-timeout). For further information, see the properties documentation in the Configuration reference page. To define a connection timeout of 10 seconds: jdbc:cassandra://host1--host2--host3:9042/keyspace?connecttimeout=10000
keepalive boolean Whether the TCP keep-alive is enabled. By default, it's disabled (see the property advanced.socket.keep-alive). For further information, see the properties documentation in the Configuration reference page. jdbc:cassandra://host1--host2--host3:9042/keyspace?keepalive=true
tcpnodelay boolean Whether the Nagle's algorithm is enabled. By default, it's enabled (see the property advanced.socket.tcp-no-delay). For further information, see the properties documentation in the Configuration reference page. jdbc:cassandra://host1--host2--host3:9042/keyspace?tcpnodelay=false
fetchsize int The default fetch size for all the queries returning result sets. This value is the number of rows the server will return in each network frame. It corresponds to the property datastax-java-driver.basic.request.page-size. By default, this value is set to 100. For further information, see the documentation about the paging. jdbc:cassandra://host1--host2--host3:9042/keyspace?fetchsize=2000

Securing connection with TLS

In order to secure the traffic between the driver and the Cassandra cluster, add at least one of these arguments to the JDBC URL:

  • enablessl=true: the DefaultSslEngineFactory will be used with the JSSE system properties defined for your application
  • sslenginefactory: specify the fully-qualified name of a class with a no-args constructor implementing SslEngineFactory interface, for instance: 
    jdbc:cassandra://host1--host2--host3:9042/keyspace?sslenginefactory=com.company.package.CustomSslEngineFactory

Note

Using a custom SSL engine factory is not recommended in most cases, always prefer using the standard JSSE properties if you can.

The argument sslEngineFactory will be ignored if the argument enableSsl is false but SSL will be enabled if sslEngineFactory is present even if enableSsl is missing.

By default, when the DefaultSslEngineFactory is used, the validation of the server certificate's common name against the hostname of the server being connected to is required. To disable it, set the argument hostnameverification=false in the JDBC URL.

For further information about custom implementations of SslEngineFactory, see SSL documentation.

Compliance modes

For some specific usages, the default behaviour of some JDBC implementations has to be modified. That's why you can use the argument compliancemode in the JDBC URL to customize the behaviour of some methods.

The values currently allowed for this argument are:

  • Default: mode activated by default if not specified in the JDBC URL. It implements the methods detailed below as defined in the JDBC specification (according to the Cassandra driver capabilities).
  • Liquibase: compliance mode for a usage of the JDBC driver with Liquibase.

Here are the behaviours defined by the compliance modes listed above:

Method Default mode Liquibase mode
CassandraConnection.getCatalog() returns the result of the querySELECT cluster_name FROM system.local or null if not available returns the schema name if available, null otherwise
CassandraConnection.rollback() throws a SQLFeatureNotSupportedException do nothing more after checking connection is open
CassandraStatement.executeUpdate(String) returns 0 returns -1

For the following methods: CassandraStatement.execute(String), CassandraStatement.executeQuery(String) and CassandraStatement.executeUpdate(String), if the CQL statement includes several queries (separated by semicolons), the behaviour is the following:

Default mode Liquibase mode
executes the queries asynchronously executes the queries synchronously

Connection to cloud databases (DBaaS)

An alternative JDBC driver based on this one exists to ease the connection to the cloud Cassandra-based DBaaS AstraDB cluster: Astra JDBC driver. Do not hesitate to use it if you are in this specific situation.

It's still possible to connect to AstraDB using this JDBC wrapper, so one would need to specify the following parameters:

  • secureconnectbundle: the fully qualified path of the cloud secure connect bundle file
  • keyspace: the keyspace to connect to
  • user: the username
  • password: the password (if you are using a token, you can specify it here and set user value to token)

For example, using the dedicated protocol jdbc:cassandra:dbaas::

jdbc:cassandra:dbaas:///keyspace?consistency=LOCAL_QUORUM&user=my_user&password=my_password&secureconnectbundle=/path/to/location/secure-connect-bundle-cluster.zip

Note

Whatever the host(s) given here will be ignored and will be fetched from the cloud secure connect bundle. So, you can let the host part empty.

For further information about connecting to DBaaS, see cloud documentation.

Connection using Kerberos authentication

To use Kerberos for authentication, add the argument userkrb5=true to the JDBC URL. This will enable the Kerberos AuthProvider implementation for the connection with default parameters.

See Authentication reference and Kerberos authenticator for Java driver for further information.

Clone this wiki locally