Cassandra Protocol Configuration

Complete configuration reference for HeliosDB's Cassandra CQL protocol implementation.

Server Configuration

Network Settings

[cassandra]
# Listen address for CQL native protocol
listen_address = "0.0.0.0"

# CQL native protocol port (default: 9042)
port = 9042

# Maximum concurrent connections
max_connections = 1000

# Connection timeout in seconds
connection_timeout = 10

# Idle connection timeout (0 = disabled)
idle_timeout = 0

Protocol Settings

[cassandra.protocol]
# Supported protocol versions
min_version = 4
max_version = 5

# Maximum frame size (bytes)
max_frame_size = 268435456  # 256MB

# Enable compression
compression_enabled = true
compression_algorithms = ["lz4", "snappy"]

# Request timeout (ms)
request_timeout = 12000

Authentication

[cassandra.auth]
# Enable authentication
enabled = true

# Authenticator type: "AllowAll", "Password"
authenticator = "Password"

# Authorizer type: "AllowAll", "CassandraAuthorizer"
authorizer = "AllowAll"

# Role manager
role_manager = "CassandraRoleManager"

# Credentials validity period (ms)
credentials_validity = 2000

# Permission validity period (ms)
permissions_validity = 2000

Keyspace Settings

[cassandra.keyspace]
# Default keyspace (optional)
default_keyspace = ""

# System keyspace replication
system_keyspace_replication = { class = "SimpleStrategy", replication_factor = 1 }

# Auto-create keyspaces
auto_create_keyspaces = true

Query Settings

[cassandra.query]
# Enable prepared statement cache
prepared_cache_enabled = true

# Prepared statement cache size
prepared_cache_size = 1000

# Page size default
default_page_size = 5000

# Maximum page size
max_page_size = 50000

# Allow filtering
allow_filtering = true

Batch Settings

[cassandra.batch]
# Enable batch operations
enabled = true

# Maximum batch size (statements)
max_batch_size = 65535

# Batch timeout (ms)
batch_timeout = 10000

# Logged batch by default
logged_by_default = true

Connection String Format

Driver Configuration

Java (DataStax)

CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("localhost", 9042))
    .withLocalDatacenter("datacenter1")
    .withAuthCredentials("username", "password")
    .withKeyspace("my_keyspace")
    .build();

Python (cassandra-driver)

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

auth = PlainTextAuthProvider(username='user', password='password')
cluster = Cluster(
    ['localhost'],
    port=9042,
    auth_provider=auth,
    protocol_version=5
)
session = cluster.connect('my_keyspace')

Node.js (cassandra-driver)

const cassandra = require('cassandra-driver');

const client = new cassandra.Client({
    contactPoints: ['localhost'],
    localDataCenter: 'datacenter1',
    keyspace: 'my_keyspace',
    authProvider: new cassandra.auth.PlainTextAuthProvider('user', 'password'),
    protocolOptions: { port: 9042 }
});

Go (gocql)

cluster := gocql.NewCluster("localhost")
cluster.Port = 9042
cluster.Keyspace = "my_keyspace"
cluster.Authenticator = gocql.PasswordAuthenticator{
    Username: "user",
    Password: "password",
}
cluster.ProtoVersion = 4

session, err := cluster.CreateSession()

Connection Pool Settings

Java Driver

CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("localhost", 9042))
    .withLocalDatacenter("datacenter1")
    .withPoolingOptions(
        new PoolingOptions()
            .setCoreConnectionsPerHost(HostDistance.LOCAL, 1)
            .setMaxConnectionsPerHost(HostDistance.LOCAL, 4)
            .setCoreConnectionsPerHost(HostDistance.REMOTE, 1)
            .setMaxConnectionsPerHost(HostDistance.REMOTE, 2)
            .setMaxRequestsPerConnection(HostDistance.LOCAL, 32768)
    )
    .build();

Python Driver

