Cassandra’s binary protocol supports [SASL]-based authentication. To enable it, use

[Cluster.Builder.withCredentials] when building your `Cluster` instance to provide the credentials

you wish to authenticate with:

Cluster.builder()

.withCredentials("bob", "mypassword")

.build();

This is a shortcut for using [PlainTextAuthProvider] for simple username/password authentication

(intended to work with the server-side `PasswordAuthenticator`). This may alternatively be

provided using the [Cluster.Builder.withAuthProvider] method:

Cluster.builder()

.withAuthProvider(new PlainTextAuthProvider("bob", "mypassword"))

.build();

Authentication must be configured before opening a session, it cannot be changed at runtime.

You can also write your own provider; it must implement [AuthProvider].

[SASL]: https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer

[Cluster.Builder.withCredentials]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/Cluster.Builder.html#withCredentials-java.lang.String-java.lang.String-

[AuthProvider]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/AuthProvider.html

[Cluster.Builder.withAuthProvider]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/Cluster.Builder.html#withAuthProvider-com.datastax.driver.core.AuthProvider-

[PlainTextAuthProvider]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/PlainTextAuthProvider.html

The control connection is a dedicated connection used for administrative tasks:

* querying system tables to learn about the cluster's topology and

[schema](../metadata/#schema-metadata);

* checking [schema agreement](../metadata/#schema-agreement);

* reacting to server events, which are used to notify the driver of external topology or schema

changes.

When the driver starts, the control connection is established to the first contacted node. If that

node goes down, a [reconnection](../reconnection/) is started to find another node; it is governed

by the same policy as regular connections and tries the nodes according to a query plan from the

[load balancing policy](../load_balancing/).

The control connection is managed independently from [regular pooled connections](../pooling/), and

used exclusively for administrative requests. It is included in [Session.State.getOpenConnections],

as well as the `open-connections` [metric](../metrics); for example, if you've configured a pool

size of 2, the control node will have 3 connections.

[Session.State.getOpenConnections]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/Session.State.html#getOpenConnections-com.datastax.driver.core.Host-

If the driver loses a connection to a node, it tries to re-establish it according to a configurable

policy. This is used in two places:

* [connection pools](../pooling/): for each node, a session has a fixed-size pool of connections to

execute user requests. If a node is detected as down, a reconnection is started.

* [control connection](../control_connection/): a session uses a single connection to an arbitrary

node for administrative requests. If that connection goes down, a reconnection gets started; each

attempt iterates through all active nodes until one of them accepts a connection. This goes on

until we have a control node again.

[ReconnectionPolicy] controls the interval between each attempt. The policy to use may be

provided using [Cluster.Builder.withReconnectionPolicy]. For example, the following configures

an [ExponentialReconnectionPolicy] with a base delay of 1 second, and a max delay of 10 minutes

(this is the default behavior).

Cluster.builder()

.withReconnectionPolicy(new ExponentialReconnectionPolicy(1000, 10 * 60 * 1000))

.build();

[ConstantReconnectionPolicy] uses the same delay every time, regardless of the

previous number of attempts.

You can also write your own policy; it must implement [ReconnectionPolicy].

For best results, use reasonable values: very low values (for example a constant delay of 10

milliseconds) will quickly saturate your system.

[ReconnectionPolicy]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/policies/ReconnectionPolicy.html

[Cluster.Builder.withReconnectionPolicy]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/Cluster.Builder.html#withReconnectionPolicy-com.datastax.driver.core.policies.ReconnectionPolicy-

[ExponentialReconnectionPolicy]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/policies/ExponentialReconnectionPolicy.html

[ConstantReconnectionPolicy]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/policies/ConstantReconnectionPolicy.html

Use [BatchStatement] to execute a set of queries as a single operation (refer to

[Batching inserts, updates and deletes][batch_dse] to understand how to use batching effectively):

PreparedStatement preparedInsertExpense =

session.prepare(

"INSERT INTO cyclist_expenses (cyclist_name, expense_id, amount, description, paid) "

+ "VALUES (:name, :id, :amount, :description, :paid)");

SimpleStatement simpleInsertBalance =

new SimpleStatement("INSERT INTO cyclist_expenses (cyclist_name, balance) VALUES (?, 0) IF NOT EXISTS",

"Vera ADRIAN");

BatchStatement batch = new BatchStatement(BatchStatement.Type.UNLOGGED)

.add(simpleInsertBalance)

.add(preparedInsertExpense.bind("Vera ADRIAN", 1, 7.95f, "Breakfast", false));

session.execute(batch);

As shown in the examples above, batches can contain any combination of simple statements and bound

statements. A given batch can contain at most 65536 statements. Past this limit, addition methods

throw an `IllegalStateException`.

By default, batches are configured as [LOGGED]. This ensures that if any statement in the batch

succeeds, all will eventually succeed. Ensuring all queries in a batch succeed has a

performance cost. Consider using [UNLOGGED] as shown above if you do not need this capability.

Please note that the size of a batch is subject to the [batch_size_fail_threshold] configuration

option on the server.

In addition, simple statements with named parameters are currently not supported in batches (this is

due to a [protocol limitation][CASSANDRA-10246] that will be fixed in a future version). If you try

to execute such a batch, an `IllegalArgumentException` is thrown.

[BatchStatement]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/BatchStatement.html

[batch_dse]: http://docs.datastax.com/en/dse/5.1/cql/cql/cql_using/useBatch.html

[LOGGED]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/BatchStatement.Type.html#LOGGED

[UNLOGGED]: https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/core/BatchStatement.Type.html#UNLOGGED

[batch_size_fail_threshold]: https://docs.datastax.com/en/cassandra/3.x/cassandra/configuration/configCassandra_yaml.html#configCassandra_yaml__batch_size_fail_threshold_in_kb

[CASSANDRA-10246]: https://issues.apache.org/jira/browse/CASSANDRA-10246

[CQL user-defined types][cql_doc] are ordered sets of named, typed fields. They must be defined in a

keyspace:

And can then be used as a column type in tables, or a field type in other user-defined types in that

keyspace:

The driver maps UDT columns to the [UDTValue] class, which exposes getters and setters to access

individual fields by index or name:

Row row = session.execute("SELECT v FROM ks.collect_things WHERE pk = 1").one();

UDTValue udtValue = row.getUDTValue("v");

int a = udtValue.getInt(0);

String b = udtValue.getString("b");

Float c = udtValue.getFloat(2);

Statements may contain UDTs as bound values:

PreparedStatement ps =

session.prepare(

"INSERT INTO ks.collect_things (pk, ck1, ck2, v) VALUES (:pk, :ck1, :ck2, :v)");

To create a new UDT value, you must first have a reference to its [UserType]. There are

various ways to get it:

* from the statement's metadata

```java

UserType udt = (UserType) ps.getVariables().getType("v");

```

* from the driver's [schema metadata](../metadata/#schema-metadata):

Note that the driver's official API does not expose a way to build [UserType] instances manually.

This is because the type's internal definition must precisely match the database schema;

if it doesn't (for example if the fields are not in the same order), you run the risk of inserting

corrupt data, that you won't be able to read back.