# index.md

Welcome to ScyllaDB Documentation

ScyllaDB is a high-performance NoSQL database optimized for speed and scalability.
Ask AI

Getting Started

Learn the basics of ScyllaDB, from first deployment to building applications.

ScyllaDB Cloud

Documentation for ScyllaDB Cloud, the fully managed database-as-a-service (DBaaS).

ScyllaDB

Documentation for deploying, configuring, and managing ScyllaDB in your own environment.

Explore More

ScyllaDB Drivers

Connect your applications to ScyllaDB using language-specific drivers.

ScyllaDB Alternator

Use ScyllaDB with the DynamoDB-compatible API.

ScyllaDB Operator

Deploy and manage ScyllaDB clusters on Kubernetes.

Versioning

Learn about ScyllaDB versioning, release types, and upgrade paths.

Monitoring Stack

Monitor the health and performance of your ScyllaDB clusters.

ScyllaDB Migrator

Move existing data into ScyllaDB.

Learn More About ScyllaDB

Attend ScyllaDB University

Register to take a *free* class at ScyllaDB University.
There are several learning paths to choose from.
Find a Class

Register for a Webinar

You can either participate in a live webinar or see a recording on demand.
There are several webinars to choose from.
Find a Webinar
# index.md # Get Started with ScyllaDB This guide will help you get started with ScyllaDB. You’ll learn how to deploy ScyllaDB and use it as the database for your application. * [New to ScyllaDB? Start here!](https://docs.scylladb.com/stable/get-started/scylladb-basics.md) * [Develop with ScyllaDB](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/index.md) * [Query Data](https://docs.scylladb.com/stable/get-started/query-data/index.md) * [Data Modeling](https://docs.scylladb.com/stable/get-started/data-modeling/index.md) * [Learn to Use ScyllaDB](https://docs.scylladb.com/stable/get-started/learn-resources/index.md) * [Build with AI](https://docs.scylladb.com/stable/get-started/build-with-ai/index.md) # index.md # ScyllaDB Drivers * [ScyllaDB CQL Drivers](https://docs.scylladb.com/stable/drivers/cql-drivers.md) * [ScyllaDB DynamoDB Drivers](https://docs.scylladb.com/stable/drivers/dynamo-drivers.md) * [Third-party Drivers](https://docs.scylladb.com/stable/drivers/third-party-drivers.md) # index.md # Versioning and Support Policy * [ScyllaDB Version Support](https://docs.scylladb.com/stable/versioning/version-support.md) * [Driver Support](https://docs.scylladb.com/stable/versioning/driver-support.md) * [OS Support per ScyllaDB Version](https://docs.scylladb.com/stable/versioning/os-support-per-version.md) * [Upgrade Policy](https://docs.scylladb.com/stable/versioning/upgrade-policy.md) # index.md # Learn to Use ScyllaDB ## ScyllaDB University Join [ScyllaDB University](https://university.scylladb.com/), which offers a series of free NoSQL database training courses. They were designed as both a ScyllaDB tutorial and a resource for learning basic NoSQL concepts. See the [course catalog](https://university.scylladb.com/#search-courses) for a complete list of available courses. ## Example Projects ScyllaDB’s [example projects](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/tutorials-example-projects.md) will help you learn how to use ScyllaDB as a data source for an application. ## Webinars and Workshops Attend ScyllaDB’s webinars, workshops, and other events. [Explore the upcoming and past events](https://www.scylladb.com/company/events/). ## Tech Talks and ScyllaDB Summit Sessions Watch [tech talks and presentations](https://www.scylladb.com/resources/tech-talks/) from ScyllaDB’s annual ScyllaDB Summit. ## ScyllaDB Community Forum Join the [ScyllaDB Community Forum](https://forum.scylladb.com/). It is a public discussion space for asking questions, sharing knowledge, and troubleshooting topics related to ScyllaDB and its ecosystem. It also hosts broader discussions on NoSQL databases, including data modeling, performance, and distributed system best practices. ## ScyllaDB Blog Subscribe to the [ScyllaDB blog](https://www.scylladb.com/blog/) to be up to date with recent news about the ScyllaDB NoSQL database and related technologies. # index.md # Develop with ScyllaDB Developing with ScyllaDB involves setting up the database environment, choosing the appropriate drivers for your programming language, and integrating it with your application. * [Run ScyllaDB](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/run-scylladb.md) * [Install a Driver](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/install-drivers.md) * [Connect an Application](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/connect-apps.md) * [Tutorials and Example Projects](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/tutorials-example-projects.md) # index.md # Build with AI * [ScyllaDB Agent Skills](https://docs.scylladb.com/stable/get-started/build-with-ai/agent-skills.md) * [AI Integrations](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/index.md) * [MCP Toolbox for Databases](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/mcp-toolbox.md) * [LangGraph](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/langgraph.md) * [Feast](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/feast.md) * [Resonate](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/resonate.md) # index.md # Data Modeling Data modeling is the process of defining the structure and relationships of your data in ScyllaDB. It involves making important decisions about how data will be organized, stored, and retrieved. Data modeling in NoSQL database such as ScyllaDB differs from traditional relational databases. A practical approach when data modeling for ScyllaDB is to adopt a query-first data model, where you design your data model around the queries that it needs to execute. * [Query Design](https://docs.scylladb.com/stable/get-started/data-modeling/query-design.md) * [Schema Design](https://docs.scylladb.com/stable/get-started/data-modeling/schema-design.md) * [Data Modeling Best Practices](https://docs.scylladb.com/stable/get-started/data-modeling/best-practices.md) # index.md # Query Data To effectively query data in ScyllaDB, you should understand its schema and how to perform basic operations like insert, read, update, and delete. To perform these basic operations, you will use CQL. * [CQL](https://docs.scylladb.com/stable/get-started/query-data/cql.md) * [Schema](https://docs.scylladb.com/stable/get-started/query-data/schema.md) * [Inserting Data](https://docs.scylladb.com/stable/get-started/query-data/insert-data.md) * [Reading Data](https://docs.scylladb.com/stable/get-started/query-data/read-data.md) * [Updating Data](https://docs.scylladb.com/stable/get-started/query-data/update-data.md) * [Deleting Data](https://docs.scylladb.com/stable/get-started/query-data/delete-data.md) #### NOTE If you are looking to query data with a DynamoDB compatible API, we recommend using [ScyllaDB Alternator](https://docs.scylladb.com/manual/stable/alternator/getting-started.html). # index.md # AI Integrations Use ScyllaDB with popular AI frameworks and tools. * [MCP Toolbox for Databases](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/mcp-toolbox.md) * [LangGraph](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/langgraph.md) * [Feast](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/feast.md) * [Resonate](https://docs.scylladb.com/stable/get-started/build-with-ai/integrations/resonate.md) # agent-skills.md # ScyllaDB Agent Skills [ScyllaDB Agent Skills](https://github.com/scylladb/agent-skills) is a collection of skills for AI coding agents ([GitHub Copilot](https://github.com/copilot), [Cursor](https://cursor.com), [Claude Code](https://claude.com/product/claude-code), and others) that provide domain-specific knowledge about ScyllaDB and ScyllaDB Cloud. The skills help agents write correct CQL queries, design efficient data models, and connect applications to ScyllaDB Cloud. ## Installation ```bash npx skills add scylladb/agent-skills ``` See the [agent-skills repository](https://github.com/scylladb/agent-skills) for available skills and more information. # best-practices.md # Data Modeling Best Practices These additional topics provide a broader perspective on data modeling, query design, schema design, and best practices when working with ScyllaDB or similar distributed NoSQL databases. **Partition Key Selection** Choose your partition keys to avoid imbalances in your clusters. Imbalanced partitions can lead to performance bottlenecks, which impact overall cluster performance. Balancing the distribution of data across partitions is crucial to ensure all nodes are effectively utilized in your cluster. Let’s consider a scenario with poor partition key selection: ```default CREATE TABLE my_keyspace.messages_bad ( user_id uuid, message_id uuid, message_text text, created_at timestamp, PRIMARY KEY (user_id, message_id) ); ``` In this model, the partition key is chosen as `user_id`, which is a globally unique identifier for each user. This choice results in poor partition key selection because it doesn’t distribute data evenly across partitions. As a result, messages from popular users with many messages will create hot partitions, as all their messages will be concentrated in a single partition. A better solution for partition key selection would look like: ```default CREATE TABLE my_keyspace.messages_good ( message_id uuid PRIMARY KEY, user_id uuid, message_text text, created_at timestamp ); ``` In this improved model, the partition key is chosen as `message_id`, which is the unique identifier for each message. This choice results in even data distribution across partitions because each user’s messages are distributed across multiple partitions. Popular users with many posts won’t create hot partitions, as their messages are distributed across the cluster. This approach ensures that all nodes in the cluster are effectively utilized, preventing performance bottlenecks. # connect-apps.md # Connect an Application To connect your application to ScyllaDB, you need to: 1. [Install the relevant driver](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/install-drivers.md) for your application language. This step involves setting up a driver that is compatible with ScyllaDB. The driver acts as the link between your application and ScyllaDB, enabling your application to communicate with the database. 2. Modify your application code to connect the driver. The following is some boilerplate code to help familiarize yourself with connecting your application with the ScyllaDB driver. For a detailed walkthrough of building a fictional media player application with code examples, please see our [Getting Started tutorial](https://cloud-getting-started.scylladb.com/stable/getting-started.html). Rust ```rust use anyhow::Result;in various languages use scylla::{Session, SessionBuilder}; use std::time::Duration; #[tokio::main] async fn main() -> Result<()> { let session: Session = SessionBuilder::new() .known_nodes(&[ "localhost", ]) .connection_timeout(Duration::from_secs(30)) .user("scylla", "your-awesome-password") .build() .await .unwrap(); Ok(()) } ``` Go ```go func main() { cluster := gocql.NewCluster("localhost") cluster.Authenticator = gocql.PasswordAuthenticator{Username: "scylla", Password: "your-awesome-password"} session, err := gocqlx.WrapSession(cluster.CreateSession()) if err != nil { panic("Connection fail") } } ``` Java ```java import com.datastax.driver.core.Cluster; import com.datastax.driver.core.PlainTextAuthProvider; import com.datastax.driver.core.Session; class Main { public static void main(String[] args) { Cluster cluster = Cluster.builder() .addContactPoints("localhost") .withAuthProvider(new PlainTextAuthProvider("scylla", "your-awesome-password")) .build(); Session session = cluster.connect(); } } ``` Python ```python from cassandra.cluster import Cluster from cassandra.auth import PlainTextAuthProvider cluster = Cluster( contact_points=[ "localhost", ], auth_provider=PlainTextAuthProvider(username='scylla', password='your-awesome-password') ) ``` JavaScript ```javascript const cluster = new cassandra.Client({ contactPoints: ["localhost", ...], localDataCenter: 'your-data-center', credentials: {username: 'scylla', password: 'your-awesome-password'}, // keyspace: 'your_keyspace' // optional }) ``` # cql-drivers.md # ScyllaDB CQL Drivers ScyllaDB drivers are specialized client libraries that enable efficient communication between your application and a ScyllaDB cluster. They handle core operations such as inserts, queries, and schema modifications while optimizing performance through shard awareness. Each driver is designed to recognize ScyllaDB’s shard-per-core architecture, routing requests directly to the appropriate CPU core and node to minimize latency and maximize throughput. * To interact with ScyllaDB, you need to install the appropriate driver for your programming language. You will find full installation instructions in the documentation for each driver (see the table below). To perform a basic installation, you can refer to the [Install a Driver](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/install-drivers.md) section in the Get Started guide. * We support the **two most recent minor releases** of each driver. Stay up to date with driver releases to maintain compatibility with your ScyllaDB version. See [Driver Support](https://docs.scylladb.com/stable/versioning/driver-support.md) for the support policy and the list of currently supported versions. ## Available ScyllaDB Drivers The following table shows the available ScyllaDB drivers. Click the documentation link to view the documentation for each driver. | ScyllaDB Driver | Description | |-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Python Driver | A native Python client for interacting with ScyllaDB and Cassandra
clusters, implementing the CQL binary protocol. It supports
asynchronous query execution, automatic connection pooling, and
adaptive load balancing to optimize throughput and latency in
Python applications.



