ef-migration-diff

Compare Entity Framework migrations between branches - detect conflicts, preview schema changes

Overview

ef-migration-diff is a powerful tool for analyzing Entity Framework Core migrations across different Git branches. It automatically detects migration conflicts, previews schema changes, and generates comprehensive reports. Whether you're working in a team environment with multiple database developers or managing complex schema evolution, this tool provides critical insights before merging.

Why You Need This

When multiple developers work on the same codebase, parallel database migrations can create conflicts that are difficult to detect without proper tooling:

Silent Conflicts: Multiple developers creating migrations for the same table can result in naming conflicts or missed dependency updates
Schema Drift: Without visibility into schema changes, you might unknowingly introduce breaking changes
Integration Difficulties: Merging migration branches without proper analysis can cause application downtime
Documentation Gaps: Complex schema migrations need clear documentation of changes

ef-migration-diff solves these problems by providing:

Automatic conflict detection between migration branches
Visual schema change previews
Detailed impact analysis
Multiple output formats for different stakeholders

Key Features

Migration Comparison

Compare migrations between two Git branches
Detect conflicting migration names and dependencies
Identify orphaned migration references
Analyze migration file content differences

Schema Change Detection

Extract and compare schema change operations
Preview before/after schema state
Categorize changes by type (CREATE, ALTER, DROP)
Detect breaking changes and data loss scenarios

Multiple Output Formats

JSON: Machine-readable format for automation
CSV: Spreadsheet-friendly format for analysis
HTML: Interactive reports for stakeholders
Console: Quick summary output for CLI usage

Integration Features

Git repository integration for automatic branch checkout
DbContext discovery and metadata extraction
Custom migration folder support
Plugin system for extensibility

Performance

Caching layer for repeated comparisons
Background task queue for long-running operations
Streaming report generation for large datasets
Optimized reflection-based DbContext scanning

Robust Processing

Comprehensive error handling and recovery
Validation middleware for input safety
Request logging for debugging
Health check endpoints

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ef-migration-diff                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │  CLI Layer   │  │  API Layer   │  │   Plugins    │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │
│         │                 │                  │             │
│  ┌──────▼─────────────────▼──────────────────▼──────┐    │
│  │           Command Execution Engine              │    │
│  │  (CommandParser, CommandExecutor, Context)      │    │
│  └──────────────────────┬─────────────────────────┘    │
│                         │                              │
│  ┌──────────────────────▼──────────────────────────┐   │
│  │    Core Analysis Services                      │   │
│  │  • MigrationDiffService                        │   │
│  │  • SchemaChangeDetectorService                 │   │
│  │  • ConflictDetectionService                    │   │
│  │  • MigrationParserService                      │   │
│  └──────────────────────┬─────────────────────────┘   │
│                         │                              │
│  ┌──────────────────────▼──────────────────────────┐   │
│  │    Data Access Layer                           │   │
│  │  • GitRepository                               │   │
│  │  • MigrationRepository                         │   │
│  │  • DbContextRepository                         │   │
│  └──────────┬───────────────┬───────────────┬─────┘   │
│             │               │               │          │
│  ┌──────────▼───┐  ┌────────▼────┐  ┌──────▼────┐   │
│  │  Git Files   │  │ Migrations  │  │ DbContext │   │
│  │              │  │ Folder      │  │ Classes   │   │
│  └──────────────┘  └─────────────┘  └───────────┘   │
│                                                       │
└─────────────────────────────────────────────────────────┘

Layer Descriptions

Presentation Layer: Handles CLI commands and user input Business Logic Layer: Core analysis and comparison engine Data Access Layer: Interacts with Git and file system Models: Data structures representing migrations and schemas

Installation

Prerequisites

.NET 10 SDK or later (Download)
Git (for repository operations)
SQL Server, PostgreSQL, MySQL, or SQLite (depending on your DbContext)

Method 1: Clone and Build

git clone https://github.com/Sarmkadan/ef-migration-diff.git
cd ef-migration-diff
dotnet restore
dotnet build -c Release
dotnet publish -c Release -o ./publish

