/DB

Configuration

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

updated 5 Jun 20264 min readv0.3.2View as Markdown

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.

MyApp.DB/
├── MyApp.DB.csproj
├── socigy.json <- here
├──
│ └── User.cs
└──
└──
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:

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

Full example

{
  "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:

"migrationNameTemplate": "${Name}"
"migrationNameTemplate": "${Timestamp}_${Name}"
"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}:

{
  "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:

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

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.

To apply all pending migrations on startup:

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