Overview

This project simplifies ScyllaDB cluster configuration with 3 nodes for local testing using Docker and Docker Compose. It facilitates easy deployment and testing of ScyllaDB, a highly scalable NoSQL database.

Prerequisites

Before you begin, make sure the following software is installed on your system:

• Docker
• Docker Compose

Note

The Docker's commands listed below consider when you use its Docker V2

Getting Started

Clone this repository

git clone https://github.com/gvieira18/ws-scylla.git

Configure ScyllaDB settings

Before starting the cluster, ensure the fs.aio-max-nr value is sufficient (e.g. 1048576 or 2097152 or more).

You can use the Makefile setup command to configure the fs.aio-max-nr value. It will set the value to 1048576, which is the minimum recommended for clusters.

make setup

If you prefer to configure it manually, run one of the following commands to check the current value:

sysctl --all | grep --word-regexp -- 'aio-max-nr'

sysctl fs.aio-max-nr

cat /proc/sys/fs/aio-max-nr

If the value is lower than required, you can use one of these commands:

# Update config non-persistent
sysctl --write fs.aio-max-nr=1048576

Warning

This command adds a file to the /etc/sysctl.d folder to be loaded when the system boots.

# Update config persistent
echo fs.aio-max-nr=1048576 | sudo tee /etc/sysctl.d/41-aio_max_nr.conf && sudo sysctl --load '/etc/sysctl.d/41-aio_max_nr.conf'

Optional

Modify the docker-compose.yml file to customize ScyllaDB settings, such as port mappings, volume mounts, and network configurations.

Start the ScyllaDB container

Use the following command to pull the ScyllaDB Docker image (if not already downloaded) and start the container in the background:

docker compose up --detach # starts the cluster in the background

Usage

Accessing the Database

CQLSH (Cassandra Query Language Shell)

CQLSH is the command-line interface for interacting with ScyllaDB using the Cassandra Query Language (CQL). It allows you to execute CQL queries and manage the database.

docker compose exec -it ws-scylla-1 cqlsh

Nodetool

Nodetool is a command-line utility for managing and monitoring ScyllaDB clusters. It provides various operations, such as checking the status of nodes, compaction, repair, and more.

docker compose exec -it ws-scylla-1 nodetool status

Inside the Docker Network

The docker-compose.yml file defines a specific network (ws-scylla) for internal usage. Integration with other projects within different Docker Compose specifications is possible setting on external.

services:
  custom-service:
    networks:
      - ws-scylla
networks:
  ws-scylla:
    external: true

After starting the custom service, it registers within the ws-scylla network. The ScyllaDB configuration already defines default ports for access.

Service Name	Host	Port
ws-scylla-1	ws-scylla-1	9042
ws-scylla-2	ws-scylla-2	9042
ws-scylla-3	ws-scylla-3	9042

// Cassandra JS Driver
const client = new cassandra.Client({
  contactPoints: ['ws-scylla-1:9042', 'ws-scylla-2:9042', 'ws-scylla-3:9042'],
  localDataCenter: 'datacenter1',
  keyspace: 'system'
});

Outside the Docker Network

The default docker-compose.yml file enables the following ports for external access to the DBMS/SGDB or directly to the database driver:

Service Name	Host	Port
ws-scylla-1	localhost	9040
ws-scylla-2	localhost	9041
ws-scylla-3	localhost	9042

Using the same example from internal access:

// Cassandra JS Driver
const client = new cassandra.Client({
  contactPoints: ['localhost:9040', 'localhost:9041', 'localhost:9042'],
  localDataCenter: 'datacenter1',
  keyspace: 'system'
});

When accessing via Datagrip, the JDBC standard is followed. You can build the JDBC URL as follows:

URL="jdbc:cassandra://localhost:9040,localhost:9041,localhost:9042/system"

Stop and Remove Cluster/Container

Stop the Cluster

docker compose stop

Stop and Remove Containers

docker compose down

Caution

Removing the volume also means removing any information stored in the database, so proceed with caution and make a backup if necessary.

docker compose down --volumes # or docker compose down -v

References

• ScyllaDB - DockerHub
• ScyllaDB - University
• ScyllaDB - CarePet PHP example
• Reflective Thoughts from a Unforgotten Past
• fee-mendes/workshop-demo
• tzach/docker-compose.yml

License

This project is licensed under the MIT License.