Cassandra CQL resource adaptor configuration

The Cassandra CQL resource adaptor has configuration properties related to:

  1. The Cassandra database to connect to — contact points and keyspace

  2. Configuration options of the Cassandra cluster — protocol version, port, query consistency level and so on

  3. Cassandra database authentication — authentication options for connecting and re-connecting to the database

  4. Connecting to the Cassandra database — policies for connecting and re-connecting to the database

  5. Socket options — socket options passed to the DataStax driver

  6. Load balancing options — a subset of the available load balancing options supported by the DataStax driver

  7. Cache of prepared statements — cache size -and entry expiry- configuration (entry expiry is now obsolete)

  8. Processing asynchronous responses — threads used for processing asynchronous responses and submitting events to the SLEE

  9. Optional switches related to debugging — options that may be useful for debugging

The Cassandra database to connect to

These configuration options define the initial set of hosts the resource adaptor entity should connect to and the keyspace it should use. There is one keyspace per resource adaptor entity. If your application requires several keyspaces, then you must create one resource adaptor entity for each keyspace. These properties may be actively changed (i.e whilst the ra entity is active).

Name Type Default Description

cassandraContactPoints

String

localhost

Comma separated list of hostname/ip addresses of cassandra nodes used to discover the cluster topology. The default value is 'localhost'

keyspace

String

The keyspace this RA entity should 'connect' to. There is no default, so this property must be defined.
Note

Contact points are addresses of Cassandra nodes that the resource adaptor uses to discover the cluster topology. Only one contact point is required (the resource adaptor will retrieve the address of the other nodes automatically). It is recommended to use more than one contact point, because if that single contact point is unavailable, the resource adaptor cannot connect to the cluster.

These configuration options define general properties of the connection made to the Cassandra cluster. They may be actively changed (i.e whilst the ra entity is active) and will have an impact on the next time the resource adaptor needs to re-connect to the cassandra cluster.

Name Type Default Description

policy.protocol.version

String

use-default

The binary protocol version to use. Possible values are: V1, V2, V3 (the default).

policy.protocol.compression

String

use-default

The compression method to use with the binary protocol. Possible values are:

  • NONE — the default

  • SNAPPY — use the Snappy library for frame compression

  • LZ4 — use the LZ4 library for frame compression

policy.protocol.usessl.jdk

Boolean

false

If SSL should be used (using jdk built-in engine).

policy.protocol.usessl.netty

Boolean

false

If SSL should be used (defer to the Netty layer).

policy.protocol.port

Integer

9042

The port to connect to the cassandra database

policy.query.consistency

String

LOCAL_QUORUM

The default query consistency level.

policy.query.serialconsistency

String

use-default

The default serial consistency level for conditional updates. The default value is SERIAL

policy.query.fetchsize

Integer

5000

The default fetch size (the number of rows) to use for SELECT queries. Allowable values are 1 …​ Integer.MAX_VALUE

policy.query.defaulttimeout

Integer

4500

The default timeout (in milliseconds) for synchronous queries if none is supplied. Allowable values are 1 …​ 60000

policy.prepare.timeout

Integer

4500

The timeout (in milliseconds) for the preparation of queries. Allowable values are 1 …​ 60000
Note

The configuration options policy.query.consistency, policy.query.serialconsistency, policy.query.fetchsize and policy.query.defaulttimeout represent the default values the resource adaptor will use if per query values are not provided. For example, you can set the consistency level of a statement to a value other than the default by using CassandraStatement.setConsistencyLevel(CassandraConsistencyLevel consistency)
Note

Possible consistency levels (from Apache Cassandra™ 2.0 — Configuring data consistency) are:

  • ALL — A write must be written to the commit log and memtable on all replica nodes in the cluster for that partition.

  • EACH_QUORUM — Strong consistency. A write must be written to the commit log and memtable on a quorum of replica nodes in all data centers.

  • QUORUM — A write must be written to the commit log and memtable on a quorum of replica nodes.

  • LOCAL_QUORUM — Strong consistency. A write must be written to the commit log and memtable on a quorum of replica nodes in the same data center as the coordinator node. Avoids latency of inter-data center communication.

  • ONE — A write must be written to the commit log and memtable of at least one replica node.

  • TWO — A write must be written to the commit log and memtable of at least two replica nodes.

  • THREE — A write must be written to the commit log and memtable of at least three replica nodes.

  • LOCAL_ONE — A write must be sent to, and successfully acknowledged by, at least one replica node in the local data center.

  • ANY — A write must be written to at least one node. If all replica nodes for the given partition key are down, the write can still succeed after a hinted handoff has been written. If all replica nodes are down at write time, an ANY write is not readable until the replica nodes for that partition have recovered.

  • SERIAL — Achieves linearizable consistency for lightweight transactions by preventing unconditional updates.

  • LOCAL_SERIAL — Same as SERIAL but confined to the data center. A write must be written conditionally to the commit log and memtable on a quorum of replica nodes in the same data center.

