SQL Driver: Cassandra

Driver name cassandra.

Driver for Apache Cassandra CQL server.

To compile support for this driver, you need to have DataStax C/C++ driver and headers installed.

Settings

`cassandra_application_name`

Default	`Dovecot`
Value	string
See Also	`cassandra_application_version` `cassandra_client_id`
Changes	Added: 2.4.6

Application name sent to the Cassandra server when connecting. This can be used to identify Dovecot's client connections on the Cassandra side.

If empty, neither the application name nor cassandra_application_version is sent.

Older cpp-driver versions can't send the application name. The default is then empty, and setting a name fails.

`cassandra_application_version`

Default	`[Dovecot version]`
Value	string
See Also	`cassandra_application_name`
Changes	Added: 2.4.6

Application version sent to the Cassandra server when connecting. If empty, the Dovecot version is used.

This is sent only when cassandra_application_name is non-empty.

`cassandra_client_id`

Default	`[random UUID]`
Value	string
See Also	`cassandra_application_name`
Changes	Added: 2.4.6

Client ID UUID sent to the Cassandra server when connecting, e.g. 01234567-89ab-4def-8123-456789abcdef. If empty, the driver generates a random UUIDv4.

`cassandra_connect_timeout`

Default	`5s`
Value	time (milliseconds)

Connection timeout.

`cassandra_connections_per_host`

Default	`1`
Value	unsigned integer
See Also	`cassandra_io_thread_count`
Changes	Added: 2.4.6

Number of connections to create to each Cassandra host for each IO thread. The total number of connections per host is this value multiplied by cassandra_io_thread_count.

Increasing this may help to increase concurrency with busy processes. Must not be 0.

`cassandra_debug_queries`

Default	`no`
Value	boolean

Whether to log CQL queries.

`cassandra_delete_consistency`

Default	`local-quorum`
Value	string
Allowed Values	`anylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall`
See Also	Cassandra: Consistency

Write consistency when deleting from the database. See Cassandra: Consistency.

`cassandra_delete_fallback_consistency`

Default	`local-quorum`
Value	string
Allowed Values	`anylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall`
See Also	Cassandra: Consistency

Write consistency when deleting from the database fails with primary consistency.

`cassandra_execution_retry_interval`

Default	[None]
Value	time (milliseconds)

If the driver supports speculative execution policy, configures constant speculative execution policy. See https://docs.datastax.com/en/developer/java-driver/latest/manual/core/speculative_execution/index.html

WARNING

If Cassandra is completely unavailable and speculative execution is used, Cassandra cpp-driver library starts hanging all queries due to a bug. This may cause problems in the dict process even after Cassandra is back online. When this happens, "Dict server timeout" errors are being logged.

`cassandra_execution_retry_times`

Default	[None]
Value	time (milliseconds)

WARNING

`cassandra_heartbeat_interval`

Default	`30s`
Value	time

How often to send keepalive packets to cassandra nodes.

`cassandra_hosts`

Default	[None]
Value	Boolean List

List of hosts or IP addresses to connect.

`cassandra_idle_timeout`

Default	`0`
Value	time (milliseconds)

How long to idle before disconnecting.

`cassandra_io_thread_count`

Default	`[driver dependent]`
Value	unsigned integer

Set number of IO threads to handle query requests.

`cassandra_keyspace`

Default	[None]
Value	string

Specifies the keyspace name to use.

`cassandra_latency_aware_exclusion_threshold`

Default	`2.0`
Value	string
See Also	`cassandra_latency_aware_routing`
Changes	Added: 2.4.6

Used by cassandra_latency_aware_routing: how much worse a host's average latency may be compared to the best performing host before it is penalized. For example the default 2.0 penalizes hosts whose average latency is more than twice the best host's latency.

This is a floating point number, which must be at least 1.0.

`cassandra_latency_aware_min_measured`

Default	`50`
Value	unsigned integer
See Also	`cassandra_latency_aware_routing`
Changes	Added: 2.4.6

Used by cassandra_latency_aware_routing: minimum number of latency measurements per host before the host's latency is taken into account.

`cassandra_latency_aware_retry_period`

