DataStax Cassandra Driver

Warnings

• breaking Major API changes were introduced between 2.x and 3.x series, affecting `Cluster.connect()` method signatures, result set iteration, and asynchronous APIs. Direct upgrades without code changes will likely fail.
  Fix: Consult the official 'Upgrading from Older Drivers' guide in the documentation (e.g., `docs.datastax.com/en/developer/python-driver/3.29/changelog/#upgrading-from-older-drivers`) for detailed migration steps.
• gotcha Failing to call `.shutdown()` on `Cluster` and `Session` objects can lead to resource leaks (e.g., open connections, threads) and prevent application processes from exiting cleanly, especially in long-running applications or multi-process/multi-threaded contexts.
  Fix: Always ensure `cluster.shutdown()` and `session.shutdown()` are called in a `finally` block to guarantee resource release. The objects do not support direct `with Cluster(...) as cluster:` context management, requiring explicit shutdown.
• gotcha Creating new `Cluster` or `Session` objects for every database operation is a significant performance anti-pattern. These objects are designed to be long-lived, thread-safe, and shared throughout the application, managing connection pools efficiently.
  Fix: Instantiate `Cluster` and `Session` objects once per application lifecycle and reuse them. Store them in a global singleton, an application context, or pass them as dependencies.
• gotcha Prepared statements are cached by the driver. If the schema of a table (e.g., columns added/removed, types changed) changes after a statement has been prepared, existing prepared statements might become invalid or lead to runtime errors (e.g., `InvalidQueryError`). The driver does not automatically re-prepare statements upon schema changes.
  Fix: If schema changes are anticipated, consider clearing the prepared statement cache (`session.clear_cache()`) or re-preparing affected statements explicitly after the schema update. Design your application to handle `InvalidQueryError` for prepared statements gracefully.

Install

• pip install cassandra-driver Default Install

Imports

• Cluster

  from cassandra.cluster import Cluster

• PlainTextAuthProvider

  from cassandra.auth import PlainTextAuthProvider

• ConsistencyLevel

  from cassandra import ConsistencyLevel

• BatchStatement

  from cassandra.query import BatchStatement

Quickstart

This quickstart connects to a local Cassandra instance (at 127.0.0.1), creates a keyspace and table if they don't exist, inserts a row, and then queries data. For production environments or Astra DB, `contact_points` should be set to your cluster's actual endpoints, and `PlainTextAuthProvider` should be used with credentials (e.g., from environment variables) for secure connections. Ensure `Cluster` and `Session` objects are properly shut down to release resources.

from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider # For secure connections
import os

# For local Cassandra, 'contact_points' can be ['127.0.0.1']
# For Astra DB or secure clusters, specify contact_points and auth_provider
# using credentials from environment variables.
# Example: CONTACT_POINTS = ['your.cassandra.host']
#          ASTRA_CLIENT_ID = os.environ.get('ASTRA_CLIENT_ID', '')
#          ASTRA_CLIENT_SECRET = os.environ.get('ASTRA_CLIENT_SECRET', '')

# For a basic local connection:
cluster = Cluster(['127.0.0.1']) # Or specify actual contact points
session = None
try:
    session = cluster.connect() # Connects to a default or specified keyspace

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

    session.execute("""
        CREATE TABLE IF NOT EXISTS users (
            id UUID PRIMARY KEY,
            name text,
            age int
        )
    """)
    print("Table 'users' created or already exists.")

    session.execute(
        "INSERT INTO users (id, name, age) VALUES (uuid(), %s, %s)",
        ("John Doe", 30)
    )
    print("Data inserted.")

    rows = session.execute("SELECT name, age FROM users WHERE age > 25")
    for row in rows:
        print(f"User: {row.name}, Age: {row.age}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if session:
        session.shutdown()
    if cluster:
        cluster.shutdown()