For more details, refer to Cassandra documentation:

Cassandra database authentication

These properties determine how the Cassandra CQL resource adaptor authenticates with the Cassandra cluster. These properties may be actively changed (i.e whilst the ra entity is active) and will have an impact on the next time the resource adaptor needs to re-connect to the Cassandra cluster.

Name Type Default Description

auth.user

String

not-set

Username for Cassandra database authentication

auth.password

String

not-set

Password for Cassandra database authentication
Note

If auth.user is set, then a value must also be provided for auth.password. If neither is set, then no authentication credentials will be sent to the Cassandra cluster when making connection attempts. If both properties are set, then the Cassandra CQL resource adaptor will attempt to connect using the provided credentials.

Connecting to the Cassandra database

These properties dictate how the Cassandra CQL resource adaptor directs the DataStax driver to connect to the Cassandra cluster. These properties may be actively changed (i.e whilst the ra entity is active) and will have an impact on the next time the resource adaptor needs to re-connect to the cassandra cluster.

Name Type Default Description

reconnection.policy

String

constant

The two policies available for connection/re-connection (reconnection.policy) are:

  • constant — the driver attempts to connect with a fixed period. The reconnection.constant.delay property is the period (measured in seconds).

  • exponential — the driver attempts to connect with an increasing period.

reconnection.constant.delay

Integer

10

How long (s) between attempts to connect to the Cassandra DB (constant). Acceptable values are 5s to 60s.

reconnection.exponential.initialdelay

Integer

1

The first delay (s) before attempting to connect to the Cassandra DB (exponential). Acceptable values are 1s to 24s.

reconnection.exponential.maxdelay

Integer

32

Subsequent delay (s) = 2 x previous delay, capped by max delay (s) (exponential). Acceptable values are 16s to 128s.
Note

The reconnection.policy, is related to the resource adaptor re-connecting to a database that it had previously connected. Connection attempts for the initial connection are always constant with a period of reconnection.constant.delay

Socket options

These properties correspond to socket options of the DataStax driver.

Name Type Default Description

socket.connecttimeout

Integer

4000

How long (ms) to establish a new connection to a Cassandra node before giving up.

socket.readtimeout

Integer

4000

How long (ms) for a given Cassandra node to answer a query.

socket.keepalive

String

not-set

True/False/not-set. Whether to enable TCP keepalive. The default, (not-set), means the value used is the default from the underlying Netty transport.

socket.reuseaddress

String

not-set

True/False/not-set. Whether reuse-address is enabled. The default, (not-set), means the value used is the default from the underlying Netty transport.

socket.solinger

Integer

-1

The linger-on-close timeout. The default, (-1 == not set), means the value used is the default from the underlying Netty transport.

socket.tcpnodelay

Boolean

True

Whether to disable Nagle’s algorithm.

socket.receivebuffersize

Integer

-1

Sets a hint to the size of the underlying buffers for incoming network I/O. The default, (-1 == not set), means the value used is the default from the underlying Netty transport.

socket.sendbuffersize

Integer

-1

Sets a hint to the size of the underlying buffers for outgoing network I/O. The default, (-1 == not set), means the value used is the default from the underlying Netty transport.
Note Setting 'socket.solinger' to 0 disables SO_Linger and is not recommended

Load balancing options

These properties correspond to a subset of all available load balancing options supported by the DataStax driver.

Name Type Default Description

lb.recipe

String

use-default

Select the load-balancing approach to use. Allowed values include: round-robin, dc-aware-round-robin, latency-aware-round-robin, latency-aware-dc-aware-round-robin. A value of use-default uses the driver default.

lb.latencyaware.exclusionThreshold

Double

0.0

How much worse the average latency of a node must be compared to the fastest performing node for it to be penalized. Must be greater than 1.0. A value of 0 means use the driver default.

lb.latencyaware.scale

Long

0