[Python Driver documentation](https://python-driver.docs.scylladb.com/) | | Java Driver | A native Java client for interacting with ScyllaDB and Cassandra
clusters, implementing the CQL binary protocol. It provides full
asynchronous support, automatic query paging, and advanced load
balancing policies.


There are two driver families, 4.x and 3.x, and the support policy
applies separately to each family, covering the two latest minor
versions within 4.x and the two latest minor versions within 3.x.



[Java Driver documentation](https://java-driver.docs.scylladb.com/) | | Go Driver | A native Go client for interacting with ScyllaDB and Cassandra
clusters, implementing the CQL binary protocol. It features a fully
asynchronous, non-blocking API with shard‑aware host selection and
optimized connection management for high-performance Go applications.


An extension, **gocqlx**, adds higher‑level abstractions, such as
query builders and struct binding, to improve developer productivity.


* [Go Driver documentation](https://github.com/scylladb/gocql)
* [Gocql extension documentation](https://github.com/scylladb/gocqlx) | | Rust Driver | A native Rust client for interacting with ScyllaDB and Cassandra
clusters, implementing the CQL binary protocol. Delivers memory-safe,
fully asynchronous operations with zero-cost abstractions for
low-latency, high-throughput Rust applications.



[Rust Driver documentation](https://rust-driver.docs.scylladb.com/) | | C# Driver | A native C# client for interacting with ScyllaDB and Cassandra
clusters, implementing the CQL binary protocol. It integrates with
.NET asynchronous programming patterns, supports connection pooling
and retry policies, and is optimized for enterprise-grade .NET
applications.



[C# Driver documentation](https://csharp-driver.docs.scylladb.com/) | | CPP RS Driver | A native C++ client built on a Rust core for interacting with
ScyllaDB and Cassandra clusters, implementing the CQL binary
protocol. It combines Rust’s memory safety and concurrency features
with C++ usability, providing safer and more reliable
high-performance database access.



[CPP RS Driver documentation](https://cpp-rs-driver.docs.scylladb.com/) | | Node.js RS Driver | A native Node.js client for interacting with ScyllaDB and Cassandra
clusters, implementing the CQL binary protocol. Built on a Rust core,
it provides fully asynchronous operations, efficient resource usage,
and high-throughput, low-latency database access for Node.js applications.



[Node.js RS Driver documentation](https://nodejs-rs-driver.docs.scylladb.com/) | | C++ Driver | This driver is no longer actively maintained. We recommend using
the CPP RS Driver for improved performance and full support
for the latest ScyllaDB features.



[C++ Driver documentation](https://cpp-driver.docs.scylladb.com/) | ## Support for Tablets The following table specifies which ScyllaDB drivers support [tablets](https://docs.scylladb.com/manual/stable/architecture/tablets.html) and since which version. | ScyllaDB Driver | Support for Tablets | Since Version | |-------------------------------------------------------------|------------------------------------------------------------|--------------------------------------------------------------| | [Python](https://python-driver.docs.scylladb.com/) | | 3.26.5 | | [Java](https://java-driver.docs.scylladb.com/) | | 4.18.0 (Java Driver 4.x)

3.11.5.2 (Java Driver 3.x) | | [Go](https://github.com/scylladb/gocql) | | 1.13.0 | | [Gocql extension](https://github.com/scylladb/gocqlx) | | N/A | | [Rust](https://rust-driver.docs.scylladb.com/) | | 0.13.0 | | [C#](https://csharp-driver.docs.scylladb.com/) | | All versions | | [CPP RS](https://cpp-rs-driver.docs.scylladb.com/) | | All versions | | [Node.js RS](https://github.com/scylladb/nodejs-rs-driver/) | | All versions | | [C++](https://cpp-driver.docs.scylladb.com/) | | N/A. This driver is no longer actively maintained. | ## Support for Vector Search The [Vector Search](https://cloud.docs.scylladb.com/stable/vector-search/index.html) feature requires drivers to support the `vector` CQL type. The following table specifies which ScyllaDB drivers support the `vector` type and since which version. | ScyllaDB Driver | Support for the `vector` type | Since Version | |-------------------------------------------------------------|------------------------------------------------------------|-----------------------------------------------------------------------------------------------| | [Python](https://python-driver.docs.scylladb.com/) | | 3.28.0 | | [Java](https://java-driver.docs.scylladb.com/) | | Java Driver 4.x: 4.16.0 (recommended 4.19.0 or later)

Java Driver 3.x: not supported | | [Go](https://github.com/scylladb/gocql) | | 1.17.0 | | [Gocql extension](https://github.com/scylladb/gocqlx) | | To be supported in a future release | | [Rust](https://rust-driver.docs.scylladb.com/) | | 1.2.0 | | [C#](https://csharp-driver.docs.scylladb.com/) | | All versions | | [CPP RS](https://cpp-rs-driver.docs.scylladb.com/) | | 0.5.1 | | [Node.js RS](https://github.com/scylladb/nodejs-rs-driver/) | | All versions | | [C++](https://cpp-driver.docs.scylladb.com/) | | N/A. This driver is no longer actively maintained. | ## CDC Integration with ScyllaDB Drivers The following table specifies which ScyllaDB drivers include a library for [CDC](https://docs.scylladb.com/manual/stable/features/cdc/index.html). | ScyllaDB Driver | CDC Connector | |-------------------------------------------------------------|------------------------------------------------------------| | [Python](https://python-driver.docs.scylladb.com/) | | | [Java](https://java-driver.docs.scylladb.com/) | | | [Go](https://github.com/scylladb/gocql) | | | [Gocql extension](https://github.com/scylladb/gocqlx) | | | [Rust](https://rust-driver.docs.scylladb.com/) | | | [C#](https://csharp-driver.docs.scylladb.com/) | | | [CPP RS Driver](https://cpp-rust-driver.docs.scylladb.com/) | | | [Node.js RS](https://github.com/scylladb/nodejs-rs-driver/) | | | [C++](https://cpp-driver.docs.scylladb.com/) | | # cql.md # CQL CQL, or Cassandra Query Language, is a query language for interacting with ScyllaDB, which is similar in syntax and usage to SQL for relational databases. It allows you to define, query, and modify data. CQL is designed to be simple and intuitive, making it easier for those familiar with SQL to transition to working with ScyllaDB. Learning and mastering CQL is crucial for designing queries. See the [ScyllaDB documentation](https://docs.scylladb.com/manual/stable/cql/index.html) for CQL reference and CQL-related topics. ## Using cqlsh cqlsh is a command-line shell for interacting with ScyllaDB through CQL. It provides an interface to run CQL commands and scripts. cqlsh connects to a ScyllaDB node and allows you to execute CQL commands directly. This tool is essential for database management tasks and querying data. You can connect to the node you started earlier in this guide, with cqlsh using the following command: ```default docker exec -it scylla cqlsh ``` The output of this command will look something like this: ```default Connected to at 172.17.0.2:9042. [cqlsh 5.0.1 | Cassandra 3.0.8 | CQL spec 3.3.1 | Native protocol v4] Use HELP for help. cqlsh> ``` See [CQLSh: the CQL shell](https://docs.scylladb.com/manual/stable/cql/cqlsh.html) for details. # delete-data.md # Deleting Data Delete data with the `DELETE` statement. Be specific with your restrictions to avoid accidental deletions. For example: ```default DELETE FROM my_keyspace.users WHERE user_id = 123e4567-e89b-12d3-a456-426655440000; ``` Let’s break down the components of this `DELETE` statement: **Keyspace and Table** `my_keyspace.users`: This specifies the keyspace and table from which you want to delete data. In this example, you are deleting data from a table named `my_table` within the `my_keyspace` keyspace. **WHERE Clause** `WHERE user_id = 123e4567-e89b-12d3-a456-426655440000`: This part of the statement specifies a restriction for filtering the rows to be deleted. Including the `WHERE` clause with a specific restriction is essential to ensure that only the rows meeting the restriction will be deleted. This is done to prevent accidental deletions of the wrong data in the table. #### NOTE Similar to `INSERT` and `UPDATE` statements, a `DELETE` operation can be conditional using ScyllaDB’s [Lightweight Transaction](https://docs.scylladb.com/manual/stable/features/lwt.html) IF EXISTS\` clause. In summary, the `DELETE` statement in ScyllaDB is used to remove existing data from a table. Always use a `WHERE` clause with a suitable restriction to target the specific rows you want to delete, and ensure that the restriction is specific enough to avoid unintended data loss. This approach helps maintain data integrity in your ScyllaDB tables. See the details about the [DELETE statement](https://docs.scylladb.com/manual/stable/cql/dml/delete.html) in the ScyllaDB documentation. # driver-support.md # Driver Support ## Support Policy We support the **two most recent minor releases** of [ScyllaDB drivers](https://docs.scylladb.com/stable/drivers/cql-drivers.md). * We test and validate the latest two minor versions. * We typically patch only the latest minor release. We recommend staying up to date with the latest supported versions to receive updates and fixes. At a minimum, upgrade your driver when upgrading to a new ScyllaDB version to ensure compatibility between the driver and the database. ## Supported Versions The following table shows the available ScyllaDB drivers and their latest versions. | ScyllaDB Driver | Supported Versions | |------------------------------------------------------------------|------------------------------------------------------------------------------------------------| | [Python Driver](https://python-driver.docs.scylladb.com/) | * 3.29
* 3.28 | | [Java Driver](https://java-driver.docs.scylladb.com/) | Java Driver 4.x

* 4.19
* 4.18

Java Driver 3.x

* 3.11
* 3.10 | | [Go Driver](https://github.com/scylladb/gocql) | * 1.18
* 1.17 | | [Rust Driver](https://rust-driver.docs.scylladb.com/) | * 1.7
* 1.6 | | [C# Driver](https://csharp-driver.docs.scylladb.com/) | * 3.22 | | [CPP RS Driver](https://cpp-rs-driver.docs.scylladb.com/) | * 1.0
* 1.1 | | [C++ Driver](https://cpp-driver.docs.scylladb.com/) | Deprecated. Migrate to [CPP RS Driver](https://cpp-rs-driver.docs.scylladb.com/). | | [Node.js RS Driver](https://nodejs-rs-driver.docs.scylladb.com/) | * 0.6 | # dynamo-drivers.md # ScyllaDB DynamoDB Drivers ScyllaDB AWS DynamoDB Compatible API can be used with any AWS DynamoDB Driver. For a list of AWS DynamoDB drivers, see [Getting started with DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStarted.html) in the Amazon DynamoDB documentation. # feast.md # Feast ![Feast logo](_static/img/integrations/feast-logo.png) [Feast](https://feast.dev/) is an open source feature store framework that manages and serves machine learning features for training and inference. The ScyllaDB integration provides a Feast online store for low-latency, distributed, real-time feature serving, with built-in support for vector search. It materializes feature values into a self-hosted ScyllaDB cluster or [ScyllaDB Cloud](https://cloud.scylladb.com/). ScyllaDB is used as an online store only. Feast still requires a separate offline store for historical feature retrieval. The ScyllaDB integration does not implement an offline store. ## Installation Install Feast with the `scylladb` extra, which pulls in `scylla-driver` automatically: ```bash pip install feast[scylladb] ``` ## Configuration Configure ScyllaDB as the online store in your `feature_store.yaml`. Set `online_store.type` to `scylladb` and provide the connection details for your cluster. Self-hosted ScyllaDB: ```yaml project: scylla_feature_repo registry: data/registry.db provider: local online_store: type: scylladb hosts: - 172.17.0.2 keyspace: feast username: scylla password: password ``` ScyllaDB Cloud: When connecting to ScyllaDB Cloud, set `local_dc` to the datacenter name shown on the **Connect** tab of your cluster in the [ScyllaDB Cloud Console](https://cloud.scylladb.com/). ```yaml project: scylla_feature_repo registry: data/registry.db provider: local online_store: type: scylladb hosts: - node-0.aws_us_east_1.xxxxxxxx.clusters.scylla.cloud - node-1.aws_us_east_1.xxxxxxxx.clusters.scylla.cloud - node-2.aws_us_east_1.xxxxxxxx.clusters.scylla.cloud keyspace: feast username: scylla password: xxxxxx local_dc: AWS_US_EAST_1 ``` ### Configuration Options | Parameter | Type | Default | Description | |------------------------------|-----------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `hosts` | list[str] | *(required)* | Contact-point host addresses. | | `port` | int | `9042` | CQL port. | | `keyspace` | str | `feast_keyspace` | Target ScyllaDB keyspace. | | `username` | str | `None` | Auth username. | | `password` | str | `None` | Auth password. | | `local_dc` | str | `None` | Local datacenter name for DC-aware load balancing. | | `request_timeout` | float | `None` | Driver request timeout in seconds. | | `read_concurrency` | int | `100` | `concurrency` argument passed to the driver’s
`execute_concurrent_with_args` for reads. Controls how many CQL
statements are in-flight at once. | | `write_concurrency` | int | `100` | `concurrency` argument passed to the driver’s
`execute_concurrent_with_args` for writes. Controls how many CQL
statements are in-flight at once. | | `vector_similarity_function` | str | `COSINE` | Default similarity function for vector indexes. Supported: `COSINE`,
`DOT_PRODUCT`, `EUCLIDEAN`. Can be overridden per-feature via the
`similarity_function` Field tag. | ## Vector Search ScyllaDB Cloud supports approximate nearest-neighbour (ANN) vector search. To enable it for a feature view, tag the embedding `Field` with `vector_index=true` and specify the number of dimensions: ```python from feast import FeatureView, Field from feast.types import Array, Float32, String documents_fv = FeatureView( name="documents", entities=[item], schema=[ Field(name="text", dtype=String), Field( name="embedding", dtype=Array(Float32), tags={ "vector_index": "true", "dimensions": "768", "similarity_function": "COSINE", # COSINE | DOT_PRODUCT | EUCLIDEAN }, ), ], online=True, source=push_source, ) ``` When `feast apply` runs, it automatically creates the necessary tables and ANN index for any feature view with vector-tagged fields. To query the top-k most similar documents: ```python result = store.retrieve_online_documents_v2( features=["documents:text", "documents:embedding"], query=[0.1, 0.2, ...], # your query embedding top_k=10, distance_metric="COSINE", ) ``` The `distance_metric` accepts the following values: * `COSINE`: cosine similarity. * `DOT_PRODUCT`: dot-product (inner-product) similarity. * `EUCLIDEAN`: Euclidean (L2) distance. ## Additional Resources * [Feast ScyllaDB online store reference](https://docs.feast.dev/master/reference/online-stores/scylladb) * [Feast website](https://feast.dev/) * [Example projects](https://feature-store.scylladb.com/) * [Turbocharge your Feature Store with ScyllaDB](https://www.scylladb.com/solution/feature-store/) # insert-data.md # Inserting Data To insert data, use the `INSERT INTO` statement specifying the table and the column values. For example: ```default INSERT INTO my_keyspace.users (user_id, first_name, last_name, age) VALUES (123e4567-e89b-12d3-a456-426655440000, 'Polly', 'Partition', 77); ``` Let’s break down the components of this `INSERT INTO` statement: **Keyspace and Table** `my_keyspace.users`: This specifies the keyspace and table into which you want to insert data. In this example, it’s inserting data into a table named `users` within the `my_keyspace` keyspace. **Column Names** `(user_id, first_name, last_name, age)`: This part of the statement specifies the column names in the table to which you want to insert data. **VALUES Clause** `VALUES (123e4567-e89b-12d3-a456-426655440000, 'Polly', 'Partition', 77)`: This part of the statement specifies the values that you want to insert into the corresponding columns. `123e4567-e89b-12d3-a456-426655440000` is being inserted into the `user_id` column (without quotes) as it is an `uuid` data type. `'Polly', 'Partition'` (enclosed in single quotes) are being inserted into the `first_name`, `last_name` columns. `77` is being inserted into the `age` column (without quotes) as it is an `int` data type. #### NOTE Unlike in SQL, `INSERT INTO` does not check the prior existence of the row by default: the row is created if none existed before, and updated otherwise. This behavior can be changed by using ScyllaDB’s [Lightweight Transaction](https://docs.scylladb.com/manual/stable/features/lwt.html) `IF NOT EXISTS` or `IF EXISTS` clauses. In summary, the `INSERT INTO` statement in ScyllaDB is used to insert a new row of data into a specific table within a keyspace. It requires you to specify the keyspace, table, column names, and the corresponding values that you want to insert into those columns. This allows you to add data to your tables in ScyllaDB for subsequent retrieval and querying. See the details about the [INSERT statement](https://docs.scylladb.com/manual/stable/cql/dml/insert.html) in the ScyllaDB documentation. # install-drivers.md # Install a Driver To interact with ScyllaDB, you need to install the appropriate drivers for your programming language. These drivers facilitate communication between the application and the ScyllaDB database, enabling data manipulation and retrieval. Rust Rust developers can use specialized drivers that provide asynchronous, non-blocking access to ScyllaDB. These drivers are designed to leverage Rust’s performance and safety features, ensuring efficient and secure database operations. The installation typically involves adding the driver as a dependency in your `Cargo.toml` file and configuring it to connect to your ScyllaDB instance. Run the following Cargo command in the project directory: ```default cargo add scylla ``` Or add the relevant version to your `Cargo.toml` following instructions on [crates.io](https://crates.io/). * See the [Rust Driver documentation](https://rust-driver.docs.scylladb.com/) for details. * Learn how to use the Rust Driver on [ScyllaDB University](https://university.scylladb.com/courses/using-scylla-drivers/lessons/rust-and-scylla-2/). Python For Python developers, ScyllaDB has forked the Python client driver for CQL, adding enhanced capabilities that take advantage of ScyllaDB’s architecture. `pip` is the suggested tool for installing packages. It will install the Python driver and all required Python dependencies. Run the following command: ```default pip install scylla-driver ``` * See the [Python Driver documentation](https://python-driver.docs.scylladb.com/) for details. * [Learn how to use Python with ScyllaDB](https://university.scylladb.com/courses/using-scylla-drivers/lessons/coding-with-python/) on ScyllaDB University. Java For Java developers, ScyllaDB has forked the Java client driver for CQL, adding enhanced capabilities that take advantage of ScyllaDB’s architecture. Maven is the suggested tool for managing dependencies, and the driver artifacts are published in Maven central, under the group id [com.scylladb](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.scylladb%22). You should include the following dependencies: ```xml com.scylladb java-driver-core ${driver.version} com.scylladb java-driver-query-builder ${driver.version} com.scylladb java-driver-mapper-runtime ${driver.version} ``` * See the [Java Driver documentation](https://java-driver.docs.scylladb.com/) for details. * [Learn how to use Java with ScyllaDB](https://university.scylladb.com/courses/using-scylla-drivers/lessons/coding-with-java-part-1/) on ScyllaDB University. Go For Golang developers, ScyllaDB has forked the GoCQL client driver for CQL, adding enhanced capabilities that take advantage of ScyllaDB’s architecture. This is a drop-in replacement for gocql, and it reuses the `github.com/gocql/gocql` import path. To install the driver: 1. Add the following line to your project `go.mod` file: > ```default > replace github.com/gocql/gocql => github.com/scylladb/gocql latest > ``` 2. Run: > ```default > go mod tidy > ``` * See the [Go Driver documentation](https://docs.scylladb.com/manual/stable/using-scylla/drivers/cql-drivers/scylla-go-driver.html) for details. * [Learn how to use Go with ScyllaDB](https://university.scylladb.com/courses/using-scylla-drivers/lessons/golang-and-scylla-part-1/) on ScyllaDB University. JavaScript For JavaScript developers, ScyllaDB can use the Cassandra driver for CQL. `yarn` is the suggested tool for installing packages and required dependencies. Run the following command: ```default yarn install cassandra-driver ``` * Alternatively, you can use `npm` to install packages with the same name. * [Learn how to use Node.js with ScyllaDB](https://university.scylladb.com/courses/using-scylla-drivers/lessons/scylla-and-node-js/) on ScyllaDB University. Other Languages See [ScyllaDB CQL Drivers](https://docs.scylladb.com/manual/stable/using-scylla/drivers/cql-drivers/index.html) for a full list of drivers supported by ScyllaDB. # langgraph.md # LangGraph [LangGraph](https://github.com/langchain-ai/langgraph) is a framework for building AI agents and multi-agent workflows. The ScyllaDB LangGraph integration provides a checkpointer that persists agent state in ScyllaDB, enabling short-term memory, human-in-the-loop patterns, time travel, and fault tolerance. ## Checkpointer The `ScyllaDBSaver` checkpointer implements the LangGraph `CheckpointSaver` interface on top of ScyllaDB. It persists the full state of your LangGraph graph after every step, so agents can resume interrupted runs and support multi-turn conversations across sessions. ### Installation ```bash pip install langgraph-checkpoint-scylladb ``` ### Usage #### Synchronous Create a new session for `ScyllaDBSaver`: ```python from cassandra.auth import PlainTextAuthProvider from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT from cassandra.policies import DCAwareRoundRobinPolicy from langgraph.checkpoint.scylladb import ScyllaDBSaver profile = ExecutionProfile( load_balancing_policy=DCAwareRoundRobinPolicy(local_dc="AWS_US_EAST_1"), ) cluster = Cluster( contact_points=["node-0.example.scylla.cloud"], port=9042, auth_provider=PlainTextAuthProvider("scylla", "secret"), execution_profiles={EXEC_PROFILE_DEFAULT: profile}, ) session = cluster.connect() checkpointer = ScyllaDBSaver(session, keyspace="langgraph") checkpointer.setup() app = graph.compile(checkpointer=checkpointer) write_config = {"configurable": {"thread_id": "1", "checkpoint_ns": ""}} read_config = {"configurable": {"thread_id": "1"}} checkpointer.put(write_config, {...}, {}, {}) checkpointer.get(read_config) list(checkpointer.list(read_config)) ``` #### NOTE Call `checkpointer.setup()` once to create the required tables in the target keyspace before using the checkpointer. #### Asynchronous (`from_conn_string`) Use the async context manager with a connection string: ```python from langgraph.checkpoint.scylladb import ScyllaDBSaver SCYLLADB_URI = ( "scylladb://scylla:secret@node-0.example.scylla.cloud:9042" "/langgraph?dc=AWS_US_EAST_1" ) async with ScyllaDBSaver.from_conn_string(SCYLLADB_URI) as checkpointer: await checkpointer.aput(write_config, {...}, {}, {}) await checkpointer.aget(read_config) [c async for c in checkpointer.alist(read_config)] ``` The connection string format is: ```text scylladb://:@:/?dc= ``` The `dc` query parameter is required for ScyllaDB Cloud connections. #### TTL Checkpoints can be automatically expired by passing a `ttl` value in seconds: ```python checkpointer = ScyllaDBSaver(session, keyspace="langgraph", ttl=3600) # seconds # or via from_conn_string async with ScyllaDBSaver.from_conn_string(SCYLLADB_URI, ttl=3600) as checkpointer: ... ``` ### Schema `checkpointer.setup()` creates two tables in the target keyspace: | Table | Partition key | Clustering key | |---------------------|---------------------------------------------|-------------------------------------------| | `checkpoints` | `thread_id` | `checkpoint_ns ASC`, `checkpoint_id DESC` | | `checkpoint_writes` | `(thread_id, checkpoint_ns, checkpoint_id)` | `task_id`, `idx` | Every access pattern uses a full partition key, so no `ALLOW FILTERING` is needed. ## Additional Resources * [langgraph-checkpoint-scylladb repository](https://github.com/scylladb/langchain-scylladb/tree/main/libs/langgraph-checkpoint-scylladb) * [LangGraph persistence documentation](https://langchain-ai.github.io/langgraph/concepts/persistence/) * [ScyllaDB Cloud](https://cloud.scylladb.com/) * [ScyllaDB documentation](https://docs.scylladb.com/) # mcp-toolbox.md # MCP Toolbox for Databases ![MCP Toolbox for Databases logo](_static/img/integrations/mcp-toolbox-logo.png) [MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox) is an open source MCP server that exposes database operations as tools consumable by AI agents and LLMs. The ScyllaDB integration lets agents execute pre-defined CQL statements against a ScyllaDB cluster via the `scylladb-cql` tool type. ## Prerequisites Install MCP Toolbox for Databases following the [official installation guide](https://mcp-toolbox.dev/documentation/getting-started/introduction/). ## Configure a ScyllaDB Source A *source* tells MCP Toolbox how to connect to your ScyllaDB cluster. Create a `tools.yaml` file and add a source block of `type: scylladb`. Self-hosted ScyllaDB: ```yaml kind: source name: my-scylladb-source type: scylladb hosts: - 127.0.0.1 keyspace: my_keyspace protoVersion: 4 username: ${USER_NAME} password: ${PASSWORD} ``` ScyllaDB Cloud: When connecting to ScyllaDB Cloud, set `localDC` to the datacenter name shown on the **Connect** tab of your cluster in the [ScyllaDB Cloud Console](https://cloud.scylladb.com/). This enables DC-aware, token-aware load balancing, which is required for ScyllaDB Cloud connections. ```yaml kind: source name: my-scylladb-cloud-source type: scylladb hosts: - node-0.your-cluster.us-east-1.cloud.scylladb.com - node-1.your-cluster.us-east-1.cloud.scylladb.com - node-2.your-cluster.us-east-1.cloud.scylladb.com keyspace: my_keyspace username: ${USER_NAME} password: ${PASSWORD} localDC: AWS_US_EAST_1 ``` ### Source Reference | Field | Type | Required | Description | |--------------------------|----------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | string | yes | Must be `"scylladb"`. | | `hosts` | string[] | yes | List of contact point addresses (e.g., `["192.168.1.1:9042"]`). The
default port is 9042 if not specified. | | `keyspace` | string | no | Name of the keyspace to connect to. | | `protoVersion` | integer | no | CQL native protocol version (e.g., `4`). | | `username` | string | no | ScyllaDB username. | | `password` | string | no | ScyllaDB password. | | `localDC` | string | no | Datacenter name for DC-aware load balancing (e.g.,
`"AWS_US_EAST_1"`). Required for ScyllaDB Cloud connections. | | `caPath` | string | no | Path to a CA certificate file. Use when connecting to a self-hosted
ScyllaDB cluster with a private or custom CA. Not needed for
ScyllaDB Cloud. | | `certPath` | string | no | Path to the client certificate file for mutual TLS (mTLS). | | `keyPath` | string | no | Path to the client private key file for mutual TLS (mTLS). Required
together with `certPath`. | | `enableHostVerification` | bool | no | Whether to verify the server hostname against its TLS certificate.
Defaults to `false`. | ## Define a `scylladb-cql` Tool A `scylladb-cql` tool executes a pre-defined CQL statement against the configured source. The statement is executed as a prepared statement; positional placeholders use `?`. Basic parameters: ```yaml kind: tool name: search_users_by_email type: scylladb-cql source: my-scylladb-source statement: | SELECT user_id, email, first_name, last_name, created_at FROM users WHERE email = ? description: | Use this tool to retrieve user information by email address. Returns user ID, email, first name, last name, and creation timestamp. Example: {{ "email": "user@example.com", }} parameters: - name: email type: string description: User's email address ``` Template parameters allow dynamic identifiers such as keyspace or table names. Because template parameters are interpolated before the statement is prepared, they are more vulnerable to CQL injection. Use basic parameters whenever possible. ```yaml kind: tool name: list_keyspace_table type: scylladb-cql source: my-scylladb-source statement: | SELECT * FROM {{.keyspace}}.{{.tableName}}; description: | Use this tool to list all rows from a table in a keyspace. Example: {{ "keyspace": "my_keyspace", "tableName": "users", }} templateParameters: - name: keyspace type: string description: Keyspace containing the table - name: tableName type: string description: Table to select from ``` ### Tool Reference | Field | Type | Required | Description | |----------------------|--------------------|------------|------------------------------------------------------------------------------------------------------------------------------------| | `type` | string | yes | Must be `"scylladb-cql"`. | | `source` | string | yes | Name of the ScyllaDB source to execute the statement on. | | `description` | string | yes | Description of the tool passed to the LLM. | | `statement` | string | yes | CQL statement to execute. | | `authRequired` | []string | no | List of authentication requirements for the source. | | `parameters` | parameters | no | Positional parameters inserted into the prepared CQL statement. | | `templateParameters` | templateParameters | no | Template parameters interpolated into the CQL statement before
it is prepared. Use only when dynamic identifiers are required. | ## Additional Resources * [MCP Toolbox ScyllaDB source reference](https://mcp-toolbox.dev/integrations/scylladb/source/) * [scylladb-cql tool reference](https://mcp-toolbox.dev/integrations/scylladb/tools/scylladb-cql/) * [MCP Toolbox documentation](https://mcp-toolbox.dev/documentation/) * [ScyllaDB Cloud](https://cloud.scylladb.com/) # os-support-per-version.md # OS Support per ScyllaDB Version ScyllaDB is designed to run on modern 64-bit Linux operating systems. To ensure stability, predictable performance, and access to timely fixes, ScyllaDB is officially supported on a defined set of Linux distributions. ## Supported Platforms The following support matrix lists the Linux distributions, container platforms, and cloud images officially [supported](#os-support-definition) for each ScyllaDB version. | Linux Distributions | Ubuntu | | Debian | | Rocky / CentOS / RHEL | | | Amazon Linux | |-------------------------------|-----------------------------------------------------------|---------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------|-----------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------| | ScyllaDB Version / OS Version | 22.04 | 24.04 | 11 | 12 | 8 | 9 | 10 | 2023 | | ScyllaDB 2026.2 | | | | | | | | | | ScyllaDB 2026.1 | | | | | | | | | | ScyllaDB 2025.4 | | | | | | | | | | ScyllaDB 2025.3 | | | | | | | | | | ScyllaDB 2025.2 | | | | | | | | | | ScyllaDB 2025.1 | | | | | | | | | | Enterprise 2024.2 | | | | | | | | | | Enterprise 2024.1 | | `*` | | | | | | | `*` 2024.1.9 and later All ScyllaDB releases are available as a Docker container, EC2 AMI, GCP, and Azure images. ## Definition of Supported Platforms A platform is considered supported when all of the following conditions are met: * A binary installation package is available for download. * The download and installation procedures are tested as part of the ScyllaDB release process for each version. * Automated installation is supported via the [ScyllaDB Web Installer for Linux](https://docs.scylladb.com/manual/stable/getting-started/installation-common/scylla-web-installer.html) (for applicable and recent versions). Platforms outside the supported list may still be usable. ScyllaDB can be [built from source](https://github.com/scylladb/scylladb#build-prerequisites) on other x86_64 or aarch64 Linux systems; however, such deployments are not tested, not validated, and not covered by support guarantees. # query-design.md # Query Design Your data model is heavily influenced by query efficiency. Effective partitioning, clustering columns and denormalization are key considerations for optimizing data access patterns. The way data is partitioned plays a pivotal role in how it’s accessed. An efficient partitioning strategy ensures that data is evenly distributed across the cluster, minimizing hotspots. For example: ```default CREATE TABLE my_keyspace.user_activities_bad ( user_id uuid, activity_date date, log_time timestamp, activity_details text, PRIMARY KEY (user_id, activity_date, log_time) ); ``` In this table, `user_id` is the partition key, ensuring activities are grouped by user, and `activity_date` is the clustering column, ordering activities within each user’s partition. However, this schema is prone to large partition sizes over time, given a user with high activity will create an imbalanced cluster. Clustering columns dictate the order of rows within a partition. They are crucial for range queries. For example: ```default CREATE TABLE my_keyspace.user_activities_good ( user_id uuid, activity_date date, log_time timestamp, log_message text, PRIMARY KEY ((user_id, activity_date), log_time) ); ``` In this table, here the partition is a combination of the `user_id` and `activity_date`, using a technique called “bucketing”. This ensures that there is no unbounded growth within a partition, bucketed to a date. In addition, logs are ordered by `log_time` within each `(user_id, activity_date)` partition, making it efficient to query logs over a time range for a specific user. Your query design should also be optimized for efficient and effective queries to retrieve and manipulate data. Query optimization aims to minimize resource usage and latency while achieving maximum throughput. Indexing is another important aspect of query design. We have already introduced the basic concept of primary keys, which can be made up of two parts: the partition key and optional clustering columns. ScyllaDB also supports [secondary indexes](https://docs.scylladb.com/manual/stable/features/secondary-indexes.html) for non-primary key columns. Secondary indexes can improve query flexibility, but it’s important to consider their impact on performance. For example: ```default CREATE INDEX ON my_keyspace.user_activities (activity_date); ``` This index allows querying activities by date regardless of the user. However, secondary indexes might lead to additional overhead and should be used when necessary. Secondary indexes are built on top of [materialized views](https://docs.scylladb.com/manual/stable/cql/mv.html), which keep a separate, indexed table based on the base table’s data. They can be more performant for reads. ScyllaDB supports CQL for querying data. Learning and mastering CQL is crucial for designing queries. For more detailed instructions, please see our [documentation](https://docs.scylladb.com/manual/stable/cql/). # read-data.md # Reading Data Use the `SELECT` statement to read data. You can specify restrictions with the `WHERE` clause. For example: ```default SELECT * FROM my_keyspace.users WHERE user_id = 123e4567-e89b-12d3-a456-426655440000; ``` Let’s break down the components of this `SELECT` statement: **Keyspace and Table** `my_keyspace.users`: This specifies the keyspace and table from which you want to retrieve data. In this example, you are selecting data from a table named `users` within the `my_keyspace` keyspace. **Columns to Retrieve** In this example, `*` is used as a wildcard character to select all columns from the specified table. This means that you want to retrieve all columns of data for rows that match the specified restriction. **WHERE Clause** `WHERE user_id = 123e4567-e89b-12d3-a456-426655440000`: This part of the statement specifies a restriction for filtering the rows to retrieve. When you execute this `SELECT` statement, ScyllaDB will retrieve all columns for rows that meet the specified restriction from the `users` table within the `my_keyspace` keyspace. You can use more complex restrictions in the `WHERE` clause to filter data based on various criteria. In summary, the `SELECT` statement in ScyllaDB is used to query data from a table within a keyspace. You can specify which columns to retrieve and apply filtering restrictions using the `WHERE` clause to fetch specific rows that match your criteria. See the details about the [SELECT statement](https://docs.scylladb.com/manual/stable/cql/dml/select.html) in the ScyllaDB documentation. # resonate.md # Resonate ![Resonate logo](_static/img/integrations/resonate-logo.png) [Resonate](https://resonatehq.io/) is a durable agent execution engine that makes long-running, failure-prone workflows reliable by persisting their state as *durable promises*. Every function call resolves to a promise written to the database before any work begins. If the process crashes, a new worker reads the last open promise and resumes from exactly that point. [resonate-on-scylladb](https://github.com/resonatehq/resonate-on-scylladb) is a Go implementation of the Resonate server protocol backed by ScyllaDB. ScyllaDB stores all promise, task, and schedule state; the Resonate server runs alongside your existing stack as a single binary. #### NOTE The Resonate server always runs on your own infrastructure. ScyllaDB (self-hosted or ScyllaDB Cloud) is the durable storage backend it connects to. You are not locked in to a hosted workflow service. ## Prerequisites * Docker Compose * Python 3.12+ (for the verification example) ## Self-hosted ScyllaDB The `resonate-on-scylladb` repository ships a `docker-compose.yaml` that starts ScyllaDB and the Resonate server together. The ScyllaDB schema is applied automatically on first startup. 1. Clone the repository: ```bash git clone https://github.com/resonatehq/resonate-on-scylladb.git cd resonate-on-scylladb ``` 1. Start ScyllaDB and the Resonate server: ```bash docker compose --profile server up ``` The Resonate server is now listening on `http://localhost:8001` and ScyllaDB is available on `localhost:9042`. #### NOTE The default `docker-compose.yaml` starts the server with `--debug` enabled, which recreates the ScyllaDB keyspace on every server restart. This is convenient for local development but means durable promises are lost when the server container restarts. To disable this behavior, remove `--debug` from the server’s `command` in `docker-compose.yaml` before running. ## ScyllaDB Cloud When using ScyllaDB Cloud as the backend, run the Resonate server on your own infrastructure and point it at your ScyllaDB Cloud cluster. The Resonate server is **not** hosted in ScyllaDB Cloud, only the durable storage is. 1. Clone the repository and build the server image: ```bash git clone https://github.com/resonatehq/resonate-on-scylladb.git cd resonate-on-scylladb docker build --target server -t resonate-server . ``` 1. Configure and start the server. Find your contact points and credentials on the **Connect** tab of your cluster in the [ScyllaDB Cloud Console](https://cloud.scylladb.com/), then run: ```bash docker run -p 8001:8001 \ -e SCYLLADB_HOSTS="node-0.your-cluster.datacenter.clusters.scylla.cloud,node-1.your-cluster.datacenter.clusters.scylla.cloud,node-2.your-cluster.datacenter.clusters.scylla.cloud" \ -e SCYLLADB_USERNAME="" \ -e SCYLLADB_PASSWORD="" \ -e SCYLLADB_KEYSPACE="resonate" \ resonate-server serve ``` #### WARNING Do not pass `--debug` to the server when connecting to a production ScyllaDB Cloud cluster. Debug mode recreates the keyspace on every server restart, deleting all durable promises. ## Verify with the Python SDK With the server running (either self-hosted or Cloud-backed), install the Resonate Python SDK: ```bash pip install resonate-sdk ``` Write a minimal durable workflow (`hello.py`): ```python import asyncio from resonate.context import Context from resonate.resonate import Resonate async def greet(ctx: Context, name: str) -> str: return f"Hello, {name}!" async def main() -> None: resonate = Resonate(url="http://localhost:8001") resonate.register(greet) try: handle = resonate.run("greet.1", greet, "ScyllaDB") result = await handle.result() print(result) # Hello, ScyllaDB! finally: await resonate.stop() if __name__ == "__main__": asyncio.run(main()) ``` Run the worker: ```bash python hello.py ``` Expected output: ```text Hello, ScyllaDB! ``` #### NOTE The first run may take up to a minute while ScyllaDB initializes the schema and the server processes the task. Subsequent runs with the same promise ID return immediately from the database. The durable promise for `greet.1` is now persisted in ScyllaDB. Kill and restart the worker with the same script, the result is served from the database and the function is not executed again. ## Additional Resources * [resonate-on-scylladb repository](https://github.com/resonatehq/resonate-on-scylladb) * [Resonate documentation](https://docs.resonatehq.io/) * [Resonate Python SDK](https://github.com/resonatehq/resonate-sdk-py) * [Resonate TypeScript SDK](https://github.com/resonatehq/resonate-sdk-ts) # run-scylladb.md # Run ScyllaDB ScyllaDB offers various deployment options, including Docker and ScyllaDB Cloud, making it flexible for different development scenarios. * [Run ScyllaDB in Docker](#create-database-docker) * [Deploy with ScyllaDB Cloud (SaaS)](#create-database-scylladb-cloud) * [Self-deploy in the Cloud or On-premise](#create-database-self-deploy) ## Run ScyllaDB in Docker Docker simplifies the deployment and management of ScyllaDB. By using Docker containers, you can easily create isolated ScyllaDB instances for development, testing, and production. Running ScyllaDB in Docker is the simplest way to experiment with ScyllaDB, and we highly recommend it. If you intend to run ScyllaDB in Docker in production, we recommend using [ScyllaDB Operator](https://operator.docs.scylladb.com/stable/) which will help you manage ScyllaDB clusters within Kubernetes. ### Running a Single Node Execute the following command to run a node: ```sh docker run --name scylla -d scylladb/scylla ``` Docker will start a new container named “scylla” in detached mode using the ScyllaDB image, allowing it to run in the background. It will take a minute or so on a decent internet connection to pull the image from Docker hub and start the container. Read on for more details on how to check your node logs and status. ### Viewing Node Logs To view the running logs of your node, run the following command: ```default docker logs -f scylla ``` The output of this command will look similar to this: ```default INFO 2023-11-13 04:18:44,449 [shard 0] init - starting the view builder INFO 2023-11-13 04:18:44,455 [shard 0] init - starting native transport INFO 2023-11-13 04:18:44,456 [shard 0] cql_server_controller - Starting listening for CQL clients on 172.17.0.2:9042 (unencrypted, non-shard-aware) INFO 2023-11-13 04:18:44,456 [shard 0] cql_server_controller - Starting listening for CQL clients on 172.17.0.2:19042 (unencrypted, shard-aware) INFO 2023-11-13 04:18:44,457 [shard 0] init - serving INFO 2023-11-13 04:18:44,457 [shard 0] init - Scylla version 5.2.9-0.20230920.5709d0043978 initialization completed. ``` Node logs can be useful for troubleshooting and support. ### Checking Node Status You can verify that the cluster is up and running with the following command: ```default docker exec -it scylla nodetool status ``` The output of this command will look similar to this: ```default Datacenter: datacenter1 ======================= Status=Up/Down |/ State=Normal/Leaving/Joining/Moving -- Address Load Tokens Owns Host ID Rack UN 172.17.0.2 632 KB 256 ? 8075882e-3b49-42a4-a742-4caf072844ff rack1 ``` The status “UN” stands for “Up and Normal”. It indicates the node is in a healthy state and actively participating in the data distribution and replication processes. ### Connecting to your Node You can connect to your node with `cqlsh` using the following command: ```default docker exec -it scylla cqlsh ``` The output of this command will look similar to this: ```default Connected to at 172.17.0.2:9042. [cqlsh 5.0.1 | Cassandra 3.0.8 | CQL spec 3.3.1 | Native protocol v4] Use HELP for help. cqlsh> ``` ## Deploy with ScyllaDB Cloud (SaaS) ScyllaDB Cloud is a fully managed service where the ScyllaDB team handles deployment and maintenance of your ScyllaDB clusters. This service is ideal if you’re seeking a cloud-based, ready-to-use ScyllaDB solution. The easiest way to get started with ScyllaDB Cloud is to [create an account](https://cloud.scylladb.com/account/sign-up), start a [free trial](https://cloud.docs.scylladb.com/stable/evaluation/index.html), and follow the [Quick Start Guide](https://cloud.docs.scylladb.com/stable/scylladb-quickstart/index.html) to launch your cluster. ## Self-deploy in the Cloud or On-premise You can install ScyllaDB on your Linux machine using a platform-agnostic installation script we refer to as [ScyllaDB Web Installer for Linux](https://docs.scylladb.com/manual/stable/getting-started/installation-common/scylla-web-installer.html). Run the following command to install ScyllaDB: ```default curl -sSf get.scylladb.com/server | sudo bash ``` By default, running the script installs the latest official version of ScyllaDB. Alternatively, you can install ScyllaDB packages for your platform or launch ScyllaDB on AWS, GCP, or Azure. See [Install ScyllaDB](https://docs.scylladb.com/manual/stable/getting-started/install-scylla/index.html) for a full list of options. # schema-design.md # Schema Design When adopting a query-first data model, the same constraints need to be applied to the schema design. While schema design can evolve to meet your changing application needs, there are certain choices you will need to make to get the most value out of ScyllaDB. This further reinforces the concept of adopting a query-first data model. **Data Types** Selecting the appropriate [data type](https://docs.scylladb.com/manual/stable/cql/types.html) for your columns is critical to your application semantics in your data model. You will need to consider factors such as data size, indexing, and sorting. Let’s say you’re designing a table to store information about e-commerce products, and one of the attributes you want to capture is the product’s price. The choice of data type for the “price” column is crucial for efficient storage and query performance. ```default CREATE TABLE my_keyspace.products ( seller_id uuid, product_id uuid, product_name text, price decimal, description text, PRIMARY KEY (seller_id, price, product_id) ); ``` In this example, for the `price`` column, we’ve chosen the decimal data type. This data type is suitable for storing precise numerical values, such as prices, as it preserves decimal precision. Choosing decimal over other numeric data types like float or double is essential when dealing with financial data to avoid issues with rounding errors. You can efficiently index and query prices using the decimal data type, ensuring fast and precise searches for products within specific price ranges partitioned by `seller_id`. When you need to sort products by `price`, the decimal data type maintains the correct order, even for values with different decimal precision. # schema.md # Schema A schema represents the organization of data in ScyllaDB. ## Keyspace A ScyllaDB keyspace contains tables and defines settings for replication. To create a keyspace, use the following simplified form: ```default CREATE KEYSPACE my_keyspace; ``` ScyllaDB applies default replication settings when explicit replication options are omitted. If you need to control replication explicitly, use the extended form: ```default CREATE KEYSPACE my_keyspace WITH replication = { 'class': 'NetworkTopologyStrategy', 'replication_factor': 3 }; ``` Let’s break down the key concepts related to keyspace creation and replication in ScyllaDB. **Keyspace Creation** To create a keyspace, you use the `CREATE KEYSPACE` command followed by a keyspace name. In the examples above, `my_keyspace` is the name of the keyspace you want to create. **Replication Strategy** Replication in ScyllaDB is the process of storing copies of data across multiple nodes to ensure fault tolerance and high availability. The replication strategy defines how data should be replicated across nodes in the cluster. In the extended example above, the replication strategy is set to `NetworkTopologyStrategy`. This is a commonly used replication strategy in ScyllaDB, especially in production deployments. It allows you to specify the number of replicas for each datacenter separately, which provides fine-grained control over data distribution in a multi-datacenter environment. For example, if you have two datacenters, you can set different replication factors for each datacenter to handle data distribution and fault tolerance according to your specific requirements. **Replication Factor** The replication factor specifies how many copies (or replicas) of each piece of data should be stored in the cluster. In the extended example above, the replication factor is set to 3. This means that each piece of data will be replicated to three different nodes in the cluster. The replication factor determines how many copies of your data exist across the cluster and directly affects fault tolerance and read performance. ## Tables Tables hold your data. Define them with specific column types and primary keys. Here’s how to create a table: ```default CREATE TABLE my_keyspace.users ( user_id uuid PRIMARY KEY, first_name text, last_name text, age int ); ``` Let’s break down the components of this `CREATE TABLE` statement: **Keyspace** The `users` table is created within the `my_keyspace` keyspace. This means that the `users` table belongs to the `my_keyspace` keyspace, and all data stored in this table will be associated with that keyspace. **Table** The name of the table being created is `users`. This name should be unique within the keyspace. **Columns** Columns in ScyllaDB are defined within a table and have a specified data type. In the above `users` table, `user_id`, `first_name`, `last_name`, and `age` are columns which are further explained as follows: * `user_id`: This is a column with the data type `uuid`. It is defined as the `PRIMARY KEY`. The primary key uniquely identifies each row in the table and is used for efficient data retrieval. * `first_name`: This is a column with the data type `text`. It is used to store the user’s first name. * `last_name`: This is another column with the data type `text`, used to store the user’s last name. * `age`: This is a column with the data type `int`, used to store the user’s age. In summary, the `CREATE TABLE` statement in ScyllaDB allows you to define the structure of your table, including column names, data types, and the primary key. This definition is essential for organizing and storing your data efficiently within the keyspace. ## Primary Keys The primary key can be made up of two parts: the partition key and optional clustering columns. The `user_id` column is the partition key in this example. It determines how data gets distributed across the cluster. Additional columns, if present, can be specified as clustering columns, which determine the internal sorting of data within a partition. ```default CREATE TABLE my_keyspace.orders ( order_id uuid, product_id uuid, quantity int, PRIMARY KEY (order_id, product_id) ); ``` In this example, `order_id` is the partition key, and `product_id` is the clustering key. Partitions are determined by the partition key, a part of the primary key. Data is distributed across nodes based on the partition key. In the `orders` table, `order_id` determines the partition. ## Learn More * See [Data Definition](https://docs.scylladb.com/manual/stable/cql/ddl.html) in the ScyllaDB documentation to learn more about defining a schema in ScyllaDB. # scylladb-basics.md # ScyllaDB Basics ## What is ScyllaDB? ScyllaDB is a high-performance NoSQL database optimized for speed and scalability. It is designed to efficiently handle large volumes of data with minimal latency, making it ideal for data-intensive applications. ScyllaDB uses a shared-nothing architecture, contributing to its excellent performance and resource utilization. ScyllaDB comes in two flavors: * **ScyllaDB Cloud** is a managed NoSQL database-as-a-service (DBaaS) running ScyllaDB. It spares you the time and effort of setting up hardware or installing software. ScyllaDB Cloud is available on both AWS and Google Cloud public clouds, so you can choose your preferred cloud provider to run your cluster. * **ScyllaDB** is a high-performance, distributed NoSQL database designed for scalability and low-latency data access, with APIs compatible with Apache Cassandra and Amazon DynamoDB API. You can install it on Linux or launch it on AWS, GCP, or Azure. ## Why ScyllaDB? ScyllaDB is favored for its exceptional capability to manage high data volumes and support rapid read/write operations. It is particularly effective in environments demanding high throughput, low latency, and the ability to scale. The database is also known for its robustness and fault tolerance, ensuring data integrity and availability. ## How do I start with ScyllaDB? If you are new to ScyllaDB, start with the [Develop with ScyllaDB](https://docs.scylladb.com/stable/get-started/develop-with-scylladb/index.md) guide. It will walk you through the basics of running and using ScyllaDB. ## How do I interact with a ScyllaDB cluster? The primary language for communicating with the ScyllaDB database is the [Apache Cassandra Query Language (CQL)](https://docs.scylladb.com/manual/stable/cql/). In addition, ScyllaDB provides drivers in different programming languages, such as Java, Python, Rust, and more, to help you interact with your clusters more efficiently. The drives ensure that queries are distributed evenly and efficiently across the cluster for latencies and the highest overall throughput. See the [driver documentation](https://docs.scylladb.com/stable/drivers/) and the [ScyllaDB University course](https://university.scylladb.com/courses/using-scylla-drivers/) to learn about the drivers. ## How can I monitor my cluster? On ScyllaDB Cloud, you have access to a set of dashboards that let you monitor your cluster’s state in real time. See [Monitoring ScyllaDB Cloud](https://cloud.docs.scylladb.com/stable/monitoring/index.html). For ScyllaDB, you can use [ScyllaDB Monitoring Stack](https://monitoring.docs.scylladb.com/stable/install/index.html), which allows you to view real-time and historical trend information on ScyllaDB clusters. ## How can I learn to use ScyllaDB? Join [ScyllaDB University](https://university.scylladb.com/), which offers a series of free NoSQL database training courses. They were designed as both a ScyllaDB tutorial and a resource for learning basic NoSQL concepts. Start with the [ScyllaDB Essentials course](https://university.scylladb.com/courses/scylla-essentials-overview/), which will help you install and run ScyllaDB and walk you through the key concepts in NoSQL. ## Where can I learn more about ScyllaDB? * Join [ScyllaDB University](https://university.scylladb.com/). * Read the [ScyllaDB documentation](https://docs.scylladb.com/manual/) and [ScyllaDB Cloud documentation](https://cloud.docs.scylladb.com/). * Join the ScyllaDB community: > * Join the [ScyllaDB Community Forum](https://forum.scylladb.com/). > * Join our [Slack Channel](https://slack.scylladb.com/). > * Read our [blog](https://www.scylladb.com/users-blog/). > * Attend ScyllaDB [workshops, webinars, and conferences](https://www.scylladb.com/events/). # third-party-drivers.md # Third-party Drivers ScyllaDB supports the CQL binary protocol version 4, so any Apache Cassandra/CQL driver that implements the same version works with ScyllaDB. However, we recommend using [ScyllaDB drivers](https://docs.scylladb.com/stable/drivers/cql-drivers.md). All ScyllaDB drivers are shard-aware and provide additional benefits over third-party drivers. * [DataStax Java Driver](https://github.com/datastax/java-driver/) * [DataStax Python Driver](https://github.com/datastax/python-driver/) * [DataStax C# Driver](https://github.com/datastax/csharp-driver/) * [DataStax Ruby Driver](https://github.com/datastax/ruby-driver/) * [DataStax Node.js Driver](https://github.com/datastax/nodejs-driver/) * [DataStax C++ Driver](https://github.com/datastax/cpp-driver/) * [DataStax PHP Driver (Supported versions: 7.1)](https://github.com/datastax/php-driver) * [He4rt PHP Driver (Supported versions: 8.1 and 8.2)](https://github.com/he4rt/scylladb-php-driver/) * [Scala Phantom Project](https://github.com/outworkers/phantom) * [Xandra Elixir Driver](https://github.com/lexhide/xandra) * [Exandra Elixir Driver](https://github.com/vinniefranco/exandra) # tutorials-example-projects.md # Tutorials and Example Projects The tutorials and example project will help you learn how to use ScyllaDB as a data source for an application. ## Getting Started with ScyllaDB Cloud [Getting Started with ScyllaDB Cloud](https://cloud-getting-started.scylladb.com/) is a step-by-step guide to building a Media Player project connected to ScyllaDB Cloud. It includes examples for NodeJS, Java, Python, Rust, Ruby, Elixir, C#, and Go. ## Vector Search With the [Vector Search sample application tutorial](https://vector-search.scylladb.com/), you’ll learn how you can use ScyllaDB Vector Search to build RAG applications, semantic caching layers, and how it works together with popular LLM libraries like LlamaIndex and LangChain. ## Video Streaming The [Video Streaming sample application](https://video-streaming.scylladb.com) will guide you through the process of creating a video streaming application using ScyllaDB Cloud and NextJS. ## Care Pet Project [Care Pet](https://iot.scylladb.com/) is a step-by-step guide to building an IoT project connected to ScyllaDB Cloud. ## ML Feature Store Our [Feature Store sample application and tutorial](https://feature-store.scylladb.com/) help you build a real-time feature store with ScyllaDB in Python. ## Shopping Cart The [Shopping Cart sample application](https://shopping-cart.scylladb.com/stable/) will guide you through the process of creating a new ScyllaDB cluster and running the shopping cart API server. # update-data.md # Updating Data Update data using the `UPDATE` statement. For example: ```default UPDATE my_keyspace.users SET age = 78 WHERE user_id = 123e4567-e89b-12d3-a456-426655440000; ``` Let’s break down the components of this `UPDATE` statement: **Keyspace and Table** `my_keyspace.users`: This specifies the keyspace and table from which you want to update data. In this example, you are updating data in a table named `my_table` within the `my_keyspace` keyspace. **Column Update** `SET age = 78`: This part of the statement specifies the update operation. You are setting the value of the age column to `78` for rows that match the specified restriction. **WHERE Clause** `WHERE user_id = 123e4567-e89b-12d3-a456-426655440000`: This part of the statement specifies the affected partition key, which is mandatory. #### NOTE Unlike in SQL, `UPDATE` does not check the prior existence of the row by default: the row is created if none existed before, and updated otherwise. This behavior can be changed by using ScyllaDB’s [Lightweight Transaction](https://docs.scylladb.com/manual/stable/features/lwt.html) `IF NOT EXISTS` or `IF EXISTS` clauses. In summary, the `UPDATE` statement in ScyllaDB is used to modify existing data in a table. Always include a `WHERE` clause with a suitable restriction to target the specific rows you want to update, and specify the changes you want to make using the SET clause. This helps you ensure the accuracy and precision of your updates. See the details about the [UPDATE statement](https://docs.scylladb.com/manual/stable/cql/dml/update.html) in the ScyllaDB documentation. # upgrade-policy.md # Upgrade Policy ScyllaDB upgrade is a rolling procedure - it does not require a full cluster shutdown and is performed without any downtime or disruption of service. ## Rules and Guidelines * To ensure a successful upgrade, follow the [documented upgrade procedures](https://docs.scylladb.com/manual/stable/upgrade/) tested by ScyllaDB. * You should upgrade to a supported version of ScyllaDB. See [ScyllaDB Version Support](https://docs.scylladb.com/stable/versioning/version-support.md). * All nodes in the cluster must be on the same version before advancing to the next version. ## Upgrade Paths ### Major Releases (LTS) * You can upgrade from the a major version to the next major version, skipping intermediate minor releases. * You cannot skip major versions. Upgrades must proceed from one major version to the next. * Example: 2025.1 → 2026.1 ### Minor Releases (Feature Releases) In version 2025.4, we updated the upgrade policy to allow non-consecutive minor upgrades. You can upgrade to: * Any minor version within the same major release. Examples: 2025.1 → 2025.4, 2026.x → 2026.y * The next major (LTS) version. Example: 2025.x → 2026.1 For **versions earlier than 2025.4**, minor upgrades must be performed consecutively — each successive X.Y version must be installed in order, without skipping any major or minor version. ### Patch Releases Upgrading to each patch version by following the *Maintenance Release Upgrade Guide* is optional. However, we recommend upgrading to the latest patch release for your version before upgrading to a new version. ## Downgrade Downgrade is not available as a standard operation. Reverting to a previous version is only possible during the rolling upgrade process, where it is referred to as a rollback. Rollback is possible only while some nodes in the cluster have not yet been upgraded. Once the final node is started with the new version, rollback is no longer possible. After that, the only way to return to a previous version is to restore the cluster from backup. In cases where a downgrade is necessary, please contact ScyllaDB support for assistance. # version-support.md # ScyllaDB Version Support ## Supported Versions | Version | Released | Status | End of Life (EOL) | |---------------------------------------------------------------------------------------------------------|----------------|---------------|------------------------------------------------------------------------------------| | [ScyllaDB 2026.2](https://docs.scylladb.com/manual/branch-2026.2/getting-started/install-scylla/) | June 2026 | Supported | After 2026.4 is released (see [Version Support Policy](#version-support-policy)) | | [ScyllaDB 2026.1 (LTS)](https://docs.scylladb.com/manual/branch-2026.1/getting-started/install-scylla/) | March 2026 | Supported | After 2028.1 is released (see [Version Support Policy](#version-support-policy)) | | ScyllaDB 2025.4 | December 2025 | Not supported | June 2026 | | ScyllaDB 2025.3 | September 2025 | Not supported | March 2026 | | ScyllaDB 2025.2 | July 2025 | Not supported | December 2025 | | [ScyllaDB 2025.1 (LTS)](https://docs.scylladb.com/manual/branch-2025.1/getting-started/install-scylla/) | April 2025 | Supported | After 2027.1 is released (see [Version Support Policy](#version-support-policy)) | | Enterprise 2024.2 | November 2024 | Not supported | July 2025 | | Enterprise 2024.1 (LTS) | February 2024 | Not supported | March 2026 | | Enterprise 2023.1 (LTS) | August 2023 | Not supported | April 2025 | | Enterprise 2022.2 | January 2023 | Not supported | June 2024 | | Enterprise 2022.1 (LTS) | August 2022 | Not supported | June 2024 | ## Version Numbering ScyllaDB follows the MAJOR.MINOR.PATCH [semantic versioning](https://semver.org/): * `MAJOR` versions contain significant changes in the product and may introduce incompatible API changes. * `MINOR` versions introduce new features and improvements in a backward-compatible manner. * `PATCH` versions have backward-compatible bug fixes. ![image](versioning/images/versioning.png) ## LTS vs. Feature Releases Long-Term Support (LTS) * Released approximately once a year. * Two last LTS versions are supported. Feature releases: * 2-4 feature releases per year. You can only use LTS releases (upgrading to the latest patch release for the greatest stability) or follow the feature and LTS releases for the latest feature set. ## Version Support Policy * The last two LTS versions are supported. * The last two *major.minor* versions (Feature or LTS release) are supported. **Example** * When 2024.2 (Feature) is released, the following are supported: * 2024.1 and 2023.1 (the last two LTS) * 2024.2 (Feature) and 2024.1 (LTS) * When 2025.1 (LTS) is released, the following are supported: * 2025.1 and 2024.1 (the last two LTS) * 2024.2 (Feature) * When 2025.2 (Feature) is released, the following are supported: * 2025.1 and 2024.1 (the last two LTS) * 2025.2 (Feature) ### Patch Versions All supported versions (major and minor, LTS and Feature) will get patch releases when required. We recommend upgrading to the latest patch version. You should especially upgrade to the latest patch of your current version before upgrading to a new major or minor version. ## Upgrade Policy To learn about the upgrade policy, see the [About Upgrade](https://docs.scylladb.com/manual/stable/upgrade/about-upgrade.html) section in the ScyllaDB documentation.