Scylla Driver for Apache Cassandra

Warnings

• breaking Python 3.8 and 3.9 are no longer officially supported by the driver as of recent versions (e.g., 3.29.5 dropped Python 3.9, 3.29.4 dropped Python 3.8). While PyPI metadata indicates `>=3.9`, the official documentation states support for Python 3.10-3.14.
  Fix: Upgrade your Python environment to 3.10 or newer for full compatibility and support.
• breaking Support for Cassandra native protocol versions 1 and 2 has been removed. Connections to very old ScyllaDB or Apache Cassandra clusters that only support these protocols will fail.
  Fix: Ensure your ScyllaDB or Cassandra cluster supports native protocol version 3 or higher. Most modern deployments will already meet this requirement.
• gotcha The driver's build system has moved from `setup_requires` to PEP 517. While this improves modern Python packaging, it might affect users with custom or older build environments if they were relying on `setup_requires` behavior.
  Fix: If encountering build issues, ensure your `pip` is up-to-date and your environment correctly handles PEP 517 builds. Avoid using `--no-build-isolation` if you are not managing build dependencies manually.
• gotcha The default event loop in Python versions prior to 3.12 utilized `asyncore`. With `asyncore` being removed entirely in Python 3.12, users must explicitly configure an alternative event loop like `libev`, `gevent`, or `eventlet` when running on Python 3.12+ if they relied on the default.
  Fix: For Python 3.12 and later, explicitly configure a supported event loop for the driver, e.g., by installing `libev` (`pip install pyuv`) or `gevent` (`pip install gevent`) and configuring the cluster to use it.
• deprecated The `Session.default_consistency_level` attribute is deprecated. Relying on this attribute may lead to future compatibility issues.
  Fix: Instead of `Session.default_consistency_level`, specify the consistency level per statement or through Execution Profiles for better control and future compatibility.

Install

• pip install scylla-driver Install stable version

Imports

• Cluster

  from cassandra.cluster import Cluster

  The Scylla driver uses the 'cassandra' namespace for its core components, even though the package is installed as 'scylla-driver'. This can be a common point of confusion for new users.
• Session

  from cassandra.cluster import Cluster; session = cluster.connect()

  Session objects are created from a Cluster instance.
• PlainTextAuthProvider

  from cassandra.auth import PlainTextAuthProvider

  Used for plain-text username/password authentication.

Quickstart

This quickstart demonstrates how to establish a connection to a ScyllaDB or Cassandra cluster, create a keyspace and table, insert data, and retrieve it. It uses environment variables for credentials, suitable for secure deployment.

import os
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider

# Replace with your ScyllaDB/Cassandra contact points and credentials
CONTACT_POINTS = os.environ.get('SCYLLA_CONTACT_POINTS', '127.0.0.1').split(',')
USERNAME = os.environ.get('SCYLLA_USERNAME', 'scylla')
PASSWORD = os.environ.get('SCYLLA_PASSWORD', 'password')

auth_provider = PlainTextAuthProvider(username=USERNAME, password=PASSWORD)

cluster = None
session = None
try:
    cluster = Cluster(contact_points=CONTACT_POINTS, auth_provider=auth_provider)
    session = cluster.connect()

    # Example: Create a keyspace and table (if they don't exist)
    session.execute(
        """CREATE KEYSPACE IF NOT EXISTS mykeyspace WITH replication = {'class': 'NetworkTopologyStrategy', 'datacenter1': 1}"""
    )
    session.set_keyspace('mykeyspace')
    session.execute(
        """CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name text, email text)"""
    )

    # Example: Insert data
    user_id = session.execute("SELECT uuid() FROM system.local").one()[0]
    session.execute(
        """INSERT INTO users (id, name, email) VALUES (%s, %s, %s)""",
        (user_id, "Alice", "alice@example.com")
    )
    print(f"Inserted user: {user_id}")

    # Example: Select data
    rows = session.execute("SELECT id, name, email FROM users WHERE id = %s", (user_id,))
    for row in rows:
        print(f"Retrieved user: {row.id}, {row.name}, {row.email}")

finally:
    if session:
        session.shutdown()
    if cluster:
        cluster.shutdown()