Flyway integration in the AppHost

⭐ Community Toolkit

This page covers the CommunityToolkit.Aspire.Hosting.Flyway AppHost APIs. For an overview and prerequisites, see Get started with the Flyway integration.

Installation

Install the package in the AppHost:

aspire add flyway

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> flyway (CommunityToolkit.Aspire.Hosting.Flyway)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.Flyway@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Flyway" Version="*" />

The package requires .NET 10 or later. Docker must be available to run the Flyway container.

Add a Flyway resource

Use AddFlyway to mount the migration scripts directory from the host into /flyway/sql in the container. migrationScriptsPath can be absolute or relative to the AppHost working directory, and Docker must be able to access it.

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const flyway: FlywayResource
flyway = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addFlyway(name: string, migrationScriptsPath: string): FlywayResource
addFlyway('flyway', './migrations');

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

using CommunityToolkit.Aspire.Hosting.Flyway;

var builder = DistributedApplication.CreateBuilder(args);

var flyway = builder.AddFlyway("flyway", "./migrations");

// After adding all resources, run the app...
builder.Build().Run();

The resource uses the flyway/flyway:13 container image, sets FLYWAY_LOCATIONS to filesystem:/flyway/sql, disables Redgate telemetry by default, and bind-mounts the scripts directory read-only.

Configure migration scripts

Place SQL migrations in the directory passed to AddFlyway, following Flyway’s naming and versioning rules. The integration does not copy files into the container; it mounts the host path. Keep the files present and readable for the lifetime of the container.

Configure the database provider

The generic Flyway package does not add a database connection to the resource. Add the database resource to the AppHost and use the database provider’s Flyway extension to configure Flyway for that engine. The PostgreSQL extension configures Flyway’s connection arguments but does not add a resource dependency. Add an explicit dependency with flywayMigration.WaitFor(postgresDb) in C# or flywayMigration.waitFor(postgresDb) in TypeScript so the database is ready before the migration runs.

Opt in to Flyway telemetry

Flyway telemetry is disabled by default through REDGATE_DISABLE_TELEMETRY=true. Call WithTelemetryOptIn only when you choose to send Flyway usage data to Redgate:

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const flyway: FlywayResource
flyway = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addFlyway(name: string, migrationScriptsPath: string): FlywayResource
addFlyway('flyway', './migrations');
await 
const flyway: FlywayResource
flyway.
FlywayResource.withTelemetryOptIn(): FlywayResource
withTelemetryOptIn();

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

using CommunityToolkit.Aspire.Hosting.Flyway;

var builder = DistributedApplication.CreateBuilder(args);

var flyway = builder.AddFlyway("flyway", "./migrations")
    .WithTelemetryOptIn();

// After adding all resources, run the app...
builder.Build().Run();

Health and lifecycle

Flyway is modeled as a container resource. This package does not add an application-level health check or a consuming-app client integration. Use the dashboard logs and state to inspect the Flyway process, and consult the provider-specific extension for its migration lifecycle behavior.

Exported AppHost API

AddFlyway(name, migrationScriptsPath) creates the Flyway container and mounts the script directory.
WithTelemetryOptIn() changes REDGATE_DISABLE_TELEMETRY to false.

These are the complete AppHost APIs exported by this package.