from cassandra.cluster import Cluster, ExecutionProfile
from cassandra.policies import RoundRobinPolicy

profile = ExecutionProfile(
    load_balancing_policy=RoundRobinPolicy(),
    request_timeout=10
)

cluster = Cluster(
    ['localhost'],
    execution_profiles={'default': profile},
    protocol_version=5,
    idle_heartbeat_interval=30
)

Consistency Levels

Server Configuration

[cassandra.consistency]
# Default read consistency
default_read_consistency = "LOCAL_QUORUM"

# Default write consistency
default_write_consistency = "LOCAL_QUORUM"

# Serial consistency
default_serial_consistency = "SERIAL"

Client Configuration

from cassandra import ConsistencyLevel
from cassandra.query import SimpleStatement

# Query with specific consistency
query = SimpleStatement(
    "SELECT * FROM users WHERE user_id = ?",
    consistency_level=ConsistencyLevel.QUORUM
)
session.execute(query, [user_id])

Retry Policies

Java Driver

CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("localhost", 9042))
    .withLocalDatacenter("datacenter1")
    .withRetryPolicy(new DefaultRetryPolicy())
    .build();

Python Driver

from cassandra.policies import RetryPolicy

class CustomRetryPolicy(RetryPolicy):
    def on_read_timeout(self, query, consistency, required_responses,
                        received_responses, data_retrieved, retry_num):
        if retry_num < 3:
            return (self.RETRY, consistency)
        return (self.RETHROW, None)

Compression

Server Configuration

[cassandra.compression]
# Enable compression
enabled = true

# Preferred algorithm: "lz4", "snappy"
algorithm = "lz4"

# Compression level (1-22 for lz4, 1-9 for snappy)
level = 3

Client Configuration

from cassandra.cluster import Cluster

cluster = Cluster(
    ['localhost'],
    compression=True  # Auto-negotiate
)

SSL/TLS Configuration

Server Configuration

[cassandra.ssl]
# Enable SSL
enabled = false

# Certificate files
cert_file = "/etc/heliosdb/cassandra.crt"
key_file = "/etc/heliosdb/cassandra.key"
ca_file = "/etc/heliosdb/ca.crt"

# Require client certificate
require_client_cert = false

# Cipher suites
ciphers = ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"]

Client Configuration

from cassandra.cluster import Cluster
from ssl import SSLContext, PROTOCOL_TLS_CLIENT

ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
ssl_context.load_verify_locations('/path/to/ca.crt')

cluster = Cluster(
    ['localhost'],
    ssl_context=ssl_context
)

Performance Tuning

Query Optimization

[cassandra.performance]
# Query trace threshold (ms)
trace_threshold_ms = 100

# Log slow queries
log_slow_queries = true

# Slow query threshold (ms)
slow_query_threshold_ms = 500

# Enable query cache
query_cache_enabled = true

# Query cache size (MB)
query_cache_size = 256

Memory Settings

[cassandra.memory]
# Native transport max concurrent connections
native_transport_max_concurrent_connections = 128

# Native transport max frame size (bytes)
native_transport_max_frame_size = 268435456

# Request timeout (ms)
request_timeout = 10000

Monitoring

cqlsh Commands

-- Show cluster info
DESCRIBE CLUSTER;

-- Show keyspaces
DESCRIBE KEYSPACES;

-- Show tables
DESCRIBE TABLES;

-- Show table schema
DESCRIBE TABLE my_table;

-- Enable tracing
TRACING ON;
SELECT * FROM users WHERE user_id = ?;
TRACING OFF;

System Tables

-- Query system tables
SELECT * FROM system.peers;
SELECT * FROM system.local;
SELECT * FROM system_schema.keyspaces;
SELECT * FROM system_schema.tables WHERE keyspace_name = 'my_keyspace';

---

Related: README.md | COMPATIBILITY.md | EXAMPLES.md

Last Updated: December 2025