Default	`10s`
Value	time (milliseconds)
See Also	`cassandra_latency_aware_routing`
Changes	Added: 2.4.6

Used by cassandra_latency_aware_routing: how long a host is penalized before it is given another chance.

`cassandra_latency_aware_routing`

Default	`no`
Value	boolean
See Also	`cassandra_latency_aware_exclusion_threshold` `cassandra_latency_aware_min_measured` `cassandra_latency_aware_retry_period` `cassandra_latency_aware_scale` `cassandra_latency_aware_update_rate`

When turned on, latency-aware routing tracks the latency of queries to avoid sending new queries to poorly performing Cassandra nodes.

`cassandra_latency_aware_scale`

Default	`100ms`
Value	time (milliseconds)
See Also	`cassandra_latency_aware_routing`
Changes	Added: 2.4.6

Used by cassandra_latency_aware_routing: controls the weight given to older latencies when calculating a host's average latency. A larger value gives more weight to older measurements.

`cassandra_latency_aware_update_rate`

Default	`100ms`
Value	time (milliseconds)
See Also	`cassandra_latency_aware_routing`
Changes	Added: 2.4.6

Used by cassandra_latency_aware_routing: how often the best average latency is recalculated.

`cassandra_local_datacenter`

Default	[None]
Value	string
See Also	`cassandra_hosts` `cassandra_read_consistency` `cassandra_write_consistency` `cassandra_delete_consistency`
Changes	Added: 2.4.6

Name of the local datacenter. Queries are sent only to the hosts in the local datacenter. This also defines the datacenter used by the local-one and local-quorum consistency levels.

If empty, the driver uses the datacenter of whichever contact point in cassandra_hosts answers first. This is nondeterministic when cassandra_hosts contains hosts from multiple datacenters. Hosts in the other datacenters are never used. It's recommended to set this when the Cassandra cluster has multiple datacenters. See Cassandra: Local Datacenter.

`cassandra_log_level`

Default	`warn`
Value	string
Allowed Values	`criticalerrorwarninfodebugtrace`

Driver log level.

`cassandra_log_retries`

Default	`no`
Value	boolean

Whether to log about failed requests that are retried (which may or may not succeed after the retry).

`cassandra_logged_batches`

Default	`yes`
Value	boolean
Changes	Added: 2.4.6

Whether transactions with multiple statements are sent as LOGGED batches. When no, they are sent as UNLOGGED batches. This is needed for Cassandra-compatible databases that don't support LOGGED batches.

UNLOGGED batches that update multiple partitions aren't atomic: if the batch fails, only some of the changes may have been written. Batches that update a single partition are atomic in either case.

`cassandra_metrics_path`

Default	[None]
Value	string

Path where to write JSON metrics. See Cassandra: Metrics.

`cassandra_page_size`

Default	[None]
Value	unsigned integer

When a query returns many rows, it can be sometimes inefficient to return them as a single response message. Instead, the driver can break the results into pages which get returned as they are needed.

This setting controls the size of each page.

Set to 0 to disable.

`cassandra_password`

Default	[None]
Value	string

Password for authentication.

`cassandra_port`

Default	`9042`
Value	Port Number

CQL port to use.

`cassandra_protocol_version`

Default	`depends on driver version`
Value	string
Allowed Values	`345`

Cassandra protocol version to use. It is good idea to specify this to avoid warnings about version handshake if the driver supports a higher protocol version than the server.

INFO

If you want to use server-side prepared statements, you need to use at least 4.

`cassandra_read_consistency`

Default	`local-quorum`
Value	string
Allowed Values	`anylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall`
See Also	Cassandra: Consistency

Read consistency.

`cassandra_read_fallback_consistency`

Default	`local-quorum`
Value	string
Allowed Values	`anylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall`
See Also	Cassandra: Consistency

Read consistency if primary consistency fails.

`cassandra_reconnect_base_delay`

Default	`2s`
Value	time (milliseconds)
See Also	`cassandra_reconnect_policy` `cassandra_reconnect_max_delay`
Changes	Added: 2.4.6

