Get started with the C# driver

Because DataStax Enterprise (DSE) is based on Apache Cassandra®, you can use Cassandra drivers to connect to your DSE databases.

This quickstart explains how to install a driver, connect it to your DSE database, and then send some CQL statements to the database.

To use the C# driver, you need to choose a compatible version, install the driver and its dependencies, and then connect the driver to your DSE database. Once connected, you can write scripts that use the driver to run commands against your database.

C# driver compatibility

DataStax officially supports the latest 12 months of releases, and DataStax recommends using the latest driver version whenever possible. Compatibility isn’t guaranteed for earlier versions. For upgrade guides and compatibility information for earlier versions, see Unsupported drivers.

New features and bug fixes are developed on the latest minor version of the driver, and users are encouraged to stay current with those minor releases. APIs are maintained stable according to semantic versioning conventions, and upgrades should be trivial.

Unless otherwise specified, compatibility version ranges include all patch versions. For example, a range of 4.0 to 4.3 includes all versions from 4.0.0 to the last 4.3.z release.

C# driver compatibility
Driver version DSE 6.9 DSE 6.8 DSE 5.1 Comments

3.21 and later Latest CassandraCSharpDriver release on NuGet

Fully compatible

Fully compatible

Fully compatible

3.16 to 3.20

Partially compatible

Fully compatible

Fully compatible

Doesn’t support the vector type.

3.13 to 3.15

Partially compatible

Partially compatible

Fully compatible

Doesn’t support the vector type.

Doesn’t support DataStax Graph, which was introduced in DSE 6.8. Compatible with legacy DSE Graph only.

Earlier versions

Not compatible

Not compatible

Not compatible

Prepare the environment and database

To use this driver, you need the following:

Authentication methods for drivers

The DSE-compatible drivers ship with built-in authentication providers that provide the necessary utilities to connect to secure DSE clusters. However, DSE clusters have no authentication service enabled by default. This simplifies initial setup, but it isn’t intended for production deployments. You must configure your preferred authentication method, security schemes, users, and roles in your clusters before attempting to use a non-default authentication method through a driver. The required credentials for the driver connection depend on your cluster and authentication method.

DSE unified authentication provides a single, flexible security model. One DSE server can accept multiple forms of authentication, and clients with different levels of access can use varying authentication schemes to connect to the same server.

Supported authentication methods include internal usernames and passwords, LDAP/Active Directory usernames and passwords, and Kerberos authentication. All of these features are supported directly in most DSE-compatible drivers with built-in classes to enable the desired security configuration. Some drivers include support for custom authentication provider classes if your desired authentication method isn’t supported by the built-in providers.

Internal username and password authentication

Always use this method in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.

Drivers use a plain text authentication provider to perform internal username and password authentication. For DSE, the driver sends a plain text username and password to the server that authenticates to the underlying Authentication scheme.

To authenticate with a username and password, provide the username and password in the driver configuration. For example, in a test environment, you could use superuser credentials. In production, use narrowly scoped user roles for better security.

In addition to traditional role-based access control (RBAC), DSE supports proxy authentication (authorization through proxy roles). With proxy authentication, the driver authenticates with a fixed set of credentials that authorize access to a cluster in lieu of direct role assignment. The driver uses the credentials to connect to the cluster and execute requests (with proxy execute) within the context of the proxy roles.

This guide uses username and password authentication for simplicity. For examples of other authentication methods, including proxy authentication, see your driver’s documentation.
LDAP/Active Directory authentication

Always use this method in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.

Drivers use a plain text authentication provider to perform LDAP/Active Directory username and password authentication. For DSE, the driver sends a plain text username and password to the server that authenticates to the underlying LDAP scheme.

For usage instructions and examples, see your driver’s documentation.

Kerberos authentication

Most DSE-compatible drivers extend authentication providers to support Kerberos authentication for DSE either directly or through custom provider implementations.

The C# driver uses the Microsoft security framework SSPI for Kerberos support, including management of the Kerberos configuration files, keytabs, and ticket caches. Functionally, the driver obtains a Kerberos ticket during system login, and then uses that ticket to authenticate with the cluster.

For more information, see Authentication for the C# driver.

SSL-encrypted connections for drivers

Cassandra drivers support SSL-encrypted connections between the driver and server. Encrypted driver connections follow a typical SSL workflow:

  1. The client opens a TCP connection to the server on the configured SSL port.

  2. An SSL handshake is initialized by the server, sending its public key (or certificate) to the client.

  3. The client uses that public key certificate to generate an encrypted session key and sends it back to the server.

  4. The server decrypts the message using its private key and retrieves the session key.

  5. All communication from that point on is encrypted using that session key.

SSL isn’t required, but it is recommended for production deployments, especially those with clients communicating over the public internet.

