StreamStore.NoSql.Cassandra 0.2.0

StreamStore.NoSql.Cassandra

Apache Cassandra and Azure Cosmos DB for Apache Cassandra storage for StreamStore asynchronous event sourcing library built on top of CassandraCSharpDriver.

ACID compliance and considerations

Despite the fact that Apache Cassandra is not ACID compliant DBMS, library provides ACID guarantees for the operations that are performed within a single partition key - stream identifier.

Such guarantees are achieved by using following features:

• The LWT (Lightweight Transactions) feature of Cassandra.
• The conditional logged batches.
• The ALL consistency level for the read and write operations.
• The SERIAL serial consistency level for the read operations.

Taking into account that configuration above significantly affects the performance of the system, and that not all scenarios requires ACID compliance, it has been decided to add possibility to change consistency levels via configuration.

Installation

To install the package, you can use the following command from the command line:

  dotnet add package StreamStore

  dotnet add package StreamStore.NoSql.Cassandra

or from Nuget Package Manager Console:

  Install-Package StreamStore

  Install-Package StreamStore.NoSql.Cassandra

Usage

Storage

By default the library provisioning schema automatically, however you must create keyspace or configure library to use already existing one.
By default the library uses streamstore keyspace in single tenant mode.
For multitenancy mode you must create keyspace per tenant in advance.

If you want to create table manually, you can use the following script:

CREATE TABLE IF NOT EXISTS events
    (id text,
    stream_id text,
    revision int,
    timestamp timestamp,
    data blob,
    PRIMARY KEY(stream_id, revision)
    );

Getting started

Since the library CassandraCSharpDriver as well as Apache Cassandra itself provides a lot of configuration options, it is not possible to cover all of them in the library configuration.
In this regards, decision has been made to provide ability to configure connectivity options via original API of CassandraCSharpDriver.

However, in case if you decided to use library with Azure Cosmos DB for Apache Cassandra, there is extension simplifies configuration by only connection string required.

services.ConfigureStreamStore(x =>...
  
  // Register single tenant implementation
  x.WithSingleDatabase(c => ...
      c.UseCassandra(x => {
          x.UseCosmosDb(connectionString);            // Optional. Required  if you want to use Azure Cosmos DB for Apache Cassandra
          x.ConfigureCluster(c =>                     // Required. Configure cluster options. Optional if you decided to use CosmosDB (see above).
              c.AddContactPoint("localhost"));        // Configure contact points.
         }
      )
  )

  // Or enable multitenancy
  x.WithMultitenancy(c => ...
      c.UseTenantProvider<MyTenantProvider>()          // Optional. Register your  ITenantProvider implementation.
                                                       // Required if you want schema to be provisioned for each tenant.
      c.UseCassandra(x => {
          x.WithKeyspaceProvider<Provider>();           // Required. Register your  ITenantKeyspaceProvider implementation.
          x.UseCosmosDb(connectionString);              // Optional. Required  if you want to use Azure Cosmos DB for Apache Cassandra
          x.ConfigureDefaultCluster(c =>                // Required. Configure cluster options. Optional if you decided to use CosmosDB (see above).
                  c.AddContactPoint("localhost"));      // Configure contact points.
        }
      )
  )
); 

Full list of configuration options you can find in the Configuration options section.

Use in application code

How to use StreamStore in your application code you can find on StreamStore page.

Example

You can find an example of usage in the StreamStore.NoSql.Example project.
More information about how example application works you can find in StreamStore documentation.

Testing

In order to run tests placed in StreamStore.NoSql.Tests/Cassandra/Database, you need to have a running Cassandra cluster. You can use docker-compose docker-compose.yaml to run it.

Configuration options

Below you can find the list of configuration options that can be used to configure the library.

// Register single tenant implementation
  x.WithSingleDatabase(c => ...
      c.UseCassandra(x => 
         {
            x.UseCosmosDb(connectionString);                                    // Optional. Required  if you want to use Azure Cosmos DB for Apache Cassandra.
            x.UseCosmosDb(Configuration, connectionStringName);                 // You can also provide IConfiguration and connection string name to Cosmos DB, by default "StreamStore".
            x.ConfigureCluster(c =>                                             // Required. Configure cluster options. Optional if you decided to use CosmosDB (see above).
                    c.AddContactPoint("localhost"));                            // Configure contact points at least.
                                                                                // There is much more cluster options available.
            x.ConfigureStorage(c =>                                             // Optional. Configure storage options.
                    c.WithKeyspaceName("keyspacename")                          // Optional. Keyspace name. Default is streamstore.
                     .WithEventsTableName("tablename")                          // Optional. Table name. Default is events.
                     .WithReadConsistencyLevel(ConsistencyLevel.Quorum)         // Optional. Read consistency level. Default is All.
                     .WithWriteConsistencyLevel(ConsistencyLevel.Quorum)        // Optional. Write consistency level. Default is All.
                     .WithSerialConsistencyLevel(ConsistencyLevel.SerialLocal)  // Optional. Serial consistency level. Default is Serial.
            );
            x.WithSessionFactory<TFactory>();                                   // Optional. Register your ISessionFactory implementation.
          }    
      )
  )

  // Or enable multitenancy
  x.WithMultitenancy(c => ...
                                                                                // More information about multitenancy configuration you can find in the StreamStore.
     c.UseCassandra(x => 
         {
            x.WithKeyspaceProvider<Provider>();                                 // Required. Register your ITenantKeyspaceProvider implementation.
            x.UseCosmosDb(connectionString);                                    // Optional. Required if you want to use Azure Cosmos DB for Apache Cassandra.
            x.UseCosmosDb(Configuration, connectionStringName);                 // You can also provide IConfiguration and connection string name to Cosmos DB, by default "StreamStore".
            x.ConfigureDefaultCluster(c =>                                      // Required. Configure default cluster options. Optional if you decided to use CosmosDB (see above).
                    c.AddContactPoint("localhost"));                            // Configure contact points at least.
                                                                                // There is much more cluster options available.
            x.ConfigureStoragePrototype(c =>                                    // Optional. Configure storage options as prototype for tenant storage configuration.
                    c.WithEventsTableName("tablename")                          // Optional. Table name. Default is events.
                     .WithReadConsistencyLevel(ConsistencyLevel.Quorum)         // Optional. Read consistency level. Default is All.
                     .WithWriteConsistencyLevel(ConsistencyLevel.Quorum)        // Optional. Write consistency level. Default is All.
                     .WithSerialConsistencyLevel(ConsistencyLevel.SerialLocal)  // Optional. Serial consistency level. Default is Serial.
            );
            x.WithTenantClusterConfigurator(c => ...);                          // Optional. Register delegate for configuring tenant cluster configuration based on default cluster.
            x.WithStorageConfigurationProvider<TProvider>();                    // Optional. Register your ITenantStorageConfigurationProvider implementation.
          }
      )
  )

License

MIT License