# Configuration

Full reference for socigy.json — the project-level config file that controls migration naming, DI code generation, and connection factory output.

## Where socigy.json lives

Place `socigy.json` in the **project root of your DB class library** — the same directory as its `.csproj` file. It is read by the CLI migration tool and by the build target that triggers code generation.

```filetree
MyApp.DB/
├── MyApp.DB.csproj
├── socigy.json          <- here
├── Users/
│   └── User.cs
└── Socigy/
    └── Procedures/
```

> **NOTE** Do not place `socigy.json` in the API project or at the solution root. The tooling looks for it relative to the DB class library, not the entry point project.

If the file is missing when the CLI tool first runs, it creates one with default values. You can also create it manually.

---

## Full example

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

---

## Field reference

### database.platform

**Type:** string  
**Required:** yes

The target database engine. The tooling is designed to support multiple database engines in the future; only PostgreSQL is supported in this release.

| Value          | Notes                          |
|----------------|--------------------------------|
| `"postgresql"` | Canonical value                |
| `"postgres"`   | Alias for `"postgresql"`       |
| `"npgsql"`     | Alias for `"postgresql"`       |
| `"postgre"`    | Alias for `"postgresql"`       |

All four values produce identical output. Other values are rejected with a build error.

---

### database.databaseName

**Type:** string  
**Required:** yes

A logical name for the database. This value is used in two places:

1. **DI registration key** — the generated `AddAuthDb()` extension method is named `Add{databaseName}()`, and the `IDbConnectionFactory` / `IMigrationManager` services are keyed by this name.
2. **Connection string lookup key** — the connection string section `ConnectionStrings.{databaseName}` in `appsettings.json` is read by the generated factory.

Example: `"databaseName": "AuthDb"` produces `AddAuthDb(...)` and reads `ConnectionStrings.AuthDb`.

---

### database.migrationNameTemplate

**Type:** string  
**Default:** `"${Name}"`

Controls how migration file names are generated. Two placeholders are supported:

| Placeholder    | Replaced with                                    |
|----------------|--------------------------------------------------|
| `${Name}`      | The migration name you supply at generation time |
| `${Timestamp}` | A UTC timestamp at generation time               |

Examples:

```json
"migrationNameTemplate": "${Name}"
```

```json
"migrationNameTemplate": "${Timestamp}_${Name}"
```

```json
"migrationNameTemplate": "${Timestamp}"
```

Using `${Timestamp}` in the template ensures migrations sort chronologically in the file system.

---

### database.generateDbConnectionFactory

**Type:** boolean  
**Default:** `true`

When `true`, the build emits:

- An `IDbConnectionFactory` implementation keyed to `databaseName`
- A `Add{DatabaseName}(IConfiguration config)` DI extension on `IServiceCollection`

Set to `false` only if you manage connections entirely outside the generated DI infrastructure.

---

### database.generateWebAppExtensions

**Type:** boolean  
**Default:** `true`

When `true` (and `generateDbConnectionFactory` is also `true`), additional extension methods are generated for:

- `WebApplicationBuilder` — `builder.AddAuthDb()`
- `HostApplicationBuilder` — `builder.AddAuthDb()`

Set to `false` if you use a non-web host and do not need `WebApplicationBuilder` extensions.

---

### shouldShowMessageOnEmptyMigrationGeneration

**Type:** boolean  
**Default:** `true`

When `true`, the CLI tool prints a notice to stdout if it detects no schema changes and generates an empty migration. Set to `false` to suppress this message in CI pipelines where it would add noise.

---

## appsettings.json connection string format

The generated `IDbConnectionFactory` reads connection strings from the standard .NET configuration system. The expected structure uses a nested object under `ConnectionStrings.{databaseName}`:

```json
{
  "ConnectionStrings": {
    "AuthDb": {
      "Default": "Host=localhost;Port=5432;Username=postgres;Password=secret",
      "ReadOnly": "Host=replica.example.com;Port=5432;Username=ro_user;Password=secret"
    }
  }
}
```

> **NOTE** Do **not** include `Database=` in the connection string. The generated factory automatically appends `Database={databaseName}` when creating a connection.

Multiple connection keys are supported within the same named database. The key `"Default"` is used when `IDbConnectionFactory.Create()` is called with no argument (or `null`). Any other key can be requested by name:

```csharp
// Uses the "Default" connection string
var conn = factory.Create();

// Uses the "ReadOnly" connection string
var readConn = factory.Create("ReadOnly");
```

> **NOTE** The connection returned by `Create()` is not pre-opened. The query builders open it automatically if it's still closed at `ExecuteAsync()` time, so calling `conn.OpenAsync()` yourself is optional — but doing so makes the connection's lifetime explicit and lets you reuse one open connection across several builders.

---

## DI registration at startup

After adding `socigy.json` with `databaseName: "AuthDb"` and running `dotnet build`, the following extension methods are available:

```csharp
// WebApplicationBuilder (ASP.NET Core)
builder.AddAuthDb();

// IServiceCollection (any host)
builder.Services.AddAuthDb();

// HostApplicationBuilder
builder.AddAuthDb();
```

Each of these registers:

- `IDbConnectionFactory` (keyed `"AuthDb"`) — creates connections from `appsettings.json`
- `IMigrationManager` (keyed `"AuthDb"`) — applies pending migrations

To apply all pending migrations on startup:

```csharp
var app = builder.Build();
await app.EnsureLatestAuthDbMigration();
```