PANiXiDA.Core.Ef.Migrator 1.0.2

PANiXiDA.Core.Ef.Migrator

PANiXiDA.Core.Ef.Migrator is a .NET library for automatically creating and applying Entity Framework Core migrations when an application starts.

It is designed for services that use PostgreSQL with EF Core and need a controlled startup-time migration flow for development, test, or managed deployment scenarios.

Status

Overview

The package extends IHostBuilder with a migration startup step. It builds the host, resolves the configured DbContext, detects pending model changes, optionally scaffolds a new EF Core migration into the target project, and optionally applies existing and generated migrations to PostgreSQL.

This package is intentionally small: the public entry point is RunMigrationsAsync<TContext>(), while generation and application behavior is controlled through configuration.

Features

• Detects differences between the current DbContext model and the latest model snapshot.
• Generates migration files into a configured project directory.
• Applies compiled pending migrations.
• Applies a newly generated migration in the same startup flow.
• Supports disabling generation and applying independently.
• Uses PostgreSQL through Npgsql.EntityFrameworkCore.PostgreSQL.

Quick Start

Requirements

• .NET 10 SDK
• Entity Framework Core 10
• PostgreSQL

Installation

<ItemGroup>
  <PackageReference Include="PANiXiDA.Core.Ef.Migrator" Version="1.0.1" />
</ItemGroup>

Minimal import

using PANiXiDA.Core.Ef.Migrator;

First example

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Hosting;
using PANiXiDA.Core.Ef.Migrator;

var builder = Host
    .CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddDbContext<AppDbContext>(options =>
        {
            options.UseNpgsql(
                context.Configuration["PostgreSqlConnectionString"],
                npgsql => npgsql.MigrationsAssembly(typeof(AppDbContext).Assembly.GetName().Name));
        });
    });

using var host = await builder.RunMigrationsAsync<AppDbContext>();
await host.RunAsync();

Usage

Configuration

The migration flow is controlled by these configuration values:

Example appsettings.json:

{
  "GenerateMigrations": true,
  "ApplyMigrations": true,
  "Ef": {
    "ProjectPath": ".",
    "MigrationsDirectory": "Data/Migrations"
  },
  "PostgreSqlConnectionString": "Host=localhost;Database=app;Username=app;Password=app"
}

Generate but do not apply

{
  "GenerateMigrations": true,
  "ApplyMigrations": false,
  "Ef": {
    "ProjectPath": ".",
    "MigrationsDirectory": "Data/Migrations"
  }
}

Apply existing migrations only

{
  "GenerateMigrations": false,
  "ApplyMigrations": true
}

Disable startup migrations

{
  "GenerateMigrations": false,
  "ApplyMigrations": false
}

Behavior Notes

• RunMigrationsAsync<TContext>() returns the built IHost.
• When generation is disabled and applying is enabled, only compiled pending migrations are applied.
• When generation is enabled but there are no model differences, the package applies compiled migrations with EF Core MigrateAsync() if applying is enabled.
• When generation and applying are both disabled, the host is built and returned without migration work.
• Ef:MigrationsDirectory must point to a directory inside Ef:ProjectPath.

Project Structure

.
|-- src/
|   `-- PANiXiDA.Core.Ef.Migrator/
|-- tests/
|   `-- PANiXiDA.Core.Ef.Migrator.IntegrationTests/
|-- .github/
|   `-- workflows/
|       `-- ci.yml
|-- Directory.Build.props
|-- Directory.Build.targets
|-- Directory.Packages.props
|-- global.json
|-- version.json
|-- LICENSE
`-- README.md

Development

Build

dotnet restore
dotnet build --configuration Release

Format

dotnet format

Test

dotnet test --configuration Release

Integration tests use Testcontainers and require a working Docker environment.

Pack

dotnet pack --configuration Release

Full local validation

dotnet restore
dotnet format
dotnet build --configuration Release
dotnet test --configuration Release
dotnet pack --configuration Release

Tooling and Conventions

This repository uses:

• .NET 10
• Nullable enabled
• Implicit usings enabled
• Central package management
• Microsoft Testing Platform
• xUnit v3
• FluentAssertions
• Testcontainers for PostgreSQL integration tests
• Nerdbank.GitVersioning
• GitHub Actions

License

This project is licensed under the Apache-2.0 license.

See the LICENSE file for details.

Maintainers

Maintained by PANiXiDA.

For questions or improvements, use GitHub Issues or Pull Requests.