To use SSL-encrypted connections, you must do the following:

  1. Select an identity verification method:

    No identity verification (Not recommended)

    As a best practice for secure driver communication, never use SSL without identity verification. Always use either client-to-server or server-to-client identity verification.

    While most drivers support creating SSL connections to the server without identity verification, DataStax doesn’t recommend this for production deployments. When a secure browser contacts a web server, the browser verifies the identity of the server before sending it requests in case an attacker is masquerading as the web server. A secure communication to a bad actor defeats the purpose of configuring secure communication between the browser and web server in the first place.

    Client verifies server

    To verify the identity of a server, the driver must be configured with a list of trusted certificate authorities (CAs). When the driver receives the server’s SSL certificate during the SSL handshake, it checks that the certificate was signed by one of the registered CAs. If the certificate wasn’t signed by a registered CA, the client checks that the signer was signed by one of the registered CAs. It continues through the signers until it finds one that is in the client’s list of trusted CAs. If the client doesn’t find a registered CA, then identity verification fails.

    Server verifies client

    To configure a server to verify the identity of a client, edit cassandra.yaml, find client_encryption_options, and then set require_client_auth to true. This scenario requires that clients have their own certificates to send to the server upon request during the SSL handshake. For more information, see Configure SSL for client-to-node connections in DSE.

  2. Configure SSL in your DSE cluster.

    By default DSE clusters are configured to communicate with clients using an unencrypted binary protocol. This is convenient for getting started but it isn’t suitable for production environments.

    To enable SSL in a DSE cluster, you need access to your cluster’s cassandra.yaml file. The location of the cassandra.yaml file depends on your DSE installation method. For information about editing cassandra.yaml and configuring SSL, see Configure SSL for DataStax Enterprise.

  3. Configure your driver to use the SSL certificates and the SSL-encrypted connection based on your preferred identity verification method. For instructions, see TLS/SSL for the C# driver.

Install the C# driver

  1. Create a new C# project:

    mkdir csharpproject
cd csharpproject
dotnet new console

  2. Add a dependency for the C# driver Latest CassandraCSharpDriver release on NuGet.

    If you install an earlier version of the driver, make sure your version is compatible with DSE and your application’s CQL statements. For example, if you need to query vector data, make sure your driver version supports the vector type.

    The C# driver is available as a NuGet package and can be installed in a project using the .NET CLI or Visual Studio Package Manager:

    Use the .NET CLI
    dotnet add package CassandraCSharpDriver

    To install a specific version, add -v VERSION to the command.

    Use the Package Manager Console
    Install-Package CassandraCSharpDriver
    Use PackageReference
    csproj
    <PackageReference Include="CassandraCSharpDriver" Version="VERSION" />

    Replace VERSION with your preferred version of the driver. DataStax recommends the latest version.

Connect the C# driver

  1. In your C# project, replace the code in Program.cs with the following code to connect to your DSE database:

    Program.cs
    using System;
using System.Linq;
using Cassandra;

namespace csharpproject
{
    class Program
    {
        static void Main(string[] args)
        {
            var session =
                Cluster.Builder()
                       .WithCredentials("username", "password")
                       .Build()
                       .Connect();
        }
    }
}

    Provide your cluster credentials in the WithCredentials method call.

  2. After the connection code, add code to the Main method in Program.cs that runs a CQL query and prints the output to the console.

    The following example queries the system.local table. You can replace the example SELECT statement with any CQL statement that you want to run against a keyspace and table in your database.

    Program.cs
    var rowSet = session.Execute("select * from system.local");
Console.WriteLine(rowSet.First().GetValue<string>("cluster_name"));

  3. Save Program.cs, and then run your C# project with the dotnet runtime:

    dotnet restore
dotnet build
dotnet run --no-build

    The console output includes the cluster_name value from the system.local table.

Next, you can extend or modify this script to run other commands against your database or connect to other databases. For more information, see the following:

Use DSE advanced workloads

If you have enabled DSE advanced workloads, you must configure your driver to connect to compatible nodes when sending DSE Search or Graph queries. For more information, see DSE advanced workloads in Cassandra drivers.

For information about the optional Graph extension, see the DataStax C# driver Graph extension documentation.

Reconnect the C# driver after a migration

If you migrate your data from one Cassandra database platform to another, you must update your client applications to connect to your new databases.

At minimum, you must update the driver connection strings. Additional changes might be required if you upgraded to a new major driver version or migrated to a database platform with a different feature set. For example, if you migrate to Astra, your drivers cannot create keyspaces because CQL for Astra doesn’t support CREATE KEYSPACE.

For information about updating driver connections after a migration, see the DataStax migration documentation on Connecting client applications to your new target database. Although the referenced documentation is in the context of zero downtime migration, the information applies to most Cassandra-to-Cassandra migrations where you need to update Cassandra driver connection strings.

Documentation and release notes

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM