# CLI tool

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

## 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:

```bash
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:

```plaintext
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](/database/0.3.2/migration/applying).

## 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:

```csharp
[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.