Table of Contents

Interface IMigrator

Namespace
Excalibur.EventSourcing
Assembly
Excalibur.EventSourcing.Abstractions.dll

Defines the contract for database schema migration operations.

public interface IMigrator

Remarks

This interface provides the core operations for managing database schema migrations:

  • Applying pending migrations to bring the database up to date
  • Querying applied migrations for version tracking
  • Rolling back to a specific version when needed

Implementations are expected to:

  • Use advisory locks or similar mechanisms to prevent concurrent migrations
  • Maintain a migration history table for tracking applied migrations
  • Execute migrations within transactions where supported

Methods

GetAppliedMigrationsAsync(CancellationToken)

Gets all migrations that have been applied to the database.

Task<IReadOnlyList<AppliedMigration>> GetAppliedMigrationsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<AppliedMigration>>

A list of applied migrations in the order they were applied.

GetPendingMigrationsAsync(CancellationToken)

Gets all pending migrations that have not yet been applied.

Task<IReadOnlyList<string>> GetPendingMigrationsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<string>>

A list of pending migration IDs in the order they should be applied.

MigrateAsync(CancellationToken)

Applies all pending migrations to bring the database schema up to date.

Task<MigrationResult> MigrateAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

Task<MigrationResult>

The result of the migration operation including applied migrations.

Remarks

This method is idempotent - calling it when no migrations are pending will succeed with an empty list of applied migrations.

RollbackAsync(string, CancellationToken)

Rolls back migrations to the specified target version.

Task<MigrationResult> RollbackAsync(string targetMigrationId, CancellationToken cancellationToken)

Parameters

targetMigrationId string

The migration ID to roll back to (this migration will remain applied).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<MigrationResult>

The result of the rollback operation.

Remarks

The target migration ID specifies the migration to roll back TO, not the migration to remove. All migrations applied after the target migration will be removed.

If the target migration ID is not found in the applied migrations, the operation will fail.