# Scylla Java Driver for Scylla and Apache Cassandra®

[![Maven Central](https://img.shields.io/maven-central/v/com.scylladb/scylla-driver-core?versionPrefix=3.12.1)](https://central.sonatype.com/artifact/com.scylladb/scylla-driver-core)

> **Deprecation Notice:** Scylla Java Driver 3.x is now **deprecated** and has
> entered **maintenance mode**. Only critical bug fixes will be accepted.
> For new projects and active development, please migrate to
> [Scylla Java Driver 4.x](https://github.com/scylladb/java-driver/tree/scylla-4.x)
> ([documentation](https://java-driver.docs.scylladb.com/scylla-3.12.1.x/)).

*If you’re reading this on github.com, please note that this is the readme
for the development version and that some features described here might
not yet have been released. You can find the documentation for the latest
version through the [Java driver
docs](https://docs.scylladb.com/using-scylla/scylla-java-driver/) or via the release tags,
[e.g.
3.12.1.0](https://github.com/scylladb/java-driver/releases/tag/3.12.1.0).*

A modern, [feature-rich]() and highly tunable Java client
library for Apache Cassandra (2.1+) and using exclusively Cassandra’s binary protocol
and Cassandra Query Language v3.

The Scylla Java Driver is a fork from [DataStax Java Driver](https://github.com/datastax/java-driver), including some non-breaking changes for Scylla optimization, with more updates planned.

**Features:**

* Like all Scylla Drivers, the Scylla Java Driver is **Shard Aware** and contains extensions for a `tokenAwareHostPolicy`.
  Using this policy, the driver can select a connection to a particular shard based on the shard’s token.
  As a result, latency is significantly reduced because there is no need to pass data between the shards.
* **Lightweight Transaction (LWT) Optimization**:
  - When using `TokenAwarePolicy` with prepared statements, LWT queries automatically use replica-only routing,
    prioritizing local datacenter replicas to minimize coordinator forwarding overhead and reduce contention during
    Paxos consensus phases.
  - When using `RackAwareRoundRobinPolicy`, LWT queries skip local rack prioritization and distribute evenly across
    all hosts in the local datacenter. This avoids creating rack-level hotspots during Paxos consensus, which can
    lead to increased contention and reduced throughput. The local datacenter is still prioritized over remote
    datacenters to maintain low latency.
  - When using `LatencyAwarePolicy`, LWT queries bypass latency-based reordering to preserve deterministic replica
    selection. This ensures that LWT routing assumptions (such as consistent coordinator selection for optimal Paxos
    performance) are maintained throughout the policy chain.
* [Sync]() and [Async]() API
* [Simple](), [Prepared](), and [Batch]()
  statements
* Asynchronous IO, parallel execution, request pipelining
* [Connection pooling]()
* Auto node discovery
* Automatic reconnection
* Configurable [load balancing]() and [retry policies]()
* Works with any cluster size
* [Query builder]()
* [Object mapper]()

The driver architecture is based on layers. At the bottom lies the driver core.
This core handles everything related to the connections to a Cassandra
cluster (for example, connection pool, discovering new nodes, etc.) and exposes a simple,
relatively low-level API on top of which higher level layers can be built.

The driver contains the following modules:

- driver-core: the core layer.
- driver-mapping: the object mapper.
- driver-extras: optional features for the Java Driver.
- driver-examples: example applications using the other modules which are
  only meant for demonstration purposes.
- driver-tests: tests for the java-driver.

**Useful links:**

- SCYLLA UNIVERSITY JAVA [CLASS](https://university.scylladb.com/courses/using-scylla-drivers/lessons/coding-with-java-part-1/)
- DOCS: the [manual]() has quick
  start material and technical details about the driver and its features.
- GITHUB REPOSITORY: https://github.com/scylladb/java-driver
- [changelog]()

## Getting the driver

The last release of the driver is available on Maven Central. You can install
it in your application using the following Maven dependency

```xml
<dependency>
  <groupId>com.scylladb</groupId>
  <artifactId>scylla-driver-core</artifactId>
  <version>3.12.1.0</version>
</dependency>
```

Note that the object mapper is published as a separate artifact:

```xml
<dependency>
  <groupId>com.scylladb</groupId>
  <artifactId>scylla-driver-mapping</artifactId>
  <version>3.12.1.0</version>
</dependency>
```

The ‘extras’ module is also published as a separate artifact:

```xml
<dependency>
  <groupId>com.scylladb</groupId>
  <artifactId>scylla-driver-extras</artifactId>
  <version>3.12.1.0</version>
</dependency>
```

We also provide a [shaded JAR]()
to avoid the explicit dependency to Netty.

On Fedora 30 or later you may need to install dependencies for `netty-tcnative-boringssl-static`
by running `dnf -y install libxcrypt-compat`

## Compatibility

The Java client driver 3.12.1.0 ([branch scylla-3.x](https://github.com/scylladb/java-driver/tree/scylla-3.x)) is compatible with
Scylla and Apache Cassandra 2.1, 2.2, 3.0+.

UDT and tuple support is available only when using Apache Cassandra 2.1 or higher.

Other features are available only when using Apache Cassandra 2.0 or higher (e.g. result set paging,
[lightweight transactions](https://docs.scylladb.com/using-scylla/lwt/))

The java driver supports Java JDK versions 8 and above.

**Disclaimer**: Some *Scylla* products might partially work on
big-endian systems, but *Scylla* does not officially support these systems.

## Upgrading from previous versions

If you are upgrading from a previous version of the driver, be sure to have a look at
the [upgrade guide]().

## Migrating to Java Driver 4.x

The [4.x migration guide](https://java-driver.docs.scylladb.com/scylla-3.12.1.x/upgrade_guide/from_3x/)
covers the API changes in detail. The first thing to change is the dependency: the artifacts are
renamed, while the `com.scylladb` group id stays the same.

| Driver 3.x              | Driver 4.x                                                                                      |
|-------------------------|-------------------------------------------------------------------------------------------------|
| `scylla-driver-core`    | `java-driver-core`, plus `java-driver-query-builder` if you use the query builder               |
| `scylla-driver-mapping` | `java-driver-mapper-runtime`, plus the `java-driver-mapper-processor` annotation processor      |
| `scylla-driver-extras`  | no counterpart; its codecs are either native to 4.x core or covered by its custom-codec support |

All four 4.x artifacts are published under `com.scylladb` from **4.7.2.0** onwards; there is no
earlier 4.x release under this group id.

## License

© DataStax, Inc.
© ScyllaDB, all rights reserved.

© 2016, The Apache Software Foundation.

Apache®, Apache Cassandra®, Cassandra®, the Apache feather logo and the Apache Cassandra®
Eye logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States
and/or other countries.
No endorsement by The Apache Software Foundation is implied by the use of these marks.

Binary artifacts of this product bundle Java Native Runtime libraries, which is available under the Eclipse Public License version 2.0.