migration-walkthrough.md

Migration Walkthrough

Video

See the accompanying Youtube video here

In this walkthrough, we will be migrating an existing simulated Akka.NET cluster from using Akka.Persistence.SqlServer persistence plugin to Akka.Persistence.Sql.

For this demo, we will be using one of the code samples provided in the Petabridge Akka.NET code sample repository, specifically the sharding-sqlserver sample code.

All of the changes are explained inside the Migration Guide

• Requirements
• Setup
  • 1. Clone The Sample Code Repository
  • 2. Start The Microsoft Sql Server Docker Container
  • 3. Seed The Database
  • 4. Duplicate The SqlSharding.Host Project
• Migrating To Akka.Persistence.Sql Full Compatibility Mode
  • Modify The New SqlSharding.Host.Migration Project
    • SqlSharding.Sql.Migration.csproj
    • Program.cs
      • Header Changes
      • Replace Cluster Sharding Persistence Configuration
      • Replace Persistence Configuration
    • ProductIndexActor.cs
    • SoldProductIndexActor.cs
    • WarningEventIndexActor.cs
  • Run The Application
• Enable WriterUuid Feature
  • Modify The Database Schema
  • Modify Program.cs
  • Run The Application
• Upgrade To Tag Table
  • Migrate Database To Support Tag Table
  • Modify Program.cs
  • Delete The SqlSharding.Host And SqlSharding.Sql.Host Project
  • Confirm Tag Table Is Working (Optional)
  • Run The Application
• Done!

Requirements

This walkthrough will require some tools to be installed on your computer.

• Microsoft .NET SDK
• Git
• Docker
• go-sqlcmd
• Powershell

Back to Top

Setup

1. Clone The Sample Code Repository

PS C:\> mkdir AkkaTutorial
PS C:\> cd AkkaTutorial
PS C:\AkkaTutorial> git clone https://github.com/petabridge/akkadotnet-code-samples.git
PS C:\AkkaTutorial> cd .\akkadotnet-code-samples\src\clustering\sharding-sqlserver\
PS C:\AkkaTutorial\akkadotnet-code-samples\src\clustering\sharding-sqlserver>

From this point forward, all console commands will be executed from inside this directory path.

Back to Top

2. Start The Microsoft Sql Server Docker Container

This script will start the Microsoft SqlServer Docker container

.\start-dependencies.cmd

Back to Top

3. Seed The Database

• In two different console windows, run these two projects:

  dotnet run --project .\SqlSharding.WebApp\SqlSharding.WebApp.csproj

  dotnet run --project .\SqlSharding.Host\SqlSharding.Host.csproj -- seed-db

• Wait for the seeding process to complete (should take less than 10 seconds)

• Open https://localhost:5001 in a browser to make sure that everything is working

• Stop both application by pressing Ctrl-C on both console windows.

Back to Top

4. Duplicate The SqlSharding.Host Project

We will be migrating the SqlSharding.Host project to use Akka.Persistence.Sql persistence plugin. Copy the project and register it with the solution file:

Copy-Item -Path .\SqlSharding.Host -Destination .\SqlSharding.Host.Migration -Recurse
Rename-Item -Path .\SqlSharding.Host.Migration\SqlSharding.Host.csproj -NewName SqlSharding.Host.Migration.csproj
dotnet sln add .\SqlSharding.Host.Migration\SqlSharding.Host.Migration.csproj

We will be working with the SqlSharding.Host.Migration project from now on.

Back to Top

Migrating To Akka.Persistence.Sql Full Compatibility Mode

Modify The New SqlSharding.Host.Migration Project

At the end of this step, the content of the SqlSharding.Host.Migration project should be identical to the SqlSharding.Sql.Host project

Back to Top

SqlSharding.Sql.Migration.csproj

• Remove the package reference to Akka.Persistence.SqlServer.Hosting
• Add package references to Akka.Persistence.Sql.Hosting and Microsoft.Data.SqlClient

The package reference section should look like this after the modification:

