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_connect_timeout`

Default	`5s`
Value	time (milliseconds)

Connection timeout.

`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

`cassandra_execution_retry_times`

Default	[None]
Value	time (milliseconds)

`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_routing`

Default	`no`
Value	boolean

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

`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_metrics`

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	[None]
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_request_timeout`

Default	`60s`
Value	time (milliseconds)

How long to wait for a query to finish.

`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_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.

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 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.

`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?

Consistency

Consistency levels in Cassandra can be configured to manage availability versus data accuracy.

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

Formats

Extensions

SQL Driver: Cassandra ​

Settings ​

cassandra_connect_timeout

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_routing

cassandra_log_level

cassandra_log_retries

cassandra_metrics

cassandra_page_size

cassandra_password

cassandra_port

cassandra_protocol_version

cassandra_read_consistency

cassandra_read_fallback_consistency

cassandra_request_timeout

cassandra_ssl

cassandra_user

cassandra_warn_timeout

cassandra_write_consistency

cassandra_write_fallback_consistency

SSL/TLS Settings ​

ssl_client_ca_file

ssl_client_cert_file

ssl_client_key_file

ssl_client_key_password

ssl_client_require_valid_cert

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 ​

SQL Driver: Cassandra

Settings

`cassandra_connect_timeout`

`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_routing`

`cassandra_log_level`

`cassandra_log_retries`

`cassandra_metrics`

`cassandra_page_size`

`cassandra_password`

`cassandra_port`

`cassandra_protocol_version`

`cassandra_read_consistency`

`cassandra_read_fallback_consistency`

`cassandra_request_timeout`

`cassandra_ssl`

`cassandra_user`

`cassandra_warn_timeout`

`cassandra_write_consistency`

`cassandra_write_fallback_consistency`

SSL/TLS Settings

`ssl_client_ca_file`

`ssl_client_cert_file`

`ssl_client_key_file`

`ssl_client_key_password`

`ssl_client_require_valid_cert`

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