TerraScale.CqlDriver

High-performance CQL driver for ScyllaDB/Cassandra with AOT support.

Features

• Custom CQL binary protocol v4 implementation
• Connection pooling with stream multiplexing
• Prepared statement caching
• Full type codec support (primitives + collections)
• PLAIN SASL authentication
• TLS/SSL support
• System.Text.Json serialization (AOT-compatible)
• FluentResults error handling

Installation

dotnet add package TerraScale.CqlDriver

Quick Start

using TerraScale.CqlDriver;
using TerraScale.CqlDriver.Client;
using TerraScale.CqlDriver.Configuration;

// Create client
var options = new CqlClientOptions
{
    ContactPoints = ["localhost"],
    Port = 9042,
    Keyspace = "my_keyspace",
    Authentication = new AuthenticationOptions
    {
        Username = "cassandra",
        Password = "cassandra"
    }
};

await using var client = new CqlClient(options);

// Execute a query
var result = await client.ExecuteAsync("SELECT * FROM users WHERE id = ?", [userId]);
if (result.IsSuccess)
{
    foreach (var row in result.Value)
    {
        Console.WriteLine($"User: {row.GetString("name")}");
    }
}

// Prepare and execute
var prepared = await client.PrepareAsync("INSERT INTO users (id, name) VALUES (?, ?)");
if (prepared.IsSuccess)
{
    var bound = prepared.Value.Bind(Guid.NewGuid(), "Alice");
    await client.ExecuteAsync(bound);
}

// Batch operations
var batch = new BatchBuilder()
    .Add("INSERT INTO users (id, name) VALUES (?, ?)", Guid.NewGuid(), "Bob")
    .Add("INSERT INTO users (id, name) VALUES (?, ?)", Guid.NewGuid(), "Charlie");

await client.ExecuteBatchAsync(batch);

Dependency Injection

// Program.cs
builder.Services.AddCqlClient(new CqlClientOptions
{
    ContactPoints = ["scylla-node1", "scylla-node2"],
    Port = 9042,
    Keyspace = "my_keyspace",
    DefaultConsistency = ConsistencyLevel.LocalQuorum
});

// Usage
public class UserService(ICqlClient cqlClient)
{
    public async Task<User?> GetUserAsync(Guid id)
    {
        var result = await cqlClient.ExecuteAsync(
            "SELECT * FROM users WHERE id = ?", [id]);

        if (result.IsFailed || result.Value.Count == 0)
            return null;

        var row = result.Value[0];
        return new User
        {
            Id = row.GetGuid("id"),
            Name = row.GetString("name")!
        };
    }
}

Configuration Options

Pooling Options

Authentication Options

options.Authentication = new AuthenticationOptions
{
    Username = "cassandra",
    Password = "cassandra"
};

TLS Options

options.Tls = new TlsOptions
{
    ValidateCertificate = true,
    CaCertificatePath = "/path/to/ca.crt",
    ClientCertificatePath = "/path/to/client.crt",
    ClientKeyPath = "/path/to/client.key"
};

Type Mappings

Consistency Levels

ConsistencyLevel.Any          // Response from any replica
ConsistencyLevel.One          // Response from one replica
ConsistencyLevel.Two          // Response from two replicas
ConsistencyLevel.Three        // Response from three replicas
ConsistencyLevel.Quorum       // Majority of replicas
ConsistencyLevel.All          // All replicas
ConsistencyLevel.LocalQuorum  // Majority in local datacenter (default)
ConsistencyLevel.EachQuorum   // Majority in each datacenter
ConsistencyLevel.LocalOne     // One replica in local datacenter

Error Handling

The driver uses FluentResults for error handling:

var result = await client.ExecuteAsync("SELECT * FROM users");

if (result.IsSuccess)
{
    // Process rows
    foreach (var row in result.Value)
    {
        // ...
    }
}
else
{
    // Handle error
    Console.WriteLine($"Error: {result.Errors[0].Message}");
}

For specific error types, catch the exceptions:

try
{
    await client.ExecuteAsync("INVALID QUERY");
}
catch (SyntaxException ex)
{
    Console.WriteLine($"Syntax error: {ex.Message}");
}
catch (UnavailableException ex)
{
    Console.WriteLine($"Not enough replicas: {ex.Required} required, {ex.Alive} alive");
}
catch (ReadTimeoutException ex)
{
    Console.WriteLine($"Read timeout: {ex.Received}/{ex.BlockFor} responses");
}

Related

• TerraScale Documentation
• TerraScale.Database.Client - Native REST client (recommended)
• SQL API Reference