---
title: "Cassandra Protocol Configuration"
---

# Cassandra Protocol Configuration

:::caution[What the listener serves today]
HeliosDB Full opens listeners for PostgreSQL, MySQL, Oracle, MongoDB,
Cassandra, Redis and SQL Server plus an HTTP gateway; MongoDB, Cassandra and SQL
Server clients can connect and authenticate, and reading and writing HeliosDB tables
through them is planned. Standard Cassandra drivers, including
the DataStax drivers and cqlsh, cannot connect yet; driver compatibility for the CQL
listener is planned. The features on this page describe the planned surface.
:::

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

## Server Configuration

### Network Settings

```toml
[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

```toml
[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

```toml
[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

```toml
[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

```toml
[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

```toml
[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)

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

#### Python (cassandra-driver)

```python
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)

```javascript
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)

```go
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

```java
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

```python
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

```toml
[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

```python
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

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

### Python Driver

```python
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

```toml
[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

```python
from cassandra.cluster import Cluster

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

## SSL/TLS Configuration

### Server Configuration

```toml
[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

```python
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

```toml
[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

```toml
[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

```cql
-- 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

```cql
-- 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](https://www.heliosdb.com/docs/full/reference/protocols/cassandra/readme/) | [COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/cassandra/compatibility/) | [EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/cassandra/examples/)