SchemaForge 1.0.0

SchemaForge

A cross-database migration tool for .NET that migrates schemas and data between different database systems.

Supported Databases

• SQL Server (source and target)
• PostgreSQL (source and target)
• MySQL (source and target)
• Oracle (source and target)

Features

• Schema Migration - Tables, columns, primary keys, foreign keys
• Data Migration - Bulk data transfer with configurable batch sizes
• View Migration - SQL dialect conversion for view definitions
• Index Migration - Including unique, filtered, and covering indexes
• Constraint Migration - CHECK, UNIQUE, and DEFAULT constraints
• Naming Convention Conversion - Automatic conversion between snake_case, PascalCase, etc.
• Table Dependency Sorting - Proper ordering based on foreign key relationships
• Dry Run Mode - Generate and preview SQL without executing against the target database
• Configurable Options - Migrate all or select specific components
• Fluent API - Chainable builder pattern for programmatic configuration

Quick Start

Prerequisites

• .NET 9.0 SDK or later
• Access to source and target databases

1. Clone and build

git clone https://github.com/your-org/SchemaForge.git
cd SchemaForge
dotnet build

2. Run via CLI

# Full migration
schemaforge --from sqlserver --to postgres \
  --source-conn "Server=localhost;Database=SourceDB;User Id=sa;Password=pass;TrustServerCertificate=True" \
  --target-conn "Host=localhost;Database=targetdb;Username=postgres;Password=pass" \
  --schema public

# Or with dotnet run
dotnet run -- --from sqlserver --to postgres \
  --source-conn "Server=localhost;..." --target-conn "Host=localhost;..."

3. Or configure via appsettings.json

Copy the template and fill in your connection strings:

cp appsettings.template.json appsettings.json
dotnet run

4. Or use the fluent API in code

using SchemaForge.Builder;

await DbMigrate
    .FromSqlServer("Server=localhost;Database=SourceDB;User Id=sa;Password=pass;TrustServerCertificate=True")
    .ToPostgres("Host=localhost;Database=targetdb;Username=postgres;Password=pass", "public")
    .MigrateAll()
    .ExecuteAsync();

Install as a .NET global tool

dotnet pack
dotnet tool install --global --add-source ./nupkg SchemaForge
schemaforge --help

CLI Usage

SchemaForge is a full CLI tool powered by System.CommandLine. All options can be passed as command-line arguments, with appsettings.json and environment variables as fallbacks.

Config resolution order: CLI args > environment variables > appsettings.json > defaults

# Full migration
schemaforge --from sqlserver --to postgres \
  --source-conn "Server=localhost;..." \
  --target-conn "Host=localhost;..." \
  --schema public

# Schema only, dry run to file
schemaforge --from mysql --to postgres \
  --source-conn "..." --target-conn "..." \
  --schema-only --dry-run --dry-run-output migration.sql

# With table filtering
schemaforge --from sqlserver --to mysql \
  --source-conn "..." --target-conn "..." \
  --include-tables Users,Orders --batch-size 5000

# Version
schemaforge --version

CLI Options

Configuration

Create an appsettings.json file in the project directory:

{
  "SourceDatabaseType": "sqlserver",
  "TargetDatabaseType": "postgres",
  "SourceConnectionString": "Server=localhost;Database=SourceDB;User Id=sa;Password=YourPassword;TrustServerCertificate=True",
  "TargetConnectionString": "Host=localhost;Database=targetdb;Username=postgres;Password=YourPassword",
  "TargetSchemaName": "public",
  "BatchSize": 1000,
  "NamingConvention": "auto",
  "UseTargetDatabaseStandards": true,
  "PreserveSourceCase": false,
  "MigrationOptions": {
    "MigrateSchema": true,
    "MigrateData": true,
    "MigrateViews": true,
    "MigrateIndexes": true,
    "MigrateConstraints": true,
    "MigrateForeignKeys": true,
    "DataBatchSize": 1000,
    "ContinueOnError": true,
    "IncludeTables": [],
    "ExcludeTables": []
  }
}

Connection strings also support environment variable substitution (e.g., ${SOURCE_CONNECTION_STRING}).

Configuration Options

Migration Options

Usage

Run Migration

# Via CLI arguments
dotnet run -- --from sqlserver --to postgres \
  --source-conn "Server=localhost;..." --target-conn "Host=localhost;..."

# Via appsettings.json (fallback when no CLI args provided)
dotnet run

Predefined Migration Presets

You can use predefined configurations in code:

// Full migration (schema + data)
var options = MigrationOptions.Full;

// Schema only (no data)
var options = MigrationOptions.SchemaOnly;

// Data only (assumes schema exists)
var options = MigrationOptions.DataOnly;

// Tables only (no views, indexes, constraints)
var options = MigrationOptions.TablesOnly;

Fluent API

Use the fluent API for programmatic migration configuration:

using SchemaForge.Builder;

// Basic migration: SQL Server to PostgreSQL
await DbMigrate
    .FromSqlServer("Server=localhost;Database=SourceDB;...")
    .ToPostgres("Host=localhost;Database=targetdb;...", "public")
    .MigrateAll()
    .ExecuteAsync();

// Schema only migration
await DbMigrate
    .FromSqlServer("...")
    .ToPostgres("...")
    .MigrateSchemaOnly()
    .ExecuteAsync();

// Data only migration (assumes schema exists)
await DbMigrate
    .FromPostgres("...")
    .ToMySql("...")
    .MigrateDataOnly()
    .ExecuteAsync();

// Selective migration with table filtering
await DbMigrate
    .FromSqlServer("...")
    .ToOracle("...", "MYSCHEMA")
    .WithSchema()
    .WithData()
    .WithIndexes()
    .WithoutViews()
    .WithoutConstraints()
    .IncludeTables("Users", "Orders", "Products")
    .ExcludeTables("AuditLog", "TempData")
    .ExecuteAsync();