With cassandra_reconnect_policy = exponential this is the initial delay before reconnecting to a Cassandra host. It must be larger than 1 millisecond.

With cassandra_reconnect_policy = constant this is the delay between all reconnection attempts. 0 means reconnecting immediately.

`cassandra_reconnect_max_delay`

Default	`60s`
Value	time (milliseconds)
See Also	`cassandra_reconnect_policy` `cassandra_reconnect_base_delay`
Changes	Added: 2.4.6

With cassandra_reconnect_policy = exponential this is the maximum delay between reconnection attempts. It must not be smaller than cassandra_reconnect_base_delay.

Not used with cassandra_reconnect_policy = constant.

`cassandra_reconnect_policy`

Default	`exponential`
Value	string
Allowed Values	`exponentialconstant`
See Also	`cassandra_reconnect_base_delay` `cassandra_reconnect_max_delay`
Changes	Added: 2.4.6

How to reconnect to a Cassandra host after the connection is lost:

exponential: Start with cassandra_reconnect_base_delay and increase the delay exponentially after each attempt, up to cassandra_reconnect_max_delay. A random jitter of +/- 15% is added to the delay.
constant: Always wait cassandra_reconnect_base_delay.

cpp-driver older than v2.14 supports only constant, which is then also the default.

`cassandra_request_queue_size`

Default	`8192`
Value	unsigned integer
See Also	`cassandra_io_thread_count` `cassandra_metrics_path`
Changes	Added: 2.4.6

Maximum number of requests queued for each IO thread while waiting for the thread to process them. The total capacity is this value multiplied by cassandra_io_thread_count. The driver rounds the value up to the next power of two.

When the queue is full, new requests fail immediately. These failures are counted in the recv_err_queue_full field of cassandra_metrics_path. Must not be 0.

`cassandra_request_timeout`

Default	`60s`
Value	time (milliseconds)

How long to wait for a query to finish.

`cassandra_source_ip`

Default	[None]
Value	IP addresses
Changes	Added: 2.4.6

Source IP address to use for connections to Cassandra hosts. Only IP addresses are supported, not host names. If empty, the source IP address is chosen by the operating system.

`cassandra_ssl`

Default	`no`
Value	string
Allowed Values	`nocert-onlycert-ip`
See Also	SSL configuration `ssl_client_require_valid_cert`

Whether to use SSL when connecting to Cassandra, and how to verify the certificate:

no: Don't use SSL
cert-only: Verify the certificate, but not the IP address or host name.
cert-ip: Verify the certificate, and require IP address to match the certificate's common name or one of its subject alternative names.

You can also skip certificate validation by setting ssl_client_require_valid_cert = yes. The cassandra_ssl setting value must something else than no.

Configure SSL certificates using the ssl_client_* settings. See SSL configuration.

`cassandra_tcp_keepalive`

Default	[None]
Value	time
See Also	`cassandra_heartbeat_interval`
Changes	Added: 2.4.6

If non-zero, enable TCP keepalive for Cassandra connections with this initial delay. This can detect connections that have been silently dropped by e.g. firewalls or NAT devices. 0 disables TCP keepalive.

`cassandra_token_aware_routing`

Default	`yes`
Value	boolean
See Also	`cassandra_token_aware_shuffle_replicas`
Changes	Added: 2.4.6

Send queries directly to a host that has the data (a replica for the queried partition), avoiding an extra hop through a coordinator host. This should normally be kept enabled, but disabling it may be useful for debugging.

`cassandra_token_aware_shuffle_replicas`

Default	`yes`
Value	boolean
See Also	`cassandra_token_aware_routing`
Changes	Added: 2.4.6

Used by cassandra_token_aware_routing: randomly shuffle the replicas for each query. This distributes load better between the replicas, but reduces the effectiveness of the Cassandra server's caching. Disabling this may improve performance when the same keys are read repeatedly.

Older cpp-driver versions don't support shuffling. The default is then no, and enabling it fails.

`cassandra_user`

Default	[None]
Value	string

Username for authentication.

`cassandra_warn_timeout`

Default	`5s`
Value	time (milliseconds)

Emit warning if query takes longer than this.

`cassandra_write_consistency`

