Cassandra Fluent Migrator

Cassandra Fluent Migrator

Interface: ICassandraFluentMigrator

Handler : CassandraFluentMigrator

This class contains the methods that will be needed by the user to create his migrations.

This helper will be divided to two sections (Class and extensions)

Note: it's recommended to use strings instead of nameof(...) when using the migration methods this will allow to keep a certain consistency in your migrations if you ever decide to go to an older version of your app.

Class

This class should be called in the constructor of the user migrations. It defines the following methods:

/// <summary>
/// Gets the registred Cassandra session context.
/// </summary>
///
/// <returns>Current instance of the Cassadnra session.</returns>
ISession GetCassandraSession();

/// <summary>
/// Gets the Cassandra table based on the {TEntity}.
/// </summary>
///
/// <typeparam name="TEntity">The Class that represent a table in Cassandra.</typeparam>
/// <returns>Instance of the Cassandra table.</returns>
Table<TEntity> GetTable<TEntity>()
    where TEntity : class;

/// <summary>
/// Validate that the table exists in the Cassandra session context.
/// </summary>
///
/// <param name="table">The table we need to search for.</param>
/// <returns>True, if exists. False otherwise.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
bool DoesTableExists([NotNull]string table);

/// <summary>
/// Validate that the column exists in the specified table.
///
/// <para>Before validating that the columns exists, the method first validate that the table exists.</para>
/// </summary>
///
/// <param name="table">The table we want to search.</param>
/// <param name="column">The column that we want to search for.</param>
/// <returns>True, if exists. False, Otherwise.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the table isn't available in the current casasndra session.</exception>
bool DoesColumnExists([NotNull]string table, [NotNull]string column);

/// <summary>
/// Validate that the User-Defined type exists in the Cassandra session context.
/// </summary>
///
/// <param name="udt">The User-Defined type that we need to search for.</param>
/// <returns>True, if exists. False otherwise.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
bool DoesUdtExists([NotNull]string udt);

/// <summary>
/// Validate that the column exists in the specified User-Defined type.
///
/// <para>Before validating that the columns exists, the method first validate that the User-Defined type exists.</para>
/// </summary>
///
/// <param name="udt">The User-Defined type we want to search.</param>
/// <param name="column">The column that we want to search for.</param>
/// <returns>True, if exists. False otherwise.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the User-Defined type isn't available in the current casasndra session.</exception>
bool DoesUdtColumnExists([NotNull]string udt, [NotNull]string column);

/// <summary>
/// Validate that the Materialized view exists in the Cassandra session context.
/// </summary>
///
/// <param name="view">The Materialized view that we need to search for.</param>
/// <returns>True, if exists. False otherwise.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
bool DoesMaterializedViewExists([NotNull]string view);

/// <summary>
/// Validate that the column exists in the specified Materialized view.
///
/// <para>Before validating that the columns exists, the method first validate that the Materialized view exists.</para>
/// </summary>
///
/// <param name="view">The Materialized view. we want to search.</param>
/// <param name="column">The column that we want to search for.</param>
/// <returns>True, if exists. False otherwise.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the Materialized view isn't available in the current casasndra session.</exception>
bool DoesMaterializedViewColumnExists([NotNull]string view, [NotNull] string column);

/// <summary>
/// Get the Cassandra CQL type equivalent to the specified CSharp type.
/// </summary>
///
/// <param name="type">The CSharp type to be converted.</param>
/// <param name="shouldBeFrozen">Define if the type should be treated as a frozen type or not.</param>
/// <returns>Return string value containing the Cassandra CQL type.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
string GetCqlType([NotNull]Type type, bool shouldBeFrozen = false);

/// <summary>
/// Get the Cassandra CQL type of the specified column.
/// </summary>
///
/// <typeparam name="TEntity">The class where we need to search for the column type.</typeparam>
/// <param name="column">The column that we want to search for.</param>
/// <param name="shouldBeFrozen">Define if the type should be treated as a frozen type or not.</param>
/// <returns>Return string value of the Cassandra CQL type.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
string GetColumnType<TEntity>([NotNull]string column, bool shouldBeFrozen = false)
    where TEntity : class;