// Full configuration
await DbMigrate
    .FromSqlServer("...")
    .ToPostgres("...", "app")
    .MigrateAll()
    .WithBatchSize(5000)
    .ContinueOnError()
    .WithNamingConvention("snake_case")
    .ConfigureLogging(logging => logging
        .AddConsole()
        .SetMinimumLevel(LogLevel.Debug))
    .ExecuteAsync();

// Generic database configuration
await DbMigrate
    .From("sqlserver", "...")
    .To("postgres", "...", "public")
    .MigrateAll()
    .ExecuteAsync();

Fluent API Methods

Dry Run Mode

Preview all generated SQL before executing against a live database. Dry run mode collects every DDL/DML statement and returns them without making any changes.

// Preview SQL to console
await DbMigrate
    .FromSqlServer("...")
    .ToPostgres("...", "public")
    .MigrateAll()
    .DryRun()
    .ExecuteAsync();

// Write generated SQL to a file
await DbMigrate
    .FromSqlServer("...")
    .ToPostgres("...", "public")
    .MigrateAll()
    .DryRun("/path/to/output.sql")
    .ExecuteAsync();

// Get structured dry run result
DryRunResult result = await DbMigrate
    .FromSqlServer("...")
    .ToPostgres("...", "public")
    .MigrateAll()
    .WithDataSamples(10)
    .ExecuteDryRunAsync();

Console.WriteLine($"Tables: {result.Summary.TableCount}");
Console.WriteLine($"Indexes: {result.Summary.IndexCount}");
Console.WriteLine($"Total statements: {result.Summary.TotalStatements}");
Console.WriteLine(result.Script);

Dry Run Options

Migration Process

The migration executes in the following order:

1. Read Source Schema - Extract table definitions, columns, keys, indexes, constraints
2. Sort Tables - Order by foreign key dependencies (parent tables first)
3. Create Tables - Create table structures with primary keys
4. Migrate Data - Bulk transfer data in batches (constraints disabled during import)
5. Create Indexes - Add indexes after data for better performance
6. Create Constraints - Add CHECK, UNIQUE, DEFAULT constraints
7. Create Views - Create views with converted SQL definitions
8. Create Foreign Keys - Add foreign key relationships

Data Type Mapping

The tool automatically maps data types between databases:

Naming Convention Conversion

When NamingConvention is set to auto, identifiers are converted to match target database standards:

Project Structure

SchemaForge/
├── Builder/
│   ├── DbMigrate.cs               # Static fluent API entry point
│   └── MigrationBuilder.cs        # Fluent builder implementation
├── Configuration/
│   └── MigrationSettings.cs       # Configuration model
├── Models/
│   ├── ColumnSchema.cs            # Column definition
│   ├── TableSchema.cs             # Table definition
│   ├── ForeignKeySchema.cs        # Foreign key definition
│   ├── Schemas.cs                 # Index, View, Constraint schemas
│   ├── DatabaseDialect.cs         # SQL dialect definitions
│   ├── MigrationOptions.cs        # Migration options
│   ├── DryRunOptions.cs           # Dry run configuration
│   └── DryRunResult.cs            # Dry run output model
├── Services/
│   ├── Interfaces/                # Service contracts
│   ├── SchemaReader/              # Read schema from databases
│   ├── SchemaWriter/              # Write schema to databases
│   ├── DataReader/                # Read data from databases
│   ├── DataWriter/                # Write data to databases
│   ├── MigrationOrchestrator.cs   # Main migration coordinator
│   ├── BulkDataMigrator.cs        # Data migration service
│   ├── TableDependencySorter.cs   # FK dependency ordering
│   ├── SnakeCaseConverter.cs      # Naming conversion
│   ├── UniversalDataTypeMapper.cs # Type mapping
│   ├── SqlDialectConverter.cs     # SQL expression conversion
│   ├── SqlCollector.cs            # Dry run SQL collector
│   └── DatabaseStandardsProvider.cs # DB conventions
├── Examples/                      # Usage examples
├── Program.cs                     # Entry point & DI setup
├── SchemaForge.csproj             # Project file
├── appsettings.json               # Configuration
├── appsettings.template.json      # Configuration template
└── DESIGN_PATTERNS.md             # Architecture & design documentation

Architecture

SchemaForge uses a strategy-based architecture with keyed dependency injection. Each database has dedicated implementations for schema reading, schema writing, data reading, and data writing. The MigrationOrchestrator coordinates the full migration workflow.

For a detailed breakdown of design patterns and architectural decisions, see DESIGN_PATTERNS.md.

Requirements

• .NET 9.0 or later
• Access to source and target databases

NuGet Packages

• Microsoft.Data.SqlClient - SQL Server connectivity
• Npgsql - PostgreSQL connectivity
• MySql.Data - MySQL connectivity
• Oracle.ManagedDataAccess.Core - Oracle connectivity
• Microsoft.Extensions.Configuration - Configuration management
• Microsoft.Extensions.Configuration.EnvironmentVariables - Environment variable configuration provider
• Microsoft.Extensions.Configuration.Json - JSON configuration provider
• Microsoft.Extensions.DependencyInjection - Dependency injection
• Microsoft.Extensions.Logging - Logging abstractions
• Microsoft.Extensions.Logging.Console - Console logging provider
• Microsoft.Extensions.Options.ConfigurationExtensions - Options configuration support
• System.CommandLine - Command-line argument parsing

Limitations

• Stored procedures, functions, and triggers are not migrated
• Spatial data types require manual handling
• Some complex view definitions may need manual adjustment
• Circular foreign key dependencies are handled but may require manual verification

License

MIT License