Skip to content
Execute cassandra statements from a vert.x module
Branch: develop
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
vertx-cassandra-mapping Updating develop poms back to pre merge state Feb 26, 2018
.gitignore Modified the EnvironmentCassandraConfigurator to use a specific delim… Mar 11, 2014
.travis.yml Give priority to config.json -> env vars -> zookeeper Dec 9, 2014


Talk to Cassandra asynchronously from vert.x and run your callbacks on the vert.x event loop.

Build Status Maven Central

Getting Started

Add a dependency to vertx-cassandra:

vertx-cassandra vert.x cassandra
3.6.0 3.5.0 3.11
3.4.0 3.3.0 3.7
3.2.0 3.2.0 3.0
3.1.0 3.1.0 2.1
3.0.0 3.0.0 2.1


The main configuration is via the normal config.json file for a Vert.x module.

    "cassandra": {
        "seeds": [<seeds>],
        "query": {
            "consistency_level": <string>,
            "serial_consistency_level": <string>,
            "fetch_size": <int>,
        "policies": {
            "load_balancing": {
                "name": "<lb_policy_name>",
            "reconnection": {
                "name": "<reconnect_policy_name>"
        "pooling": {
            "core_connections_per_host_local": <int>,
            "core_connections_per_host_remote": <int>,
            "heartbeat_interval_seconds": <int>,
            "idle_timeout_seconds": <int>,
            "max_queue_size": <int>,
            "max_requests_per_connection_local": <int>,
            "max_requests_per_connection_remote": <int>,
            "max_connections_per_host_local": <int>,
            "max_connections_per_host_remote": <int>,
            "new_connection_threshold_local": <int>,
            "new_connection_threshold_remote": <int>
        "socket": {
            "connect_timeout_millis": <int>,
            "read_timeout_millis": <int>,
            "keep_alive": <boolean>,
            "reuse_address": <boolean>,
            "receive_buffer_size": <int>,
            "send_buffer_size": <int>,
            "so_linger": <int>,
            "tcp_no_delay": <boolean>
  • seeds - an array of string seed IP or host names. At least one seed must be provided.
  • lb_policy_name - (optional) the load balancing policy name. The following values are accepted:
    • "DCAwareRoundRobinPolicy" - requires string field local_dc and optional numeric field used_hosts_per_remote_dc
    • Any FQCN such of a class that implements LoadBalancingPolicy
  • reconnect_policy_name - (optional) the reconnect policy name. The following values are accepted:
    • "constant"|"ConstantReconnectionPolicy" - creates a ConstantReconnectionPolicy policy. Expects additional numeric field delay in ms.
    • "exponential"|"ExponentialReconnectionPolicy" - creates an ExponentialReconnectionPolicy policy. Expects additional numeric fields base_delay and max_delay in ms.

Refer to the Cassandra Java driver documentation for a description of the remaining configuration options.

A sample config looks like:

    "cassandra": {
        "seeds": ["", ""],
        "policies": {
            "load_balancing": {
                "name": "DCAwareRoundRobinPolicy",
                "local_dc": "LOCAL1",
                "used_hosts_per_remote_dc": 1
            "reconnection": {
                "name": "exponential",
                "base_delay": 1000,
                "max_delay": 10000

Overriding with Environment Variables

It is possible to override the seeds and policies section of the configuration using environment variables. The two environment variables are:


So an example would be:


The latter, the CASSANDRA_LOCAL_DC, if used will override the entire load balancing section of the configuration, setting it to DCAwareRoundRobinPolicy, with a used_hosts value of 0 and the local_dc set to whatever is placed in the environment variable.

So the examples given here are akin to having this in the config file:

"seeds": ["", ""],
"policies": {
    "load_balancing": {
        "name": "DCAwareRoundRobinPolicy",
        "local_dc": "REMOTE1",
        "used_hosts_per_remote_dc": 0


If there is no configuration, neither JSON nor environment variables, the module will default to looking for cassandra at with the Cassandra driver defaults for everything.

How to Use

This module uses HK2 or Guice to provide an implementation of CassandraSession via injection. CassandraSession provides methods that allow statements to be executed, statements to be prepared and for the reading of metadata.

The execution and preparation methods have both synchronous and asynchronous variants. The asynchronous versions take a FutureCallBack class that is updated once the method has finished.

FutureCallback is part of Guava and the JAR is included as part of the Datastax java driver used by this module.

The general best practice is to inject one CassandraSession per verticle.

Promises Variant

There is a promises variant of CassandraSession, which is used by injecting WhenCassandraSession instead. This provides all of the same functionality, but instead of callbacks this class returns promises.

The promises used are from the Englishtown package, which can be found on Github.

If you intend to use this implementation, you must include the dependency in your application as it is not provided by this module.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.