Method 2: Docker

docker build -t ef-migration-diff:latest .
docker run --rm -v /path/to/project:/workspace ef-migration-diff:latest \
  compare --branch1 main --branch2 feature/users

Method 3: Local Installation

dotnet tool install --global --add-source ./publish ef-migration-diff

Verify Installation

ef-migration-diff --version
# Output: ef-migration-diff version 1.0.0

Quick Start

1. Basic Comparison

Compare migrations between two branches:

ef-migration-diff compare --branch1 main --branch2 feature/add-users

2. Generate HTML Report

ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/add-users \
  --output html \
  --output-path ./report.html

Open report.html in your browser to view the interactive report.

3. Check for Conflicts

ef-migration-diff validate --branch feature/users

4. Export as JSON

ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/data-migration \
  --output json \
  --output-path ./diff.json

Usage Examples

Example 1: Detecting Migration Name Conflicts

Scenario: Two developers created migrations simultaneously.

ef-migration-diff compare \
  --branch1 develop \
  --branch2 feature/new-fields \
  --strict-mode

Output:

Migration Conflicts Found:
- 20250504120000_AddUserRoles.cs (exists in both branches)
- 20250504121500_AddPermissions.cs (exists in both branches)

Recommendation: Rename migrations to avoid conflicts

Example 2: Schema Change Preview

Scenario: Review all schema changes before merging a feature branch.

ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/refactor-tables \
  --include-schema-preview \
  --output html \
  --output-path ./schema-changes.html

What you'll see:

Table creation/deletion operations
Column additions/modifications
Index changes
Constraint additions

Example 3: Breaking Change Detection

Scenario: Identify potentially breaking changes before deployment.

ef-migration-diff compare \
  --branch1 production \
  --branch2 release/v2.0 \
  --detect-breaking-changes \
  --output csv \
  --output-path ./breaking-changes.csv

Example 4: Custom Migration Paths

Scenario: Project has migrations in non-standard locations.

ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/users \
  --migrations-path ./src/Data/Migrations \
  --output json

Example 5: Validate Current Branch

Scenario: Check if current branch has valid migrations.

ef-migration-diff validate \
  --strict-mode \
  --check-duplicates \
  --check-orphans

Example 6: Caching for Performance

Scenario: Running multiple comparisons on the same branches.

ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/users \
  --use-cache \
  --cache-ttl 3600

The tool caches analysis results for 1 hour by default.

Example 7: GitHub Integration

Scenario: Automatically post results as PR comment.

ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/users \
  --post-to-github \
  --github-token $GITHUB_TOKEN \
  --github-repo owner/repo \
  --github-pr 42

Example 8: Batch Processing

Scenario: Compare multiple feature branches against main.

