/DB

Configuration

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

updated 3 May 20263 min readv0.1.82

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.

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.

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

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

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

// 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. Always call conn.OpenAsync() before passing it to a query builder.

DI registration at startup

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

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

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