/DB

Configuration

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

updated 5 Jun 20263 min readv0.3.2View as Markdown

What is socigy.json?

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

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

Location

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

MyApp.AppDb/
├── MyApp.AppDb.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. PostgreSQL is the only supported engine in this release. The value is matched against a fixed set of aliases; anything outside this set means no DI context or migration code is generated.

Accepted value Notes
"postgresql" Standard (recommended)
"postgres" Alias
"postgre" Alias
"npgsql" Recognized by the migration tool only, but the source generator does not emit the DI/context code for it, so prefer "postgresql"

`database.databaseName`

The identifier for this database. It defaults to "UnnamedDb" when omitted, so set it explicitly. The value is used verbatim as the {Db} prefix everywhere:

  • The key under ConnectionStrings in appsettings.json. The generated factory looks up ConnectionStrings:{databaseName}:Default.
  • The suffix on generated DI methods. databaseName: "AuthDb" produces AddAuthDb() and EnsureLatestAuthDbMigration().
  • The key used to register IDbConnectionFactory and IMigrationManager in the DI container.
  • The name of the PostgreSQL database itself. The factory creates and connects to a database named {databaseName}.
"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 on Windows, where the migration name is entered interactively. Two placeholders are available:

Placeholder Value
${Name} The migration name you type in the prompt
${Timestamp} Current UTC timestamp as yyyyMMddHHmm

Every generated file is also prefixed with a UTC timestamp and suffixed with a short content hash automatically, so names stay unique and chronologically sortable regardless of template:

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

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

The default is "${Name}".

NOTE
On Linux and CI runs there is no interactive prompt. The migration name is derived automatically from the schema diff and the template is not applied. See Applying migrations.

`database.generateDbConnectionFactory`

Default true. When true, the source generator emits:

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

Set it to false only if you manage connections entirely by hand and do not want the generated DI code.

`database.generateWebAppExtensions`

Default true. When true, the generator also emits:

  • app.EnsureLatestAuthDbMigration() on WebApplication and IHost, which applies all pending migrations at startup

This requires generateDbConnectionFactory: true.

`shouldShowMessageOnEmptyMigrationGeneration`

Default true. When true, the tool reports that no schema changes were detected (and therefore no migration file was written). Set it to false to silence the message in CI pipelines where no-op builds are expected.

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

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