Default	`local-quorum`
Value	string
Allowed Values	`anylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall`
See Also	Cassandra: Consistency

Write consistency when updating or inserting to the database.

`cassandra_write_fallback_consistency`

Default	`local-quorum`
Value	string
Allowed Values	`anylocal-serialserialonetwothreelocal-quorumquorumeach-quorumall`
See Also	Cassandra: Consistency

Write consistency when updating or inserting to the database fails with primary consistency.

`dns_client_timeout`

Default	`10s`
Value	time (milliseconds)

Timeout for DNS lookups.

This is also used by the Cassandra driver for resolving cassandra_hosts. It can be changed for Cassandra only by placing it inside a cassandra filter:

cassandra {
  dns_client_timeout = 5s
}

SSL/TLS Settings

Not all of Dovecot SSL settings are supported by the Cassandra library. Below is the list of supported settings:

`ssl_client_ca_file`

Default	[None]
Value	File
See Also	`ssl` `ssl_client_ca_dir` SSL configuration

File containing the trusted SSL CA certificates. For example /etc/ssl/certs/ca-bundle.crt.

These certificates are used only for outgoing SSL connections (e.g. with the imapc driver).

Note that this setting isn't recommended to be used with large CA bundles, because all the certificates are read into memory. This leads to excessive memory usage, because it gets multiplied by the number of imap processes. It's better to either use ssl_client_ca_dir setting or use a CA bundle that only contains the CAs that are actually necessary for the server operation.

If both ssl_client_ca_dir and ssl_client_ca_file are empty, the system CA certificates are used.

`ssl_client_cert_file`

Default	[None]
Value	File
See Also	`ssl` `ssl_client_key_file` SSL configuration

Public SSL certificate used for outgoing SSL connections. This is generally needed only when the server authenticates the client using the certificate.

ssl_client_key_file is also needed for the private certificate.

Example:

ssl_client_cert_file = /etc/dovecot/dovecot-client.crt
ssl_client_key_file = /etc/dovecot/dovecot-client.key

`ssl_client_key_file`

Default	[None]
Value	File
See Also	`ssl` `ssl_client_cert_file` SSL configuration

Private key for ssl_client_cert_file. If it is password protected, set the password with ssl_client_key_password.

Example:

ssl_client_cert_file = /etc/dovecot/dovecot-client.crt
ssl_client_key_file = /etc/dovecot/dovecot-client.key

`ssl_client_key_password`

Default	[None]
Value	string
See Also	`ssl` `ssl_client_key_file` SSL configuration

Password for the ssl_client_key_file.

`ssl_client_require_valid_cert`

Default	`yes`
Value	boolean
See Also	`ssl` SSL configuration

Require a valid certificate when connecting to external SSL services?

Local Datacenter

Queries are sent only to the Cassandra nodes in the local datacenter. The local datacenter is also used by the local-one, local-quorum and local-serial consistency levels.

The local datacenter is configured with cassandra_local_datacenter. If it's empty, the local datacenter is the datacenter of whichever cassandra_hosts node happens to answer first when connecting. This is nondeterministic if cassandra_hosts contains nodes from multiple datacenters. So with multiple datacenters cassandra_local_datacenter should always be set:

doveconf

cassandra_local_datacenter = dc1

Consistency

Consistency levels in Cassandra can be configured to manage availability versus data accuracy. The local-* consistency levels refer to the local datacenter.

Read Consistency

`any`

DANGER

Not supported for reads.

`local-serial`

Allows reading the current (and possibly uncommitted) state of data without proposing a new addition or update.

If a SERIAL read finds an uncommitted transaction in progress, it will commit the transaction as part of the read.

Local serial is confined to datacenter.

`serial`

Allows reading the current (and possibly uncommitted) state of data without proposing a new addition or update.

If a SERIAL read finds an uncommitted transaction in progress, it will commit the transaction as part of the read.

`one`

Returns a response from the closest replica, as determined by the snitch.

`two`

Returns the most recent data from two of the closest replicas.

`three`

Returns the most recent data from three of the closest replicas.

`local-quorum`

Returns the record after a quorum of replicas in the current datacenter as the coordinator has reported.