#!/bin/bash
for branch in feature/* ; do
  echo "Analyzing $branch..."
  ef-migration-diff compare \
    --branch1 main \
    --branch2 "$branch" \
    --output json \
    --output-path "reports/$(basename $branch).json"
done

Example 9: Integration Testing

Scenario: Run migrations in test environment and compare.

ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/schema-change \
  --run-migrations \
  --test-connection "Server=localhost;Database=TestDb;..."

Example 10: CI/CD Pipeline Integration

Scenario: Prevent merging without migration review (in GitHub Actions).

- name: Check migrations
  run: |
    ef-migration-diff validate --strict-mode
    ef-migration-diff compare \
      --branch1 origin/main \
      --branch2 HEAD \
      --detect-breaking-changes \
      && echo "✓ Migrations safe to merge" \
      || exit 1

CLI Reference

compare Command

Compare migrations between two Git branches.

Usage:

ef-migration-diff compare [options]

Options:

Option	Short	Type	Default	Description
`--branch1`	`-b1`	string	-	Required. Base branch name
`--branch2`	`-b2`	string	-	Required. Compare branch name
`--output`	`-o`	string	`console`	Output format: json, csv, html, console
`--output-path`	`-op`	string	-	File path for output (required for non-console)
`--migrations-path`	`-mp`	string	`Migrations`	Path to migrations folder
`--strict-mode`	`-s`	flag	false	Fail on any conflicts
`--include-schema-preview`	`-sp`	flag	false	Include before/after schema
`--detect-breaking-changes`	`-dbc`	flag	false	Analyze for data loss scenarios
`--use-cache`	`-uc`	flag	false	Use cached results
`--cache-ttl`	`-ct`	int	3600	Cache time-to-live in seconds
`--post-to-github`	`-gh`	flag	false	Post results to GitHub PR
`--github-token`	`-ght`	string	-	GitHub API token
`--github-repo`	`-ghr`	string	-	Repository in format owner/repo
`--github-pr`	`-ghp`	int	-	Pull request number

Examples:

# Basic comparison
ef-migration-diff compare -b1 main -b2 develop

# With report generation
ef-migration-diff compare -b1 main -b2 feature/users -o html -op report.html

# Strict validation
ef-migration-diff compare -b1 main -b2 develop -s

# With schema preview
ef-migration-diff compare -b1 main -b2 develop -sp -o json -op diff.json

validate Command

Validate migrations on current branch.

Usage:

ef-migration-diff validate [options]

Options:

Option	Short	Type	Default	Description
`--branch`	`-b`	string	HEAD	Branch to validate
`--check-duplicates`	`-cd`	flag	true	Check for duplicate migrations
`--check-orphans`	`-co`	flag	true	Check for orphaned migrations
`--check-syntax`	`-cs`	flag	true	Validate migration C# syntax
`--strict-mode`	`-s`	flag	false	Fail on any issues

Examples:

# Quick validation
ef-migration-diff validate

# Strict validation
ef-migration-diff validate -s

# Only duplicate check
ef-migration-diff validate -cd -b feature/users

help Command

Display help information.

Usage:

ef-migration-diff help [command]

Examples:

ef-migration-diff help                 # Show all commands
ef-migration-diff help compare         # Show compare command details
ef-migration-diff help validate        # Show validate command details

API Reference

Comparison Service

var service = new MigrationDiffService(
    migrationRepository, 
    schemaDetector,
    conflictDetectionService);

var result = await service.CompareBranchesAsync(
    branch1: "main",
    branch2: "feature/users",
    options: new ComparisonOptions 
    { 
        IncludeSchemaPreview = true,
        DetectBreakingChanges = true
    });

// Access results
var hasDifferences = result.HasDifferences;
var conflicts = result.Conflicts;
var schemaChanges = result.SchemaChanges;

Conflict Detection

var service = new ConflictDetectionService();

var conflicts = await service.DetectConflictsAsync(
    migrations1,
    migrations2);

foreach (var conflict in conflicts)
{
    Console.WriteLine($"Conflict: {conflict.MigrationName}");
    Console.WriteLine($"Type: {conflict.ConflictType}");
    Console.WriteLine($"Severity: {conflict.Severity}");
}

Schema Analysis

var analyzer = new SchemaChangeDetectorService();

var changes = await analyzer.DetectChangesAsync(
    oldMigrations,
    newMigrations);

foreach (var change in changes)
{
    Console.WriteLine($"Table: {change.TableName}");
    Console.WriteLine($"Operation: {change.OperationType}");
    Console.WriteLine($"Fields: {string.Join(", ", change.AffectedColumns)}");
}

Report Generation

var engine = new ReportEngine();

// Generate HTML report
var htmlReport = await engine.GenerateHtmlReportAsync(
    migrationDiff,
    options: new ReportOptions
    {
        IncludeTimestamp = true,
        IncludeStatistics = true,
        IncludeRecommendations = true
    });

await System.IO.File.WriteAllTextAsync("report.html", htmlReport);

Configuration

appsettings.json

{
  "EfMigrationDiff": {
    "DefaultOutputFormat": "console",
    "MigrationsPath": "Migrations",
    "CacheEnabled": true,
    "CacheTtlSeconds": 3600,
    "StrictModeDefault": false,
    "Logging": {
      "LogLevel": "Information"
    },
    "GitHub": {
      "Enabled": false,
      "ApiUrl": "https://api.github.com"
    },
    "Performance": {
      "MaxConcurrentAnalysis": 4,
      "EnableCaching": true,
      "CacheDirectory": ".cache"
    }
  }
}

Environment Variables

Variable	Description	Example
`EFMIGDIFF_OUTPUT_FORMAT`	Default output format	`json`
`EFMIGDIFF_MIGRATIONS_PATH`	Path to migrations	`./Data/Migrations`
`EFMIGDIFF_CACHE_ENABLED`	Enable caching	`true`
`EFMIGDIFF_CACHE_TTL`	Cache TTL in seconds	`3600`
`EFMIGDIFF_GITHUB_TOKEN`	GitHub API token	`ghp_xxx...`
`EFMIGDIFF_STRICT_MODE`	Strict validation mode	`false`

Programmatic Configuration

var config = new AppSettings
{
    DefaultOutputFormat = OutputFormat.Json,
    MigrationsPath = "Data/Migrations",
    CacheEnabled = true,
    CacheTtlSeconds = 3600,
    StrictModeDefault = false
};

var services = DependencyInjection.ConfigureServices(
    new ConfigurationBuilder()
        .AddInMemoryCollection(new Dictionary<string, string>
        {
            ["EfMigrationDiff:MigrationsPath"] = "Data/Migrations"
        })
        .Build());

Performance

ef-migration-diff is optimized for both small projects and large enterprise codebases.

Operation	Dataset	Time
Branch comparison	100 migrations	<200ms
Branch comparison	500 migrations	<800ms
Schema analysis	Typical project	<50ms
Conflict detection	1 000 migrations	<2s
Report generation (HTML)	500 changes	<300ms
Cached repeat comparison	Any size	<20ms

Performance Tips

Enable caching (--use-cache) for repeated comparisons — reduces repeat analysis time by ~90%
Use --output json instead of --output html when parsing results programmatically
Set MaxConcurrentAnalysis in configuration to match your CPU core count
For migration sets of 1 000+, increase CacheTtlSeconds to avoid redundant re-analysis

Troubleshooting

Issue: "Migration files not found"

Cause: Tool is looking in wrong directory

Solution:

# Specify correct migrations path
ef-migration-diff compare \
  --branch1 main \
  --branch2 feature/users \
  --migrations-path ./src/Data/Migrations

Issue: "DbContext not discovered"

Cause: DbContext classes not in standard locations

Solution:

Ensure DbContext inherits from DbContext
Place in project root or Models/ directory
Configure path in appsettings.json

{
  "DbContextPath": "./Models"
}

Issue: "Out of memory on large migrations"

Cause: Too many migrations loaded simultaneously

Solution:

# Enable caching and streaming
ef-migration-diff compare \
  --branch1 main \
  --branch2 develop \
  --use-cache \
  --cache-ttl 7200

Issue: "Git operation failed"

Cause: Repository state issues

Solution:

# Ensure repository is clean
git status
git stash

# Try again
ef-migration-diff compare -b1 main -b2 feature/users

Issue: "Permission denied accessing migrations"

Cause: File permissions issue

Solution:

# Ensure read access
chmod -R 755 ./Migrations

# Or run with elevated privileges
sudo ef-migration-diff compare -b1 main -b2 develop

Testing

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test project
dotnet test tests/ef-migration-diff.Tests/

# Run with verbose output
dotnet test --logger "console;verbosity=detailed"

The test suite covers:

Migration parsing and comparison logic (MigrationServicesTests)
String and collection extension utilities (StringAndCollectionExtensionsTests)
Input validation and error handling (ValidationHelperTests)

Related Projects

dotnet-deploy-notify - Deployment notification pipeline for .NET — build status to Telegram/Slack/Discord webhooks

Integration Examples

Send migration conflict alerts via webhook

After detecting conflicts, trigger a deployment notification using dotnet-deploy-notify:

var diffService = serviceProvider.GetRequiredService<MigrationDiffService>();
var diff = await diffService.CompareBranchesAsync("main", "feature/users");

if (diff.HasConflicts)
{
    var notifier = new DeployNotifier(webhookUrl);
    await notifier.SendAsync($"Migration conflicts detected: {diff.Conflicts.Count} conflict(s) found before merge.");
}

Gate deployment pipelines on migration safety

var result = await migrationDiffService.CompareBranchesAsync(
    branch1: "main",
    branch2: Environment.GetEnvironmentVariable("DEPLOY_BRANCH"));

if (result.HasBreakingChanges)
{
    await deployNotifier.SendAsync(
        channel: "#deployments",
        message: $"Deploy blocked: {result.BreakingChanges.Count} breaking schema change(s) detected.");
    return ExitCodes.Failure;
}

Contributing

We welcome contributions! To get started:

Fork the repository on GitHub
Clone your fork: git clone https://github.com/YOUR_USERNAME/ef-migration-diff.git
Create a feature branch: git checkout -b feature/your-feature
Make your changes and test thoroughly
Commit with clear messages: git commit -am "Add feature: description"
Push to your fork: git push origin feature/your-feature
Open a Pull Request with detailed description

Development Setup

# Install dependencies
dotnet restore

# Build project
dotnet build

# Run tests
dotnet test

# Run in debug mode
dotnet run -- compare --branch1 main --branch2 develop

# Format code
dotnet format

# Run static analysis
dotnet analyzers run

Code Style Guidelines

Follow C# coding conventions
Use meaningful variable names
Add XML documentation comments
Write unit tests for new features
Keep methods under 50 lines
Use dependency injection

Reporting Issues

Found a bug? Please create an issue with:

Clear title and description
Steps to reproduce
Expected vs actual behavior
Your environment (OS, .NET version)
Relevant logs

License

Built by Vladyslav Zaiets - CTO & Software Architect

Portfolio | GitHub | Telegram

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
Analysis		Analysis
BackgroundWork		BackgroundWork
CLI		CLI
Caching		Caching
Configuration		Configuration
Events		Events
Exceptions		Exceptions
Extensions		Extensions
Formatters		Formatters
Integration		Integration
Middleware		Middleware
Models		Models
Monitoring		Monitoring
Plugins		Plugins
Reports		Reports
Repositories		Repositories
Services		Services
Utilities		Utilities
docs		docs
examples		examples
tests/ef-migration-diff.Tests		tests/ef-migration-diff.Tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
Program.cs		Program.cs
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
ef-migration-diff.csproj		ef-migration-diff.csproj
ef-migration-diff.sln		ef-migration-diff.sln

Folders and files

Latest commit

History

Repository files navigation

ef-migration-diff

Table of Contents

Overview

Why You Need This

Key Features

Migration Comparison

Schema Change Detection

Multiple Output Formats

Integration Features

Performance

Robust Processing

Architecture

Layer Descriptions

Installation

Prerequisites

Method 1: Clone and Build

Method 2: Docker

Method 3: Local Installation

Verify Installation

Quick Start

1. Basic Comparison

2. Generate HTML Report

3. Check for Conflicts

4. Export as JSON

Usage Examples

Example 1: Detecting Migration Name Conflicts

Example 2: Schema Change Preview

Example 3: Breaking Change Detection

Example 4: Custom Migration Paths

Example 5: Validate Current Branch

Example 6: Caching for Performance

Example 7: GitHub Integration

Example 8: Batch Processing

Example 9: Integration Testing

Example 10: CI/CD Pipeline Integration

CLI Reference

compare Command

validate Command

help Command

API Reference

Comparison Service

Conflict Detection

Schema Analysis

Report Generation

Configuration

appsettings.json

Environment Variables

Programmatic Configuration

Performance

Performance Tips

Troubleshooting

Issue: "Migration files not found"

Issue: "DbContext not discovered"

Issue: "Out of memory on large migrations"

Issue: "Git operation failed"

Issue: "Permission denied accessing migrations"

Testing

Related Projects

Integration Examples

Contributing

Development Setup

Code Style Guidelines

Reporting Issues

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages