ScyllaDB Tutorial: High-Performance NoSQL for Beginners

If you have ever needed a database that handles millions of writes per second with predictable single-digit millisecond latency, ScyllaDB is built for exactly that. This ScyllaDB tutorial shows you how to get it running locally with Docker, create your first keyspace and table, insert data, query it, and connect from Python, all in a single session. No prior Cassandra experience needed.

TL;DR Summary

• ScyllaDB is a free, open-source NoSQL database written in C++ that is API-compatible with Apache Cassandra but up to 10x faster.
• Setup takes under 5 minutes using a single Docker command.
• ScyllaDB uses CQL (Cassandra Query Language), so any Cassandra knowledge transfers directly.
• It organises data into keyspaces and tables with partition keys and clustering keys for fast distributed queries.
• Discord migrated its messages cluster from Cassandra to ScyllaDB and reduced message latency from 200ms to 5ms.

What is ScyllaDB?

ScyllaDB is an open-source distributed NoSQL database written in C++. It is API-compatible with Apache Cassandra, meaning any application built for Cassandra works with ScyllaDB without code changes.

The key difference is performance. ScyllaDB is designed to squeeze maximum throughput from modern hardware with high-core CPUs and fast SSDs. It achieves this through a shard-per-core architecture where each CPU core owns its own data shard and handles its own I/O independently, eliminating the lock contention that limits Cassandra’s throughput.

ScyllaDB is the right choice when you need low-latency reads and writes at scale for time-series data, IoT streams, user event logs, or real-time analytics.

ScyllaDB fits naturally into high-performance backend stacks for real-time applications, IoT systems, and event-driven architectures. HCL GUVI’s Full Stack Development Course and AI Software Development Course are both IITM Pravartak certified and build the backend engineering depth that makes databases like ScyllaDB practical to work with in production.

ScyllaDB Tutorial: Installation with Docker

Run ScyllaDB locally with one command:

docker run –name scylla -d -p 9042:9042 scylladb/scylla –smp 1

The –smp 1 flag limits ScyllaDB to one CPU core, which is important for local development to avoid consuming all available system resources. Without it, ScyllaDB claims every core it finds.

Wait about 30 seconds for the node to fully start, then confirm it is ready:

docker exec -it scylla nodetool status

When you see UN (Up, Normal) in the status column, ScyllaDB is running and ready to accept connections.

Connecting with cqlsh

cqlsh is the interactive CQL shell bundled with ScyllaDB. Open it with:

docker exec -it scylla cqlsh

You should see a cqlsh> prompt. This is where you run all CQL commands interactively. If you get a connection refused error, wait a few more seconds and try again, the node may still be starting up.

Creating a Keyspace and Table

A keyspace in ScyllaDB is the equivalent of a database in relational systems. It groups related tables together and defines the replication strategy.

Sql

CREATE KEYSPACE IF NOT EXISTS demo
WITH replication = {
  'class': 'SimpleStrategy',
  'replication_factor': '1'
};

USE demo;

CREATE TABLE IF NOT EXISTS events (
  user_id UUID,
  event_time TIMESTAMP,
  event_type TEXT,
  details TEXT,
  PRIMARY KEY (user_id, event_time)
) WITH CLUSTERING ORDER BY (event_time DESC);

The PRIMARY KEY here has two parts. user_id is the partition key, which determines which node stores the row. event_time is the clustering key, which controls how rows are sorted within a partition. Ordering by event_time DESC means the most recent events are always at the top of a scan, which is perfect for time-series queries.

Inserting and Querying Data

Insert a few rows:

Sql 

INSERT INTO demo.events (user_id, event_time, event_type, details)
VALUES (uuid(), toTimestamp(now()), 'login', 'User logged in from mobile');

INSERT INTO demo.events (user_id, event_time, event_type, details)
VALUES (uuid(), toTimestamp(now()), 'purchase', 'Bought item ID 4412');

Query all events for a specific user:

Sql

SELECT * FROM demo.events WHERE user_id = <your-uuid> LIMIT 10;

ScyllaDB always requires the partition key in WHERE clauses for efficient queries. Filtering without it triggers a full cluster scan which is slow and expensive at scale.

Connecting with Python

Install the Cassandra-compatible Python driver, which works with ScyllaDB directly:

pip install cassandra-driver

Connect and run queries from Python:

Python

from cassandra.cluster import Cluster

cluster = Cluster(['127.0.0.1'])
session = cluster.connect()

session.execute("""
    CREATE KEYSPACE IF NOT EXISTS demo
    WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}
""")
session.set_keyspace('demo')

rows = session.execute("SELECT event_type, details FROM events LIMIT 5")
for row in rows:
    print(row.event_type, row.details)

cluster.shutdown()

Because ScyllaDB is API-compatible with Cassandra, the cassandra-driver package works with ScyllaDB without any modification.

When to Use ScyllaDB

Common Mistakes to Avoid

• Running ScyllaDB without –smp 1 in development. By default, ScyllaDB claims every CPU core on your machine. On a developer laptop, this makes everything else unusably slow. Always use –smp 1 for local development and testing.
• Querying without the partition key. ScyllaDB requires the partition key in every WHERE clause for efficient queries. Filtering on non-key columns without using ALLOW FILTERING causes an error, and using ALLOW FILTERING on a large table causes a full cluster scan. Design your data model around your query patterns, not the other way around.
• Using SimpleStrategy for production. SimpleStrategy is only for single-datacenter development setups. For production, switch to NetworkTopologyStrategy with a replication factor of at least 3 to survive node failures.

Conclusion

This ScyllaDB tutorial covered the full beginner workflow: running ScyllaDB with Docker, connecting with cqlsh, creating a keyspace and table with a well-structured primary key, inserting and querying data, and connecting from Python. ScyllaDB’s combination of Cassandra compatibility, C++ performance, and a free open-source license makes it one of the strongest choices for high-throughput, low-latency workloads in 2026.

FAQs

1. What is ScyllaDB?

ScyllaDB is a free, open-source distributed NoSQL database written in C++ that is API-compatible with Apache Cassandra but delivers significantly higher throughput and lower latency through a shard-per-core architecture.

2. Is ScyllaDB free to use?

Yes. The ScyllaDB open-source edition is free under the AGPL license. ScyllaDB also offers a managed cloud service with a free trial.

3. Do I need to learn a new query language for ScyllaDB?

No. ScyllaDB uses CQL, the same Cassandra Query Language used by Apache Cassandra. Any CQL knowledge transfers directly.

4. What is the difference between a keyspace and a table in ScyllaDB?

A keyspace is the top-level container, similar to a database in relational systems. A table lives inside a keyspace and stores rows of structured data organised by a partition key and optional clustering keys.

5. Can I use the Cassandra Python driver with ScyllaDB?

Yes. ScyllaDB is API-compatible with Cassandra, so the cassandra-driver Python package connects and works without any code modifications.