Installation

Add Socigy.OpenSource.DB to a .NET project, verify the source generator ran, and confirm every prerequisite is met.

updated 5 Jun 20264 min readv0.3.2View as Markdown

Requirements

Component	Minimum version	Notes
.NET	10.0	Required by the Roslyn 4.x incremental source generator
PostgreSQL	14.0	Currently the only supported database engine, required for `gen_random_uuid()` and similar
Npgsql	6.0	Transitive dependency when `platform` is `"postgresql"`, needed for `DateOnly` and `TimeOnly`

NOTE

platform in socigy.json selects the target database engine. PostgreSQL is the only engine supported in this release. The tooling is built to add more engines later.

NOTE

Npgsql arrives as a transitive dependency on the PostgreSQL platform, so you rarely add it yourself. If your project already references Npgsql at a different version, pin it in your .csproj to avoid conflicts.

Add the NuGet package

dotnet add package Socigy.OpenSource.DB

Or reference it directly in your .csproj:

<ItemGroup>
  <PackageReference Include="Socigy.OpenSource.DB" Version="0.3.2" />
</ItemGroup>

What the package contains

Socigy.OpenSource.DB is a single reference that installs three components together:

The base classes and interfaces shared across all DB operations.
Manages the Npgsql connection lifecycle for you.

One package reference covers all three. Adding Socigy.OpenSource.DB is the only install step.

Make your class partial and build

The source generator augments your model classes by adding members in a companion generated file. Each class that maps to a table must be declared partial:

using Socigy.OpenSource.DB.Attributes;

[Table("users")]
public partial class User
{
    [PrimaryKey, Default(DbDefaults.Guid.Random)]
    public Guid Id { get; set; }

    public string Username { get; set; } = "anonymous";

    [Default(DbDefaults.Time.Now)]
    public DateTime CreatedAt { get; set; }
}

NOTE

Schema attributes and the DbDefaults constants live in Socigy.OpenSource.DB.Attributes. A single using covers [Table], [Column], [PrimaryKey], [Default], and the rest. The one exception is [Nullable], which lives in Socigy.OpenSource.DB.Core.Attributes.

Then build:

dotnet build

A successful build means the source generator ran. Inspect the output under obj/{Configuration}/net{version}/generated/Socigy.OpenSource.DB.SourceGenerator/ to find a User.g.cs file containing the generated Insert(), Query(), Update(), and Delete() methods.

TIP

Add obj/ to your .gitignore. Generated files are recreated on every build and should never be committed.

Verify the generated output

To write the generated files to disk, add <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> to your .csproj:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

After building, confirm the generated files exist:

ls obj/Debug/net10.0/generated/Socigy.OpenSource.DB.SourceGenerator/Socigy.OpenSource.DB.SourceGenerator.Program/

You will see one .g.cs file per annotated class. The exact path varies by configuration (Debug, Release, DB_Migration) and target framework. Opening a generated file is a useful debugging technique: it shows exactly what SQL the builder produces.

In Visual Studio and JetBrains Rider, "Go to Definition" on a generated method navigates straight to the generated file.

Npgsql as a standalone reference

Because Npgsql is a transitive dependency, most projects do not need an explicit reference. If you call Npgsql APIs directly (for example NpgsqlDataSource or NpgsqlConnection), add it explicitly:

dotnet add package Npgsql

await using var conn = new NpgsqlConnection(
    "Host=localhost;Port=5432;Database=myapp;Username=postgres;Password=secret");
await conn.OpenAsync();

Never hard-code credentials in source files. Read connection strings from environment variables or appsettings.json in production.

Alternative download: GitHub Packages

If you cannot reach NuGet.org, the package is also published to GitHub Packages. Add the GitHub NuGet source first:

dotnet nuget add source https://nuget.pkg.github.com/WailedParsley36/index.json \
  --name github-socigy \
  --username YOUR_GITHUB_USERNAME \
  --password YOUR_GITHUB_PAT

Then install as normal:

dotnet add package Socigy.OpenSource.DB --source github-socigy

NOTE

GitHub Packages requires authentication even for public packages. Generate a Personal Access Token with the read:packages scope at github.com/settings/tokens.

Dependencies

The package declares two dependencies used by the diagnostics pipeline:

System.Diagnostics.DiagnosticSource for the OpenTelemetry ActivitySource and Meter.
Microsoft.Extensions.Logging.Abstractions for ILogger support.

On .NET 6.0 and later these ship in the shared framework, so they add nothing to a typical web or console app. They are declared so non-framework consumers also resolve them. No action is required on your part.

Next steps

Walk through a complete example in Quickstart.
Build a real application end to end in the Tutorial.
Understand the recommended directory layout in Project structure.
Configure socigy.json for migrations and DI code generation in Configuration.

next →Quickstart