# Configuration

Full reference for socigy.json, the project-level 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 migration CLI 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.

---

## Minimal example

In practice only `platform` and `databaseName` are needed, the rest carry sensible defaults:

```json
{
  "database": {
    "platform": "postgresql",
    "databaseName": "AuthDb"
  }
}
```

## 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 built to support multiple engines later, only PostgreSQL is supported in this release.

| Value          | Notes                          |
|----------------|--------------------------------|
| `"postgresql"` | Canonical value                |
| `"postgres"`   | Alias for `"postgresql"`       |
| `"postgre"`    | Alias for `"postgresql"`       |
| `"npgsql"`     | Recognized by the migration tool only (see note) |

Other values are rejected with a build error.

> **NOTE** Prefer the canonical `"postgresql"` (or `"postgres"`/`"postgre"`). The `"npgsql"` value is accepted by the migration CLI tool when generating DDL, but the source generator does **not** recognize it, so the keyed `IDbConnectionFactory`, the `I{Db}` context, and the DI extension methods are not emitted for it.

---

### database.databaseName

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

A logical name for the database. This value drives code generation in three places:

1. **DI registration names**, where the generated extensions become `Add{databaseName}()` and `Add{databaseName}Context()`, and the `IDbConnectionFactory` is keyed by this name.
2. **Context types**, where the generator emits `I{databaseName}` and `{databaseName}Context` plus the migration helper `EnsureLatest{databaseName}Migration()`.
3. **Connection string lookup key**, where the section `ConnectionStrings:{databaseName}` in `appsettings.json` is read by the generated factory.

Example: `"databaseName": "AuthDb"` produces `AddAuthDb()`, `AddAuthDbContext()`, `IAuthDb`, 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}"
```

Including `${Timestamp}` keeps migrations sorted chronologically in the file system.

---

### database.generateDbConnectionFactory

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

When `true`, the build emits:

- An `IDbConnectionFactory` implementation keyed to `databaseName`.
- An `Add{DatabaseName}()` 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`, giving `builder.AddAuthDb()`.
- `HostApplicationBuilder`, giving `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 reports that no schema changes were detected and aborts without writing a migration file. 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 nests 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"
    }
  }
}
```

> **WARNING** Do **not** include `Database=` in the connection string. The generated factory appends `Database={databaseName}` when it creates a connection.

Multiple connection keys are supported within the same named database. The `"Default"` key 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 is still closed at `ExecuteAsync()` time, so calling `conn.OpenAsync()` yourself is optional. 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`, register both the connection factory and the context:

```csharp
using Socigy.OpenSource.DB.AuthDb.Extensions;

// WebApplicationBuilder or HostApplicationBuilder
builder.AddAuthDb();                  // registers IDbConnectionFactory (keyed "AuthDb")
builder.Services.AddAuthDbContext();  // registers ISocigyDatabaseFactory<IAuthDb>
```

`AddAuthDb()` registers:

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

`AddAuthDbContext()` registers the context factory `ISocigyDatabaseFactory<IAuthDb>`, the recommended way to run data access. See [Database context](/database/0.3.2/core-concepts/database-context).

To apply all pending migrations on startup:

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