# Apache Cassandra Java Driver Setup and Modules

> The Apache Cassandra Java Driver is a Java client for Cassandra-compatible databases, using Cassandra's binary protocol and CQL v3. Its separate Maven modules cover core access, query construction, and mapper runtime support.

**apache/cassandra-java-driver** — Java Driver for Apache Cassandra®

- Repository: https://github.com/apache/cassandra-java-driver
- Website: https://cassandra.apache.org/
- Stars: 1,383 · Forks: 891
- Language: Java
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/apache-cassandra-java-driver

## Where the Apache Cassandra Java Driver Fits

The Java Driver for Apache Cassandra is intended for Java applications that communicate with Apache Cassandra 2.1 or later, DataStax Enterprise 4.7 or later, and DataStax Astra. The README specifies that the client communicates through Cassandra's binary protocol and uses Cassandra Query Language, or CQL, version 3. It is a client library rather than a database server, migration utility, schema manager, or query execution environment.

This scope makes the project relevant when the application is written in Java and stores or retrieves data through CQL. The documented compatibility also covers DataStax offerings, but the driver is not presented as a client for databases that use a different wire protocol or query language. Its stated Java requirement is Java 8 or later.

That boundary matters during selection. A team can assess protocol compatibility when its service targets a supported Cassandra deployment. A team expecting SQL compatibility, ORM support for unrelated databases, Java 7 compatibility, or binary compatibility with an older driver line needs to resolve that mismatch first. Driver version, database version, and Java runtime should be considered as separate compatibility decisions rather than inferred from the project's name.

## Core, Query Builder, and Mapper Artifacts

The driver publishes its artifacts in Maven Central under the group ID `org.apache.cassandra`. Each artifact name starts with `java-driver-`. The `java-driver-core` module is the main driver dependency, `java-driver-query-builder` supplies the query builder, and `java-driver-mapper-runtime` supplies the mapper runtime.

The repository layout reflects that division. It contains separate top-level directories for `core/`, `query-builder/`, `mapper-runtime/`, and `mapper-processor/`. Other entries include shaded core and Guava areas, metrics, OSGi tests, integration tests, performance work, distribution files, and examples. This is a multi-module build rather than one Java artifact with every optional feature in the same dependency.

The most important dependency decision is whether an application needs more than `java-driver-core`. The README states directly that the query builder is now a separate artifact. A project using that feature must declare `java-driver-query-builder`. A project relying on mapper runtime behavior must likewise declare `java-driver-mapper-runtime`. The presence of `mapper-processor/` indicates a related processor component, but the README does not provide its annotation-processing configuration. Engineers should consult the mapper manual before adding that component.

The repository also contains a `bom/` directory, but the README does not give its coordinates or say that using a BOM is mandatory. The same caution applies to the examples. An `examples/pom.xml` exists, but the README gives no command for running those examples, so the example build cannot be treated as a documented installation procedure.

## Installing the Core Driver with Maven

The README documents Maven Central as the distribution location for the driver. A Java service that needs the core client declares `java-driver-core` under group ID `org.apache.cassandra`. The documented dependency uses `${driver.version}`, so the build must define that property according to the release being targeted.

```xml
<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>${driver.version}</version>
</dependency>
```

This is the first documented installation step for a new application. It adds the client library to the build but does not configure a Cassandra endpoint or execute a query. The README does not provide a `mvn` command for creating a project, connecting to a node, or running an example, so the next verified step is the core manual linked by the repository.

Use the documentation associated with the release tag rather than relying on the default branch for release-specific behavior. The README warns that the repository describes a development version and that some features may not yet have been released.

## Adding the Query Builder for CQL Construction

The query builder is not bundled into the core artifact. Projects that use it must add the separate Maven dependency shown by the README. The shared `${driver.version}` property keeps the query-builder version aligned with the core driver when the build defines one version for both modules.

```xml
<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-query-builder</artifactId>
  <version>${driver.version}</version>
</dependency>
```

The README does not give a complete query-builder program or a command for running one, so this article does not invent an API example. The linked query-builder manual is the documented source for constructor syntax, supported CQL operations, and integration details. Application code that imports query-builder classes should use the query-builder manual alongside the core manual rather than infer an API from the artifact name.

The separate artifact is a deliberate dependency choice. An application that does not use query building does not need to declare it merely because it uses `java-driver-core`.

## Adding the Mapper Runtime

Applications using mapper runtime features need the separately published `java-driver-mapper-runtime` artifact. The README lists it as a Maven dependency under the same `org.apache.cassandra` group and with the same `${driver.version}` property.

```xml
<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-mapper-runtime</artifactId>
  <version>${driver.version}</version>
</dependency>
```

The repository includes a `mapper-processor/` directory as well as a mapper runtime artifact, but the README does not document the processor's dependency or annotation-processing setup. The mapper manual is therefore the appropriate place to confirm how the processor is integrated. The README does not state that `java-driver-core` automatically enables mapper processing.

This distinction affects classpath planning and build configuration. Code that relies on mapper APIs needs the runtime artifact, while build-time processor configuration must follow the version-specific manual. The artifact declaration above is the only mapper setup shown by the README.