`quorum`

Returns the record after a quorum of replicas from all datacenters has responded.

`each-quorum`

DANGER

Not supported for reads.

`all`

Returns the record after all replicas have responded. The read operation will fail if a replica does not respond.

Write/Delete Consistency

`any`

At least one node must succeed in the operation.

`local-serial`

DANGER

Not supported for writes.

`serial`

DANGER

Not supported for writes.

`one`

Operation must be at least in commit log and one memory table of one replica.

`two`

Operation must be at least in commit log and one memory table of two replicas.

`three`

Operation must be at least in commit log and one memory table of three replicas.

`local-quorum`

A write must be written to the commit log and memory table on a quorum of replica nodes in the same datacenter as the coordinator.

`quorum`

A write must be written to the commit log and memory table on a quorum of replica nodes across all datacenters.

`each-quorum`

A write must be written to the commit log and memory table on a quorum of replica nodes in each datacenter.

`all`

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

Metrics

This describes the format of the JSON output produced when the metrics configuration option is activated.

Source: https://docs.datastax.com/en/developer/cpp-driver/latest/api/struct.CassMetrics/index.html

Details

json

{
    "Requests": {
        # Minimum in microseconds
        "min": [Number: integer],
        # Maximum in microseconds
        "max": [Number: integer],
        # Mean in microseconds
        "mean": [Number: integer],
        # Standard deviation in microseconds
        "stddev": [Number: integer],
        # Median in microseconds
        "median": [Number: integer],
        # 75th percentile in microseconds
        "percentile_75th": [Number: integer],
        # 95th percentile in microseconds
        "percentile_95th": [Number: integer],
        # 98th percentile in microseconds
        "percentile_98th": [Number: integer],
        # 99th percentile in microseconds
        "percentile_99th": [Number: integer],
        # 99.9th percentile in microseconds
        "percentile_999th": [Number: integer],
        # Mean rate in requests per second
        "mean_rate": [Number: fraction],
        # 1 minute rate in requests per second
        "one_minute_rate": [Number: fraction],
        # 5 minute rate in requests per second
        "five_minute_rate": [Number: fraction],
        # 15 minute rate in requests per second
        "fifteen_minute_rate": [Number: fraction]
    },
    "stats": {
        # The total number of connections
        "total_connections": [Number: integer],
        # The number of connections available to take requests
        "available_connections": [Number: integer],
        # Occurrences when requests exceeded a pool's water mark
        "exceeded_pending_requests_water_mark": [Number: integer],
        # Occurrences when number of bytes exceeded a connection's water mark
        "exceeded_write_bytes_water_mark": [Number: integer]
    },
    "queries": {
        # Number of queries sent to Cassandra
        "sent": [Number: integer],
        # Number of successful responses
        "recv_ok": [Number: integer],
        # Number of requests that couldn’t be sent, because the local
        # Cassandra driver’s queue was full.
        "recv_err_queue_full": [Number: integer],
        # Number of requests that didn’t succeed because the Cassandra
        # driver couldn’t connect to the server.
        "recv_err_no_hosts": [Number: integer],
        # Number of requests that didn’t succeed because the Cassandra
        # driver timed out while waiting for response from server.
        "recv_err_client_timeout": [Number: integer],
        # Number of requests that didn’t succeed because the Cassandra
        # server reported a timeout communicating with other nodes.
        "recv_err_server_timeout": [Number: integer],
        # Number of requests which couldn’t succeed, because not enough
        # Cassandra nodes were available for the consistency level.
        "recv_err_server_unavailable": [Number: integer]
        # Number of requests which couldn’t succeed for other reasons.
        "recv_err_other": [Number: integer]
    },
    "errors": {
        # Occurrences of a connection timeout
        "connection_timeouts": [Number: integer],
        # [No description provided]
         "pending_request_timeouts": [Number: integer],
        # Occurrences of requests that timed out waiting for a connection
        "request_timeouts": [Number: integer]
    }
}

Databases

Mechanisms

Users

Extensions

SQL Driver: Cassandra ​

Settings ​

cassandra_application_name

cassandra_application_version

cassandra_client_id

