/DB

Configuration

Full reference for socigy.json — the project-level config file that drives migration generation and DI code generation.

updated 3 May 20263 min readv0.1.82

What is socigy.json?

socigy.json is a small JSON file placed in the root of your DB class library project. The CLI migration tool reads it on every run to know which database platform to target, what name to give the database, and which helper code to generate alongside the migrations.

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

Location

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

MyApp.DB/
├── MyApp.DB.csproj
├── socigy.json← lives here
├──
│ └── User.cs
└──
├── structure.json
└──
└── 202605011200_Initial_Migration_abc123.g.cs

Full Schema

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

Field Reference

`database.platform`

The target database engine. Only PostgreSQL is supported in this release.

Accepted value Notes
"postgresql" Standard (recommended)
"postgres" Alias
"npgsql" Alias
"postgre" Alias

`database.databaseName`

Required. A short identifier for this database. Used as:

  • The key under ConnectionStrings in appsettings.json — the generated factory looks up ConnectionStrings.{databaseName}.Default
  • The suffix on generated DI methods — databaseName: "AuthDb" → AddAuthDb(), EnsureLatestAuthDbMigration()
  • The key used to register IDbConnectionFactory and IMigrationManager in the DI container
"databaseName": "AuthDb"

Results in:

// 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. Two placeholders are available:

Placeholder Value
${Name} The migration name entered interactively (Windows) or auto-generated from the schema diff (Linux/CI)
${Timestamp} Current UTC timestamp as yyyyMMddHHmm

Examples:

"migrationNameTemplate": "${Name}"
// → Initial_Migration_abc123.g.cs

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

The default is "${Name}". Use "${Timestamp}_${Name}" when you want migrations to sort chronologically in the file system.

`database.generateDbConnectionFactory`

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

  • An implementation of IDbConnectionFactory keyed to databaseName
  • AddAuthDb() extension on WebApplicationBuilder, IServiceCollection, and IHostApplicationBuilder
  • Keyed IDbConnectionFactory and IMigrationManager registrations in DI

Set to false only if you are managing connections entirely manually and do not want the generated DI code.

`database.generateWebAppExtensions`

Default: true. When true, also generates:

  • app.EnsureLatestAuthDbMigration() extension on WebApplication — applies all pending migrations at startup
  • Requires generateDbConnectionFactory: true to also be set

`shouldShowMessageOnEmptyMigrationGeneration`

Default: true. When true, the CLI tool prints a message when it detects no schema changes (and therefore generates no migration file). Set to false to suppress the message in CI pipelines where you expect many no-op builds.

Connection String Format

The generated factory reads the connection string from appsettings.json under ConnectionStrings.{databaseName}:

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

NOTE
Do not include Database= — the factory automatically appends it 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.