<ItemGroup>
  <PackageReference Include="Akka.Persistence.Sql.Hosting" Version="1.5.12-beta1" />
  <PackageReference Include="Microsoft.Data.SqlClient" Version="5.1.1" />
  <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="$(MicrosoftExtensionsVersion)" />
  <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="$(MicrosoftExtensionsVersion)" />
  <PackageReference Include="Petabridge.Cmd.Cluster" Version="$(PbmVersion)" />
  <PackageReference Include="Petabridge.Cmd.Cluster.Sharding" Version="$(PbmVersion)" />
  <PackageReference Include="Petabridge.Cmd.Host" Version="$(PbmVersion)" />
</ItemGroup>

Back to Top

Program.cs

Header Changes

Replace

using Akka.Persistence.SqlServer.Hosting;

with

using Akka.Persistence.Sql.Config;
using Akka.Persistence.Sql.Hosting;
using LinqToDB;
using SqlJournalOptions = Akka.Persistence.Sql.Hosting.SqlJournalOptions;
using SqlSnapshotOptions = Akka.Persistence.Sql.Hosting.SqlSnapshotOptions;

Replace Cluster Sharding Persistence Configuration

• Replace

  var shardingJournalOptions = new SqlServerJournalOptions(
      isDefaultPlugin: false, 
      identifier: "sharding")
  {
      ConnectionString = connectionString,
      TableName = "ShardingEventJournal", 
      MetadataTableName = "ShardingMetadata",
      AutoInitialize = true
  };

  with

  var shardingJournalDbOptions = JournalDatabaseOptions.SqlServer;
  shardingJournalDbOptions.JournalTable!.TableName = "ShardingEventJournal";
  shardingJournalDbOptions.MetadataTable!.TableName = "ShardingMetadata";
  
  var shardingJournalOptions = new SqlJournalOptions(
      isDefaultPlugin: false, 
      identifier: "sharding")
  {
      ConnectionString = connectionString,
      ProviderName = ProviderName.SqlServer2019,
      DatabaseOptions = shardingJournalDbOptions,
      TagStorageMode = TagMode.Csv,
      DeleteCompatibilityMode = true,
      AutoInitialize = false
  };

• Replace

  var shardingSnapshotOptions = new SqlServerSnapshotOptions(
      isDefaultPlugin: false, 
      identifier: "sharding")
  {
      ConnectionString = connectionString,
      TableName = "ShardingSnapshotStore",
      AutoInitialize = true
  };

  with

  var shardingSnapshotDbOptions = SnapshotDatabaseOptions.SqlServer;
  shardingSnapshotDbOptions.SnapshotTable!.TableName = "ShardingSnapshotStore";
  
  var shardingSnapshotOptions = new SqlSnapshotOptions(
      isDefaultPlugin: false, 
      identifier: "sharding")
  {
      ConnectionString = connectionString,
      ProviderName = ProviderName.SqlServer2019,
      DatabaseOptions = shardingSnapshotDbOptions, 
      AutoInitialize = false
  };

Back to Top

Replace Persistence Configuration

Replace

.WithSqlServerPersistence(
    connectionString: connectionString,
    journalBuilder: builder =>
    {
        builder.AddWriteEventAdapter<MessageTagger>("product-tagger", new[] { typeof(IProductEvent) });
    })

with

.WithSqlPersistence(
    connectionString: connectionString,
    providerName: ProviderName.SqlServer2019,
    databaseMapping: DatabaseMapping.SqlServer,
    tagStorageMode: TagMode.Csv,
    deleteCompatibilityMode: true,
    useWriterUuidColumn: false,
    autoInitialize: false,
    journalBuilder: builder =>
    {
        builder.AddWriteEventAdapter<MessageTagger>("product-tagger", new[] { typeof(IProductEvent) });
    })

Back to Top

ProductIndexActor.cs

Replace using Akka.Persistence.Query.Sql; with using Akka.Persistence.Sql.Query;

Back to Top

SoldProductIndexActor.cs

Replace using Akka.Persistence.Query.Sql; with using Akka.Persistence.Sql.Query;

Back to Top

WarningEventIndexActor.cs

Replace using Akka.Persistence.Query.Sql; with using Akka.Persistence.Sql.Query;

Back to Top

Run The Application

At this point, the migration project is in Akka.Persistence.Sql full compatibility mode. All 3 version of the Host project can co-exist in the same Akka.NET cluster.

