# 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 migration tool reads it on every run to learn which database platform to target, what to name the database, and which helper code to generate alongside the migrations.

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

## Location

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

```filetree
MyApp.AppDb/
├── MyApp.AppDb.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. PostgreSQL is the only supported engine in this release. The value is matched against a fixed set of aliases; anything outside this set means no DI context or migration code is generated.

| Accepted value | Notes |
|----------------|-------|
| `"postgresql"` | Standard (recommended) |
| `"postgres"` | Alias |
| `"postgre"` | Alias |
| `"npgsql"` | Recognized by the migration tool only, but the source generator does not emit the DI/context code for it, so prefer `"postgresql"` |

### `database.databaseName`

The identifier for this database. It defaults to `"UnnamedDb"` when omitted, so set it explicitly. The value is used verbatim as the `{Db}` prefix everywhere:

- The key under `ConnectionStrings` in `appsettings.json`. The generated factory looks up `ConnectionStrings:{databaseName}:Default`.
- The suffix on generated DI methods. `databaseName: "AuthDb"` produces `AddAuthDb()` and `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.
- The name of the PostgreSQL database itself. The factory creates and connects to a database named `{databaseName}`.

```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 on Windows, where the migration name is entered interactively. Two placeholders are available:

| Placeholder | Value |
|-------------|-------|
| `${Name}` | The migration name you type in the prompt |
| `${Timestamp}` | Current UTC timestamp as `yyyyMMddHHmm` |

Every generated file is also prefixed with a UTC timestamp and suffixed with a short content hash automatically, so names stay unique and chronologically sortable regardless of template:

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

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

The default is `"${Name}"`.

> **NOTE** On Linux and CI runs there is no interactive prompt. The migration name is derived automatically from the schema diff and the template is not applied. See [Applying migrations](/database/0.3.2/migration/applying).

### `database.generateDbConnectionFactory`

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

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

Set it to `false` only if you manage connections entirely by hand and do not want the generated DI code.

### `database.generateWebAppExtensions`

Default `true`. When true, the generator also emits:

- `app.EnsureLatestAuthDbMigration()` on `WebApplication` and `IHost`, which applies all pending migrations at startup

This requires `generateDbConnectionFactory: true`.

### `shouldShowMessageOnEmptyMigrationGeneration`

Default `true`. When true, the tool reports that no schema changes were detected (and therefore no migration file was written). Set it to `false` to silence the message in CI pipelines where no-op builds are expected.

## 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 the `connectionKey` argument to `IDbConnectionFactory.Create(connectionKey)`. Passing `null` (the default) resolves to `"Default"`.

> **NOTE** Do not include `Database=`. The factory appends it automatically 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.