Dictates the weight of a latency measurement to previous measurements in average latency. The value must be greater than 0. A value of 0 means use the driver default.
Note

The following recipes are supported are:

  • round-robin — This policy queries nodes in a round-robin fashion. For a given query, if an host fail, the next one (following the round-robin order) is tried, until all hosts have been tried.

  • dc-aware-round-robin — This policy provides round-robin queries over the node of the local data center. It also includes in the query plans returned a configurable number of hosts in the remote data centers, but those are always tried after the local nodes. In other words, this policy guarantees that no host in a remote data center will be queried unless no host in the local data center can be reached.

  • latency-aware-round-robin — Adds latency awareness to a round-robin policy

  • latency-aware-dc-aware-round-robin — Adds latency awareness to a dc-aware-round-robin policy

A value of 'use-default' means the DataStax driver default load balancing configuration will be used.

The latency-aware load balancing policy collect latencies of the queries to each Cassandra node and maintain a per-node average latency score. The nodes that are slower than the best performing node by more than a configurable threshold will be moved to the end of the query plan (that is, they will only be tried if all other nodes failed).

The latency-aware configuration properties include:

  • exclusionThreshold — controls how much worse the average latency of a node must be compared to the fastest performing node for it to be penalized by the policy. The default exclusion threshold is 2.

  • scale — provides control on how the weight given to older latencies decreases over time. A bigger scale gives less weight to new measurements (compared to previous measuresments), a smaller scale will give them more weight. The default scale is 100ms.

Cache of prepared statements

The resource adaptor manages a cache of prepared statements, implemented as a LoadingCache<String, PreparedCassandraStatement> from the Guava library (guava-libraries — CachesExplained).

Tip See section Preparing statements for more information on preparing statements using the Cassandra CQL resource adaptor API.

The cache is cleared when the resource adaptor entity is deactivated. The size of the cache, -and the cache entry expiry behaviour- is controlled by the statementCache.maxSize and -statementCache.expireAfterAccessT- properties. These properties may be actively changed (i.e whilst the ra entity is active). Entries in the cache are preserved when properties of the cache are changed.

Note

The configuration option statementCache.expireAfterAccessT is now ignored to avoid spamming the logs with WARN statements from the datastax Cassandra driver. These were caused by re-preparing expired statements that were still cached in Cassandra itself. Now prepared statements will not expire in the RA cache.
Name Type Default Description

statementCache.maxSize

Integer

100

Maximum number of entries in the prepared statement cache

statementCache.expireAfterAccessT

Integer

10

Obsolete. -Time (s) after which a statement is removed from the cache since it was last used-

Processing asynchronous responses

The resource adaptor receives asynchronous responses from the DataStax driver and delivers them as events into the Rhino TAS. This function is implemented using a standard java ThreadPoolExecutor. The ThreadPoolExecutor encapsulates a thread pool and a task queue. The following properties define the configuration of this ThreadPoolExecutor and should be set to suit the expected rate of asynchrounous responses.

Name Type Default Description

responseExecutor.corePoolSize

Integer

1

Number of threads available at all times

responseExecutor.maxPoolSize

Integer

5

Maximum number of threads

responseExecutor.nonCoreThreadKeepAliveT

Integer

60

How long (s) to keep non-core threads if they are idle

responseExecutor.queueCapacity

Integer

500

The maximum results to queue waiting for a result executor thread

responseExecutor.guardtimer.enabled

Boolean

true

If the RA guard timer should be used for asynchronous queries

responseExecutor.guardtimer.resolution

Integer

500

Milliseconds between scheduler ticks

responseExecutor.guardtimer.commoninterval

Integer

2000

Common timer interval in milliseconds

responseExecutor.guardtimer.maxinterval

Integer

4500

Maximum timer interval in milliseconds

These properties may be actively changed (i.e whilst the ra entity is active).

Optional switches for debugging

The resource adaptor will request additional notifications from the Rhino TAS when CassandraSession activities end if the debug.activity.requestendedcallback is true.

The resource adaptor will set the enableTracing flag on all queries that take a Statement arg if the debug.activity.tracingenabled is true.

This behaviour is not required for normal operation of the resource adaptor, but may be useful during application testing scenarios. These properties can be actively changed (i.e whilst the ra entity is active).

Name Type Default Description

debug.activity.requestendedcallback

Boolean

false

Should the RA request activity ended notification from the slee

debug.activity.tracingenabled

Boolean

false

Should the RA call enableTracing on all Cassandra Statements.
Previous page Next page