/DB

CLI tool

The bundled migration CLI generates migration classes from your C# models, no global tool install required.

updated 5 Jun 20262 min readv0.3.2View as Markdown

Overview

Socigy.OpenSource.DB ships a CLI tool (Socigy.OpenSource.DB.Tool) inside the NuGet package. It loads your compiled assembly, reads every [Table] and [FlagTable] annotated type through reflection metadata, and generates PostgreSQL DDL.

The tool runs through an MSBuild target that the package registers automatically. There is no dotnet tool install step.

Running the tool

Build your model project in the DB_Migration configuration to trigger the migration target:

dotnet build MyApp.AppDb/MyApp.AppDb.csproj -c DB_Migration

The target invokes the tool with the compiled assembly and project directory. The tool analyses the assembly and writes migration files into the project.

What gets generated

For each annotated type the tool emits DDL covering:

  • CREATE TABLE IF NOT EXISTS with all columns, types, and DEFAULT expressions
  • PRIMARY KEY constraints
  • FOREIGN KEY constraints (from [ForeignKey])
  • UNIQUE constraints (from [Unique])
  • CHECK constraints (from [Check], [StringLength], [Min], [Max])
  • CREATE SEQUENCE IF NOT EXISTS for [AutoIncrement] columns
  • INSERT ... ON CONFLICT DO UPDATE seed data for [Table]-annotated enums and [FlaggedEnum] reference tables

The DDL is wrapped in a generated .g.cs migration class that implements ILocalMigration, ready to be applied at runtime by the migration manager.

Output files

The tool writes to Socigy/Migrations/ in the project directory. Each run produces a timestamped C# file:

Socigy/
├── structure.json
└── Migrations/
    └── 202605011200_Initial_Migration_abc123.g.cs

A working snapshot of the model (Socigy/structure.json) is kept alongside the migrations so later runs can diff against it.

NOTE
The tool only generates migration classes. It never connects to your database. Migrations are applied at runtime by the generated extension or the migration manager, see Applying migrations.

Incremental migrations

On the first run the tool emits a full CREATE baseline. On every later run it compares the current model against the previous structure.json baseline and emits only the statements needed to bring the schema up to date.

Supported drift types:

  • New columns (ALTER TABLE ... ADD COLUMN)
  • Removed columns (ALTER TABLE ... DROP COLUMN)
  • Type changes (ALTER TABLE ... ALTER COLUMN ... TYPE)
  • New or removed constraints

Column renames

Use [Renamed("old_name")] to tell the tool a column was renamed rather than dropped and re-added:

[Renamed("user_name")]
public string Username { get; set; }

Without [Renamed], a renamed column is treated as a drop followed by an add, and the data is lost.

Supported platforms

The tool ships two builds inside the package:

Path in package Target Runs on
tools/any/ net10.0 (framework-dependent) Any OS with .NET 10 installed
tools/win/ net10.0-windows Windows only

The Windows build adds an interactive prompt for the migration name. On Linux and CI the tools/any/ build is selected and the name is generated automatically.