Shardis.Migration 0.2.2

Shardis.Migration

Key migration execution primitives for Shardis. This package contains the executor, planner abstractions, checkpoint store contracts, and reference in-memory implementations used for tests and prototypes.

Install

dotnet add package Shardis.Migration --version 0.2.*

When to use

• Deterministic, idempotent key migration (copy → verify → swap) between shard topologies.
• Need pluggable verification (checksum, rowversion via provider) & projection abstractions.
• Require checkpointing & resume support during long-running migrations.

What’s included

• Planner models: MigrationPlan<TKey>, KeyMove<TKey>, MigrationCheckpoint<TKey>.
• ShardMigrationExecutor<TKey> — orchestrates copy → verify → swap with checkpoint persistence & metrics hooks.
• Abstractions: IShardDataMover<TKey>, IVerificationStrategy<TKey>, IShardMigrationCheckpointStore<TKey>, IShardMapSwapper<TKey>, IShardMigrationMetrics.
• Duration instrumentation: executor records per-key copy / verify latency, per-swap-batch latency, and total elapsed (extend IShardMigrationMetrics for export).
• Reference in-memory checkpoint store & test doubles (see tests) for prototyping.
• Default stable canonicalization + hashing abstractions (IStableCanonicalizer, IStableHasher) consumed by checksum strategies. See docs/canonicalization.md.

Quick start

// register migration runtime + (optionally) provider-specific support (e.g. EF / Marten)
services.AddShardisMigration<string>(); // core abstractions & executor

var planner = services.GetRequiredService<IShardMigrationPlanner<string>>(); // if planner registered
var executor = services.GetRequiredService<ShardMigrationExecutor<string>>();

var plan = await planner.CreatePlanAsync(fromSnapshot, toSnapshot, CancellationToken.None);
var result = await executor.ExecuteAsync(plan, progress: null, CancellationToken.None);

Integration notes

• For long migrations use a durable checkpoint store implementation (custom). An experimental SQL-backed implementation lives in Shardis.Migration.Sql (preview; API stability not yet guaranteed).
• Verification strategy can be swapped (rowversion, checksum) by provider DI extensions before execution.
• Projection strategy (IEntityProjectionStrategy) allows shape normalization (exclude volatile fields) — ensure determinism.

Samples & tests

• Docs: https://github.com/veggerby/shardis/blob/main/docs/migration-usage.md
• Canonicalization: https://github.com/veggerby/shardis/blob/main/docs/canonicalization.md
• Sample end-to-end scenarios (retry, cancellation, resume, large plan): samples/Shardis.Migration.Sample.
• ADR: https://github.com/veggerby/shardis/blob/main/docs/adr/0004-segmented-planner.md
• Tests: https://github.com/veggerby/shardis/tree/main/test/Shardis.Migration.Tests

Contributing

• PRs that add durable checkpoint store implementations or improve executor observability are welcome. See https://github.com/veggerby/shardis/blob/main/CONTRIBUTING.md

License

• MIT — see https://github.com/veggerby/shardis/blob/main/LICENSE