Extensions

This section contains the definition of the extensions that can be used alongside the ICassandraFluentMigrator class, it's separated into two sections

Tables

This Extension class is used to group all the Cassandra tables columns Actions for the Cassandra Fluent Migrator.

/// <summary>
/// Adds the specified column to the targeted table only if the column doesn't exist.
/// </summary>
///
/// <param name="self">The instance of the Cassandra Fluent Migrator helper.</param>
/// <param name="table">The table to which we want to add the new column.</param>
/// <param name="column">The new column.</param>
/// <param name="type">The column type.</param>
/// <param name="shouldBeFrozen">Define if the type should be treated as a frozen type or not.</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the table doesn't exists.</exception>
Task<ICassandraFluentMigrator> AddColumnAsync([NotNull]this ICassandraFluentMigrator self, [NotNull] string table, [NotNull] string column, [NotNull]Type type, bool shouldBeFrozen = false);

/// <summary>
/// Adds the specified column to the targeted table only if the column doesn't exist.
///
/// <para>Note: The method automatically resolve the type of the column.</para>
/// </summary>
///
/// <typeparam name="Table">The Table where we should search for the column type.</typeparam>
/// <param name="self">The instance of the Cassandra Fluent Migrator helper.</param>
/// <param name="table">The table to which we want to add the new column.</param>
/// <param name="column">The new column.</param>
/// <param name="shouldBeFrozen">Define if the type should be treated as a frozen type or not.</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the table doesn't exists.</exception>
Task<ICassandraFluentMigrator> AddColumnAsync<Table>([NotNull]this ICassandraFluentMigrator self, [NotNull] string table, [NotNull] string column, bool shouldBeFrozen = false);

/// <summary>
/// Rename the specified column in the targeted table only if the column exists.
/// <para>IMPORTANT: In Cassandra only the Primary key can be renamed.</para>
/// </summary>
///
/// <param name="self">The instance of the Cassandra Fluent Migrator helper.</param>
/// <param name="table">The table where we want to rename the column.</param>
/// <param name="old">The column to be renamed.</param>
/// <param name="target">The new column name.</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the table doesn't exists.</exception>
/// <exception cref="InvalidOperationException">Thrown when the Column is not a primary key or the target column name already exists.</exception>
Task<ICassandraFluentMigrator> RenamePrimaryColumnAsync([NotNull]this ICassandraFluentMigrator self, [NotNull]string table, [NotNull]string old, [NotNull]string target);

/// <summary>
/// Drops the specified column from the targeted table only if the column exists.
/// </summary>
///
/// <param name="self">The instance of the Cassandra Fluent Migrator helper.</param>
/// <param name="table">The table from which we want to delete the column.</param>
/// <param name="column">The column to be deleted.</param>
/// <returns>The table Instance.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the table doesn't exists.</exception>
Task<ICassandraFluentMigrator> DropColumnAsync(this ICassandraFluentMigrator self, [NotNull]string table, [NotNull]string column);

// IMPORTANT: Alter Column type is no longer supported in Cassandra v3.x
Task<ICassandraFluentMigrator> AlterColumnAsync("table", "field", ["Type"]);

User Defined types

This Extension class is used to group all the Cassandra User-Defined types Actions for the Cassandra Fluent Migrator.

/// <summary>
/// Create the new User-Defined type by building and generating a query
/// based on the generic class fields and types.
/// If the UDT already exists, the method skips the creation.
///
/// <para>Note: If the User-Defined type name is [Null || Empty] the method will take the generic type {TEntity} name.</para>
/// </summary>
///
/// <typeparam name="TEntity">The calss where the method should look for the properties and their types.</typeparam>
/// <param name="self">The Cassandra Fluent Migrator.</param>
/// <param name="name">The name of the User-Defined type (Optional).</param>
/// <param name="shouldBeFrozen">Define if the type should be treated as a frozen type or not.</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
Task<ICassandraFluentMigrator> CreateUserDefinedTypeAsync<TEntity>([NotNull]this ICassandraFluentMigrator self, string name = default, bool shouldBeFrozen = false);

