# Configuration

Full reference for socigy.json — the project-level config file that drives migration generation and DI code generation.

## What is socigy.json?

`socigy.json` is a small JSON file placed in the root of your DB class library project. The CLI migration tool reads it on every run to know which database platform to target, what name to give the database, and which helper code to generate alongside the migrations.

If the file does not exist when you first run `dotnet build -c DB_Migration`, the tool creates it automatically with PostgreSQL defaults.

## Location

Place `socigy.json` next to your `.csproj` file — the tool receives the project directory as the `--project-dir` argument and looks for the file there.

```filetree
MyApp.DB/
├── MyApp.DB.csproj
├── socigy.json              ← lives here
├── Users/
│   └── User.cs
└── Socigy/
    ├── structure.json
    └── Migrations/
        └── 202605011200_Initial_Migration_abc123.g.cs
```

## Full Schema

```json
{
  "database": {
    "platform": "postgresql",
    "databaseName": "AuthDb",
    "migrationNameTemplate": "${Name}",
    "generateDbConnectionFactory": true,
    "generateWebAppExtensions": true
  },
  "shouldShowMessageOnEmptyMigrationGeneration": true
}
```

## Field Reference

### `database.platform`

The target database engine. Only PostgreSQL is supported in this release.

| Accepted value | Notes |
|----------------|-------|
| `"postgresql"` | Standard (recommended) |
| `"postgres"` | Alias |
| `"npgsql"` | Alias |
| `"postgre"` | Alias |

### `database.databaseName`

**Required.** A short identifier for this database. Used as:

- The key under `ConnectionStrings` in `appsettings.json` — the generated factory looks up `ConnectionStrings.{databaseName}.Default`
- The suffix on generated DI methods — `databaseName: "AuthDb"` → `AddAuthDb()`, `EnsureLatestAuthDbMigration()`
- The [key](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection#keyed-services) used to register `IDbConnectionFactory` and `IMigrationManager` in the DI container

```json
"databaseName": "AuthDb"
```

Results in:

```csharp
// Generated extension methods
builder.AddAuthDb();
await app.EnsureLatestAuthDbMigration();

// DI key for manual resolution
var factory = sp.GetRequiredKeyedService<IDbConnectionFactory>("AuthDb");
```

### `database.migrationNameTemplate`

Controls the filename (and embedded class name) of generated migration files. Two placeholders are available:

| Placeholder | Value |
|-------------|-------|
| `${Name}` | The migration name entered interactively (Windows) or auto-generated from the schema diff (Linux/CI) |
| `${Timestamp}` | Current UTC timestamp as `yyyyMMddHHmm` |

Examples:

```json
"migrationNameTemplate": "${Name}"
// → Initial_Migration_abc123.g.cs

"migrationNameTemplate": "${Timestamp}_${Name}"
// → 202605011200_Initial_Migration_abc123.g.cs
```

The default is `"${Name}"`. Use `"${Timestamp}_${Name}"` when you want migrations to sort chronologically in the file system.

### `database.generateDbConnectionFactory`

**Default: `true`.** When true, the source generator emits:

- An implementation of `IDbConnectionFactory` keyed to `databaseName`
- `AddAuthDb()` extension on `WebApplicationBuilder`, `IServiceCollection`, and `IHostApplicationBuilder`
- Keyed `IDbConnectionFactory` and `IMigrationManager` registrations in DI

Set to `false` only if you are managing connections entirely manually and do not want the generated DI code.

### `database.generateWebAppExtensions`

**Default: `true`.** When true, also generates:

- `app.EnsureLatestAuthDbMigration()` extension on `WebApplication` — applies all pending migrations at startup
- Requires `generateDbConnectionFactory: true` to also be set

### `shouldShowMessageOnEmptyMigrationGeneration`

**Default: `true`.** When true, the CLI tool prints a message when it detects no schema changes (and therefore generates no migration file). Set to `false` to suppress the message in CI pipelines where you expect many no-op builds.

## Connection String Format

The generated factory reads the connection string from `appsettings.json` under `ConnectionStrings.{databaseName}`:

```json
{
  "ConnectionStrings": {
    "AuthDb": {
      "Default": "Host=localhost;Port=5432;Username=app;Password=secret;Pooling=true",
      "ReadOnly": "Host=replica.internal;Port=5432;Username=app_ro;Password=secret"
    }
  }
}
```

The sub-key (`"Default"`, `"ReadOnly"`) is passed as the `connectionKey` argument to `IDbConnectionFactory.Create(connectionKey)`. Passing `null` (the default) resolves to `"Default"`.

> **NOTE** Do **not** include `Database=` — the factory automatically appends it using `databaseName` from `socigy.json`.

> **TIP** Add `appsettings.Development.json` with local connection strings and keep `appsettings.json` in version control with placeholder values. Never commit real passwords.