• In three different console windows, run all of the projects:

  dotnet run --project .\SqlSharding.WebApp\SqlSharding.WebApp.csproj

  dotnet run --project .\SqlSharding.Host\SqlSharding.Host.csproj

  dotnet run --project .\SqlSharding.Host.Migration\SqlSharding.Host.Migration.csproj

• Open https://localhost:5001 in a browser to make sure that everything is working

• Stop all application by pressing Ctrl-C on all console windows.

Back to Top

Enable WriterUuid Feature

To go straight to this step, you can directly check out the git branch:

git checkout Migration_01

Back to Top

Modify The Database Schema

In a Powershell console, execute:

sqlcmd -S "localhost,1533" -d Akka -U sa -P "yourStrong(!)Password" -Q "ALTER TABLE [dbo].[EventJournal] ADD writer_uuid VARCHAR(128)"

Back to Top

Modify Program.cs

Inside Program.cs, change the useWriterUuidColumn argument parameter of the .WithSqlPersistence() to true.

.WithSqlPersistence(
    connectionString: connectionString,
    providerName: ProviderName.SqlServer2019,
    databaseMapping: DatabaseMapping.SqlServer,
    tagStorageMode: TagMode.Csv,
    deleteCompatibilityMode: true,
    useWriterUuidColumn: true, // Change this parameter value to true
    autoInitialize: false,
    journalBuilder: builder =>
    {
        builder.AddWriteEventAdapter<MessageTagger>("product-tagger", new[] { typeof(IProductEvent) });
    })

Back to Top

Run The Application

• In two different console windows, run the projects:

  dotnet run --project .\SqlSharding.WebApp\SqlSharding.WebApp.csproj

  dotnet run --project .\SqlSharding.Host.Migration\SqlSharding.Host.Migration.csproj

• Open https://localhost:5001 in a browser to make sure that everything is working

• Stop all application by pressing Ctrl-C on all console windows.

Back to Top

Upgrade To Tag Table

To go straight to this step, you can directly check out the git branch:

git checkout Migration_02

Back to Top

Migrate Database To Support Tag Table

1. Download these SQL script files:
   • 1_Migration_Setup.sql
   • 2_Migration.sql
   • 3_Post_Migration_Cleanup.sql
2. Copy these SQL script into a folder called Scripts
3. Execute the scripts in order:

   sqlcmd -S "localhost,1533" -d Akka -U sa -P "yourStrong(!)Password" -i .\Scripts\1_Migration_Setup.sql
   
   sqlcmd -S "localhost,1533" -d Akka -U sa -P "yourStrong(!)Password" -i .\Scripts\2_Migration.sql
   
   sqlcmd -S "localhost,1533" -d Akka -U sa -P "yourStrong(!)Password" -i .\Scripts\3_Post_Migration_Cleanup.sql

Back to Top

Modify Program.cs

Inside Program.cs, change the tagStorageMode argument parameter of the .WithSqlPersistence() to TagMode.TagTable.

Back to Top

Delete The SqlSharding.Host And SqlSharding.Sql.Host Project

The SqlSharding.Host and SqlSharding.Sql.Host project is not compatible with SqlSharding.Host.Migration anymore, you can delete these projects.

dotnet sln remove .\SqlSharding.Host\SqlSharding.Host.csproj
dotnet sln remove .\SqlSharding.Sql.Host\SqlSharding.Sql.Host.csproj
Remove-Item -Recurse -Force .\SqlSharding.Host\
Remove-Item -Recurse -Force .\SqlSharding.Sql.Host\

Back to Top

Confirm Tag Table Is Working (Optional)

To confirm that the tag table is working, lets delete the old tag data:

sqlcmd -S "localhost,1533" -d Akka -U sa -P "yourStrong(!)Password" -Q "UPDATE [dbo].[EventJournal] SET Tags = NULL"

Back to Top

Run The Application

• In two different console windows, run the projects:

  dotnet run --project .\SqlSharding.WebApp\SqlSharding.WebApp.csproj

  dotnet run --project .\SqlSharding.Host.Migration\SqlSharding.Host.Migration.csproj

• Open https://localhost:5001 in a browser to make sure that everything is working

• Stop all application by pressing Ctrl-C on all console windows.

Back to Top

Done!

To go straight to this step, you can directly check out the git branch:

git checkout Migration_03