cassandra_connect_timeout

cassandra_connections_per_host

cassandra_debug_queries

cassandra_delete_consistency

cassandra_delete_fallback_consistency

cassandra_execution_retry_interval

cassandra_execution_retry_times

cassandra_heartbeat_interval

cassandra_hosts

cassandra_idle_timeout

cassandra_io_thread_count

cassandra_keyspace

cassandra_latency_aware_exclusion_threshold

cassandra_latency_aware_min_measured

cassandra_latency_aware_retry_period

cassandra_latency_aware_routing

cassandra_latency_aware_scale

cassandra_latency_aware_update_rate

cassandra_local_datacenter

cassandra_log_level

cassandra_log_retries

cassandra_logged_batches

cassandra_metrics_path

cassandra_page_size

cassandra_password

cassandra_port

cassandra_protocol_version

cassandra_read_consistency

cassandra_read_fallback_consistency

cassandra_reconnect_base_delay

cassandra_reconnect_max_delay

cassandra_reconnect_policy

cassandra_request_queue_size

cassandra_request_timeout

cassandra_source_ip

cassandra_ssl

cassandra_tcp_keepalive

cassandra_token_aware_routing

cassandra_token_aware_shuffle_replicas

cassandra_user

cassandra_warn_timeout

cassandra_write_consistency

cassandra_write_fallback_consistency

dns_client_timeout

SSL/TLS Settings ​

ssl_client_ca_file

ssl_client_cert_file

ssl_client_key_file

ssl_client_key_password

ssl_client_require_valid_cert

Local Datacenter ​

Consistency ​

Read Consistency ​

any ​

local-serial ​

serial ​

one ​

two ​

three ​

local-quorum ​

quorum ​

each-quorum ​

all ​

Write/Delete Consistency ​

any ​

local-serial ​

serial ​

one ​

two ​

three ​

local-quorum ​

SQL Driver: Cassandra

Settings

`cassandra_application_name`

`cassandra_application_version`

`cassandra_client_id`

`cassandra_connect_timeout`

`cassandra_connections_per_host`

`cassandra_debug_queries`

`cassandra_delete_consistency`

`cassandra_delete_fallback_consistency`

`cassandra_execution_retry_interval`

`cassandra_execution_retry_times`

`cassandra_heartbeat_interval`

`cassandra_hosts`

`cassandra_idle_timeout`

`cassandra_io_thread_count`

`cassandra_keyspace`

`cassandra_latency_aware_exclusion_threshold`

`cassandra_latency_aware_min_measured`

`cassandra_latency_aware_retry_period`

`cassandra_latency_aware_routing`

`cassandra_latency_aware_scale`

`cassandra_latency_aware_update_rate`

`cassandra_local_datacenter`

`cassandra_log_level`

`cassandra_log_retries`

`cassandra_logged_batches`

`cassandra_metrics_path`

`cassandra_page_size`

`cassandra_password`

`cassandra_port`

`cassandra_protocol_version`

`cassandra_read_consistency`

`cassandra_read_fallback_consistency`

`cassandra_reconnect_base_delay`

`cassandra_reconnect_max_delay`

`cassandra_reconnect_policy`

`cassandra_request_queue_size`

`cassandra_request_timeout`

`cassandra_source_ip`

`cassandra_ssl`

`cassandra_tcp_keepalive`

`cassandra_token_aware_routing`

`cassandra_token_aware_shuffle_replicas`

`cassandra_user`

`cassandra_warn_timeout`

`cassandra_write_consistency`

`cassandra_write_fallback_consistency`

`dns_client_timeout`

SSL/TLS Settings

`ssl_client_ca_file`

`ssl_client_cert_file`

`ssl_client_key_file`

`ssl_client_key_password`

`ssl_client_require_valid_cert`

Local Datacenter

Consistency

Read Consistency

`any`

`local-serial`

`serial`

`one`

`two`

`three`

`local-quorum`

`quorum`

`each-quorum`

`all`

Write/Delete Consistency

`any`

`local-serial`

`serial`

`one`

`two`

`three`

`local-quorum`

`quorum`

`each-quorum`

`all`

Metrics