## Binary Protocol, CQL, and Client Data Flow

The documented client-server boundary is precise: the library uses Cassandra's binary protocol and CQL v3. In a Java service, application code consumes the selected driver modules at build time, the core library handles client communication, and supported Cassandra endpoints receive protocol requests expressed through CQL. The query-builder module assists query construction when declared. The mapper runtime is another separately published client component.

The README does not expose session construction, contact-point configuration, connection-pool controls, retry behavior, load-balancing policy, metadata refresh, asynchronous APIs, or transaction handling. Those details cannot be inferred from the high-level project description. They should be checked in the core manual and API documentation linked by the repository for the selected driver release.

The optional module boundaries affect application design. Code that imports query-builder or mapper APIs cannot rely on those classes merely because `java-driver-core` is present. The README explicitly resolves this for the query builder by stating that its artifact must be added. It does not provide the same detailed setup guidance for mapper processing, so an annotation-processing configuration should be copied from the mapper manual rather than reconstructed from directory names.

None of these modules replaces a Cassandra deployment. A service using this driver still needs a compatible database endpoint and must construct requests using CQL v3. The project solves the Java client integration problem, not the provisioning and operation of Cassandra itself.

## Driver 4 Migration and Release Line Constraints

Java Driver 4 is not binary compatible with earlier driver versions. This is the clearest upgrade constraint stated by the README. Many concepts remain unchanged, and developers who used the 2.x and 3.x lines may recognize the API structure. That similarity does not establish binary compatibility or guarantee that existing dependency combinations will load without change.

An existing Java client therefore has a concrete decision to make before replacing its driver. It must determine whether the application can update all affected driver modules together or needs to preserve binaries from an earlier line. The README points migration work to `upgrade_guide/README.md`. It does not document an automated migration command, compatibility flag, or staged deployment procedure.

Release selection is another constraint. The repository records releases `4.19.4` and `3.13.0` on 2026-10-14, plus `4.19.3` on 2026-06-04. Their coexistence shows that more than one release line receives published versions. The README does not define support windows or defect-response commitments for those lines, so the newest numeric version should not be assumed to fit every build.

The README on `trunk` describes a development version and warns that some features may not yet have been released. It directs readers to release tags for documentation tied to a published version. Production setup should use the documentation and configuration examples associated with its chosen release tag rather than assuming that everything described on the default branch exists in the selected artifact.

## Maintenance, Licensing, and Distribution Constraints

The repository is not archived, and its last push was on 2026-09-25. Releases `4.19.4` and `3.13.0` were published on 2026-10-14. These are concrete signs of recent repository and release activity. The README does not define how long each release line will be maintained, how quickly defects will be addressed, or which patch releases receive compatibility fixes.

The project uses the Apache License, Version 2.0. The README also states that binary artifacts bundle Java Native Runtime libraries available under the Eclipse Public License version 2.0. Repository files include `LICENSE`, `LICENSE_binary`, `NOTICE.txt`, and `NOTICE_binary.txt`, indicating that source and binary distribution terms are tracked separately. A team redistributing driver binaries should inspect the files attached to the selected release and satisfy the applicable notices and license conditions. This identifies the repository's licensing structure without interpreting legal obligations.

A practical limitation is the need to verify compatibility at several levels: Java version, driver release line, Cassandra-compatible target, and optional module selection. The README gives minimum compatibility ranges, but it does not enumerate every tested patch release or every module constraint. A broad range such as Apache Cassandra 2.1 and higher should not substitute for checking the documentation attached to the exact driver version.

The driver is the wrong choice when the service must run on Java 7, communicate with a database through a non-Cassandra protocol, or remain binary compatible with Driver 3. It is also a poor fit for a Java application that expects the mapper processor or query builder to arrive automatically with the core artifact, since both are published separately.

## Conclusion

Java teams operating Cassandra 2.1+ through Java 8 or later can adopt the driver when binary-protocol access and CQL v3 fit the service. Projects using the query builder or mapper must add separate artifacts, while Driver 4 adopters must accept binary incompatibility with earlier lines. Verify the selected release tag, required module, database compatibility, and upgrade guide before changing a production build.

## FAQ

### Which Java versions are supported by the Apache Cassandra Java Driver?

The README states that the driver requires Java 8 or higher.

### Which Apache Cassandra versions are compatible with the Java Driver?

The README documents compatibility with Apache Cassandra 2.1 and higher. It also lists DataStax Enterprise 4.7 and higher and DataStax Astra.

### Does the Apache Cassandra Java Driver require a separate Maven artifact for its query builder?

Yes. The query builder is published as `java-driver-query-builder`, so projects using it must add that dependency in addition to the core module.

## Sources

- [apache/cassandra-java-driver on GitHub](https://github.com/apache/cassandra-java-driver)
- [License: Apache-2.0](https://github.com/apache/cassandra-java-driver/blob/trunk/LICENSE)
- [Project website](https://cassandra.apache.org/)
- [README](https://github.com/apache/cassandra-java-driver/blob/trunk/README.md)
- [Releases](https://github.com/apache/cassandra-java-driver/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apache-cassandra-java-driver