# Reference configuration for the DataStax Java driver for Apache Cassandra®.

#

# Unless you use a custom mechanism to load your configuration (see DriverContext), all the values

# declared here will be used as defaults if you don't override them in your own `application.conf`.

#

# Unless explicitly stated otherwise:

# - options are required;

# - they can not be overridden in a profile;

# - runtime changes are ignored.

#

# This file is in HOCON format, see https://github.com/typesafehub/config/blob/master/HOCON.md.

datastax-java-driver {

# The contact points to use for the initial connection to the cluster.

#

# These are addresses of Cassandra nodes that the driver uses to discover the cluster topology.

# Only one contact point is required (the driver will retrieve the address of the other nodes

# automatically), but it is usually a good idea to provide more than one contact point, because

# if that single contact point is unavailable, the driver cannot initialize itself correctly.

#

# This must be a list of strings with each contact point specified as "host:port". If the host is

# a DNS name that resolves to multiple A-records, all the corresponding addresses will be used.

# Do not use "localhost" as the host name (since it resolves to both IPv4 and IPv6 addresses on

# some platforms).

#

# Note that the current version of Cassandra (3.11) requires all nodes in a cluster to share the

# same port.

#

# This option is not required. Contact points can also be provided programmatically when you build

# a cluster instance. If both are specified, they will be merged.

// contact-points = [ "127.0.0.1:9042", "127.0.0.2:9042" ]

protocol {

# The native protocol version to use.

#

# This option is not required. If it is absent, the driver looks up the versions of the nodes at

# startup (by default in system.peers.release_version), and chooses the highest common protocol

# version. For example, if you have a mixed cluster with Apache Cassandra 2.1 nodes (protocol

# v3) and Apache Cassandra 3.0 nodes (protocol v3 and v4), then protocol v3 is chosen. If the

# nodes don't have a common protocol version, initialization fails.

#

# If this option is set, then the given version will be used for all connections, without any

# negotiation or downgrading. If any of the contact points doesn't support it, it will be

# skipped.

#

# Once the protocol version is set, it can't change for the rest of the driver's lifetime; if an

# incompatible node joins the cluster later, connection will fail and the driver will force it

# down (i.e. never try to connect to it again).

#

# You can check the actual version at runtime with Cluster.getContext().protocolVersion().

// version = V4

# The maximum length of the frames supported by the driver. Beyond that limit, requests will

# fail with an exception

#

# This option can be changed at runtime, the new value will be used for new connections created

# after the change.

max-frame-length = 256 MB

# The components that handles authentication on each new connection.

auth-provider {

# This property is optional; if it is not present, no authentication will occur.

// class = com.datastax.oss.driver.api.core.auth.PlainTextAuthProvider

# Sample configuration for the plain-text provider:

// username = cassandra

// password = cassandra

}

}

# A name that uniquely identifies the driver instance created from this configuration. This is

# used as a prefix for log messages and metrics.

# This option is not required; if it is not specified, the driver will generate an identifier

# composed of the letter 'c' followed by an incrementing counter.

# If you provide a different value, try to keep it short to keep the logs readable. Also, make

# sure it is unique: reusing the same value will not break the driver, but it will mix up the logs

# and metrics.

// cluster-name = my_cluster

# How often the driver tries to reload the configuration.

# This option is required, except if you use a different config loader than the driver's built-in

# one. Runtime changes are taken into account.

# To disable periodic reloading, set this to 0.

config-reload-interval = 5 minutes

load-balancing-policy {

class = com.datastax.oss.driver.api.core.loadbalancing.RoundRobinLoadBalancingPolicy

}

connection {

# The timeout to use for internal queries that run as part of the initialization process, just

# after we open a connection. If this timeout fires, the initialization of the connection will

# fail. If this is the first connection ever, the driver will fail to initialize as well,

# otherwise it will retry the connection later.

#

# This option can be changed at runtime, the new value will be used for new connections created

# after the change.

init-query-timeout = 500 milliseconds

# The timeout to use when the driver changes the keyspace on a connection at runtime (this

# happens when the client issues a `USE ...` query, and all connections belonging to the

# current session need to be updated).

#

# This option can be changed at runtime, the new value will be used for new connections created

# after the change.

set-keyspace-timeout = ${datastax-java-driver.connection.init-query-timeout}

# The maximum number of requests that can be executed concurrently on a connection. This must be

# between 1 and 32768.

#

# This option can be changed at runtime, the new value will be used for new connections created

# after the change.

max-requests-per-connection = 32768

# The maximum number of "orphaned" requests before a connection gets closed automatically.

#

# Sometimes the driver writes to a node but stops listening for a response (for example if the

# request timed out, or was completed by another node). But we can't safely reuse the stream id

# on this connection until we know for sure that the server is done with it. Therefore the id is

# marked as "orphaned" until we get a response from the node.

#

# If the response never comes (or is lost because of a network issue), orphaned ids can

# accumulate over time, eventually affecting the connection's throughput. So we monitor them and

# close the connection above a given threshold (the pool will replace it).

#

# This option can be changed at runtime, the new value will be used for new connections created

# after the change.

max-orphan-requests = 24576

heartbeat {

# The heartbeat interval. If a connection stays idle for that duration (no reads), the driver

# sends a dummy message on it to make sure it's still alive. If not, the connection is

# trashed and replaced.

#

# This option can be changed at runtime, the new value will be used for new connections

# created after the change.

interval = 30 seconds

# How long the driver waits for the response to a heartbeat. If this timeout fires, the

# heartbeat is considered failed.

#

# This option can be changed at runtime, the new value will be used for heartbeat queries

# issued after the change.

timeout = ${datastax-java-driver.connection.init-query-timeout}

}

reconnection-policy {

class = com.datastax.oss.driver.api.core.connection.ExponentialReconnectionPolicy

base-delay = 1 second

max-delay = 60 seconds

}

control-connection {

# How long the driver waits for responses to control queries (e.g. fetching the list of

# nodes, refreshing the schema).

timeout = 500 milliseconds

# The page size used for control queries. If a query returns more than this number of

# results, it will be fetched in multiple requests.

page-size = 5000

}

# The component that coalesces writes on the connections.

# This is exposed mainly to facilitate tuning during development. You shouldn't have to adjust

# this.

coalescer {

class = com.datastax.oss.driver.internal.core.channel.DefaultWriteCoalescer

# How many times the coalescer is allowed to reschedule itself when it did no work.

max-runs-with-no-work = 5

# The reschedule interval.

reschedule-interval = 10 microseconds

}

# The driver maintains a connection pool to each node, according to the distance assigned to it

# by the load balancing policy. If the distance is IGNORED, no connections are maintained.

pool {

local {

# The number of connections in the pool.

#

# This option can be changed at runtime; when the change is detected, all active pools will

# adjust their size.

size = 1

}

remote {

size = 1

}

}

}

request {

# How long the driver waits for a request to complete. This is a global limit on the duration

# of a session.execute() call, including any internal retries the driver might do.

#

# This option can be changed at runtime, the new value will be used for requests issued after

# the change. It can be overridden in a profile.

timeout = 500 milliseconds

# The consistency level.

#

# This option can be changed at runtime, the new value will be used for requests issued after

# the change. It can be overridden in a profile.

consistency = LOCAL_ONE

# The page size. This controls how many rows will be retrieved simultaneously in a single

# network roundtrip (the goal being to avoid loading too many results in memory at the same

# time). If there are more results, additional requests will be used to retrieve them (either

# automatically if you iterate with the sync API, or explicitly with the async API's

# fetchNextPage method).

# If the value is 0 or negative, it will be ignored and the request will not be paged.

#

# This option can be changed at runtime, the new value will be used for requests issued after

# the change. It can be overridden in a profile.

page-size = 5000

# The serial consistency level.

# The allowed values are SERIAL and LOCAL_SERIAL.

#

# This option can be changed at runtime, the new value will be used for requests issued after

# the change. It can be overridden in a profile.

serial-consistency = SERIAL

# Whether a warning is logged when a request (such as a CQL `USE ...`) changes the active

# keyspace.

# Switching keyspace at runtime is highly discouraged, because it is inherently unsafe (other

# requests expecting the old keyspace might be running concurrently), and may cause statements

# prepared before the change to fail.

# It should only be done in very specific use cases where there is only a single client thread

# executing synchronous queries (such as a cqlsh-like interpreter). In other cases, clients

# should prefix table names in their queries instead.

#

# Note that CASSANDRA-10145 (scheduled for C* 4.0) will introduce a per-request keyspace

# option as a workaround to this issue.

#

# This option can be changed at runtime, it will apply to keyspace switches occurring after the

# change.

warn-if-set-keyspace = true

# The default idempotence of a request, that will be used for all `Request` instances where

# `isIdempotent()` returns null.

#

# This option can be changed at runtime, the new value will be used for requests issued after

# the change. It can be overridden in a profile.

default-idempotence = false

# The generator that assigns a microsecond timestamp to each request.

timestamp-generator {

# The implementation to use. Built-in options are (all from the package

# com.datastax.oss.driver.api.core.time):

# - AtomicTimestampGenerator: timestamps are guaranteed to be unique across all client threads.

# - ThreadLocalTimestampGenerator: timestamps that are guaranteed to be unique within each

# thread only.

# - ServerSideTimestampGenerator: do not generate timestamps, let the server assign them.

class = com.datastax.oss.driver.api.core.time.AtomicTimestampGenerator

# To guarantee that queries are applied on the server in the same order as the client issued

# them, timestamps must be strictly increasing. But this means that, if the driver sends more

# than one query per microsecond, timestamps will drift in the future. While this could happen

# occasionally under high load, it should not be a regular occurrence. Therefore the built-in

# implementations log a warning to detect potential issues.

drift-warning {

# How far in the future timestamps are allowed to drift before the warning is logged.

# If it is undefined or set to 0, warnings are disabled.

threshold = 1 second

# How often the warning will be logged if timestamps keep drifting above the threshold.

interval = 10 seconds

}

# Whether to force the driver to use Java's millisecond-precision system clock.

# If this is false, the driver will try to access the microsecond-precision OS clock via native

# calls (and fallback to the Java one if the native calls fail).

# Unless you explicitly want to avoid native calls, there's no reason to change this.

force-java-clock = false

}

retry-policy {

class = com.datastax.oss.driver.api.core.retry.DefaultRetryPolicy

}

speculative-execution-policy {

# Don't schedule any speculative executions

class = com.datastax.oss.driver.api.core.specex.NoSpeculativeExecutionPolicy

# Schedule a fixed number of executions, with a fixed delay

// class = com.datastax.oss.driver.api.core.specex.ConstantSpeculativeExecutionPolicy

# The maximum number of executions (including the initial, non-speculative execution).

# This must be at least one.

// max-executions = 3

# The delay between each execution. 0 is allowed, and will result in all executions being sent

# simultaneously when the request starts.

# Note that sub-millisecond precision is not supported, any excess precision information will

# be dropped; in particular, delays of less than 1 millisecond are equivalent to 0.

# This must be positive or 0.

// delay = 100 milliseconds

}

}

prepared-statements {

# Whether `Session.prepare` calls should be sent to all nodes in the cluster.

#

# A request to prepare is handled in two steps:

# 1) send to a single node first (to rule out simple errors like malformed queries).

# 2) if step 1 succeeds, re-send to all other active nodes (i.e. not ignored by the load

# balancing policy).

# This option controls whether step 2 is executed.

#

# The reason why you might want to disable it is to optimize network usage if you have a large

# number of clients preparing the same set of statements at startup. If your load balancing

# policy distributes queries randomly, each client will pick a different host to prepare its

# statements, and on the whole each host has a good chance of having been hit by at least one

# client for each statement.

# On the other hand, if that assumption turns out to be wrong and one host hasn't prepared a

# given statement, it needs to be re-prepared on the fly the first time it gets executed; this

# causes a performance penalty (one extra roundtrip to resend the query to prepare, and another

# to retry the execution).

#

# This option can be changed at runtime, the new value will be used for prepares issued after

# the change. It can be overridden in a profile.

prepare-on-all-nodes = true

# How the driver replicates prepared statements on a node that just came back up or joined the

# cluster.

# These options can be changed at runtime, the new values will be used for prepares issued after

# the change. However they can not be overridden in a profile.

reprepare-on-up {

# Whether the driver tries to prepare on new nodes at all.

#

# The reason why you might want to disable it is to optimize reconnection time when you

# believe nodes often get marked down because of temporary network issues, rather than the

# node really crashing. In that case, the node still has prepared statements in its cache when

# the driver reconnects, so re-preparing is redundant.

#

# On the other hand, if that assumption turns out to be wrong and the node had really

# restarted, its prepared statement cache is empty (before CASSANDRA-8831), and statements

# need to be re-prepared on the fly the first time they get executed; this causes a

# performance penalty (one extra roundtrip to resend the query to prepare, and another to

# retry the execution).

enabled = true

# Whether to check `system.prepared_statements` on the target node before repreparing.

#

# This table exists since CASSANDRA-8831 (merged in 3.10). It stores the statements already

# prepared on the node, and preserves them across restarts.

#

# Checking the table first avoids repreparing unnecessarily, but the cost of the query is not

# always worth the improvement, especially if the number of statements is low.

#

# If the table does not exist, or the query fails for any other reason, the error is ignored

# and the driver proceeds to reprepare statements according to the other parameters.

check-system-table = false

# The maximum number of statements that should be reprepared. 0 or a negative value means no

# limit.

max-statements = 0

# The maximum number of concurrent requests when repreparing.

max-parallelism = 100

# The request timeout. This applies both to querying the system.prepared_statements table (if

# relevant), and the prepare requests themselves.

timeout = ${datastax-java-driver.connection.init-query-timeout}

}

}

metadata {

# Topology events are external signals that inform the driver of the state of Cassandra nodes

# (by default, they correspond to gossip events received on the control connection).

# The debouncer helps smoothen out oscillations if conflicting events are sent out in short

# bursts.

# Debouncing may be disabled by setting the window to 0 or max-events to 1 (this is not

# recommended).

topology-event-debouncer {

# How long the driver waits to propagate an event. If another event is received within that

# time, the window is reset and a batch of accumulated events will be delivered.

window = 1 second

# The maximum number of events that can accumulate. If this count is reached, the events are

# delivered immediately and the time window is reset. This avoids holding events indefinitely

# if the window keeps getting reset.

max-events = 20

}

schema {

# The timeout for the requests to the schema tables.

request-timeout = ${datastax-java-driver.request.timeout}

# The page size for the requests to the schema tables.

request-page-size = ${datastax-java-driver.request.page-size}

}

}

# The address translator to use to convert the addresses sent by Cassandra nodes into ones that

# the driver uses to connect.

# This is only needed if the nodes are not directly reachable from the driver (for example, the

# driver is in a different network region and needs to use a public IP, or it connects through

# a proxy).

address-translator {

# This default implementation always returns the same address unchanged.

class = com.datastax.oss.driver.api.core.addresstranslation.PassThroughAddressTranslator

}

# The SSL engine factory that will initialize an SSL engine for each new connection to a server.

ssl-engine-factory {

# This property is optional; if it is not present, SSL won't be activated.

// class = com.datastax.oss.driver.api.core.ssl.DefaultSslEngineFactory

# Sample configuration for the default SSL factory:

# The cipher suites to enable when creating an SSLEngine for a connection.

# This property is optional. If it is not present, the driver won't explicitly enable cipher

# suites on the engine, which according to the JDK documentations results in "a minimum

# quality of service".

// cipher-suites = [ "TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA" ]

}

# Options related to the Netty event loop groups used internally by the driver.

netty {

# The event loop group used for I/O operations (reading and writing to Cassandra nodes).

io-group {

# The number of threads.

# If this is set to 0, the driver will use `Runtime.getRuntime().availableProcessors() * 2`.

size = 0

# The options to shut down the event loop group gracefully when the driver closes. If a task

# gets submitted during the quiet period, it is accepted and the quiet period starts over. The

# timeout limits the overall shutdown time.

shutdown { quiet-period = 2, timeout = 15, unit = SECONDS }

}

# The event loop group used for admin tasks not related to request I/O (handle cluster events,

# refresh metadata, schedule reconnections, etc.)

admin-group {

size = 2

shutdown { quiet-period = 2, timeout = 15, unit = SECONDS }

}

}

profiles {

# This is where your custom profiles go, for example:

# olap {

# request.timeout = 5 seconds

# }

}

}