/// <summary>
/// Delete the User-Defined type if exists.
/// If the UDT doesn't exists, the method skips the deletion.
///
/// <para>Note: If the User-Defined type name is [Null || Empty] the method will take the generic type {TEntity} name.</para>
/// </summary>
///
/// <typeparam name="TEntity">The calss where the method should look for the properties and their types.</typeparam>
/// <param name="self">The Cassandra Fluent Migrator.</param>
/// <param name="name">The name of the udt (Optional).</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
Task<ICassandraFluentMigrator> DeleteUserDefinedTypeAsync<TEntity>([NotNull]this ICassandraFluentMigrator self, [NotNull]string name = default);


// ***************** [Add/Alter/Rename/Delete] Columns from a User-Defined Type ***************** //

/// <summary>
/// Alter the specified User-Defined type by adding a new column only if it doesn't exist.
/// If the UDT doesn't exists, the method throws an exception.
/// If the column exists, the method skips the action.
/// </summary>
///
/// <param name="self">The Cassandra Fluent Migrator.</param>
/// <param name="udt">The name of the User-Defined type.</param>
/// <param name="column">The name of the column to be added.</param>
/// <param name="type">The type of the new column.</param>
/// <param name="shouldBeFrozen">Define if the type should be treated as a frozen type or not.</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the User-Defined type doesn't exists.</exception>
Task<ICassandraFluentMigrator> AlterUdtAddColumnAsync([NotNull]this ICassandraFluentMigrator self, [NotNull]string udt, string column, Type type, bool shouldBeFrozen = false);

/// <summary>
/// Alter the specified User-Defined type by adding a new column only if it doesn't exist.
/// If the UDT doesn't exists, the method throws an exception.
/// If the column exists, the method skips the action.
/// </summary>
///
/// <typeparam name="TEntity">The calss where the method should search for the properties and their types.</typeparam>
/// <param name="self">The Cassandra Fluent Migrator.</param>
/// <param name="udt">The name of the User-Defined type.</param>
/// <param name="column">The name of the column to be added.</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the User-Defined type doesn't exists.</exception>
Task<ICassandraFluentMigrator> AlterUdtAddColumnAsync<TEntity>([NotNull]this ICassandraFluentMigrator self, [NotNull]string udt, string column);

/// <summary>
/// Alter the specified User-Defined type by renaming the column name by the target name.
/// If the UDT doesn't exists, the method throws an exception.
/// If the new column exists, the method throws an exception.
/// </summary>
///
/// <param name="self">The Cassandra Fluent Migrator.</param>
/// <param name="udt">The name of the User-Defined type.</param>
/// <param name="column">The name of the column to be renamed.</param>
/// <param name="target">The new column name.</param>
/// <returns>The Cassandra Fluent Migrator helper.</returns>
///
/// <exception cref="NullReferenceException">Thrown when one or all the specified arguments are invalid or null.</exception>
/// <exception cref="InvalidOperationException">Thrown when the target column name exists.</exception>
/// <exception cref="ObjectNotFoundException">Thrown when the User-Defined type doesn't exists.</exception>
Task<ICassandraFluentMigrator> AlterUdtRenameColumnAsync([NotNull]this ICassandraFluentMigrator self, [NotNull]string udt, [NotNull]string column, [NotNull]string target);

// IMPORTANT: Cassandra doesn't support Dropping a column of a `User-Defined type`.
AlterUdtDeleteColumnAsync("udt", "field");

// IMPORTANT: Alter Column is no longer supported in Cassandra v3.x
AlterUdtAlterColumnAsync("udt", "field", ["Type"]);