/DB

Installation

Add Socigy.OpenSource.DB to a .NET project, verify the source generator ran, and meet all prerequisites.

updated 3 May 20263 min readv0.1.82

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() etc.
Npgsql 6.0 Transitive dependency when platform is "postgresql"; needed for DateOnly/TimeOnly
NOTE
platform in socigy.json controls which database engine is targeted. PostgreSQL is the only engine supported in this release. The tooling is designed to support additional engines in future releases.
NOTE
Npgsql is a transitive dependency when using the PostgreSQL platform — you normally do not need to add it explicitly. 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 add it directly in your .csproj:

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

What the package contains

Socigy.OpenSource.DB is a meta-package that installs three components together:

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

You do not need separate references to any of these components. Adding Socigy.OpenSource.DB is the only step.

Make your class partial and build

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

using Socigy.OpenSource.DB.Core.Attributes;
using Socigy.OpenSource.DB.Core.Values;

[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; }
}

Then build:

dotnet build

If the build succeeds, the source generator ran. You can inspect the output under obj/Generated/Socigy.OpenSource.DB.SourceGenerator/ — you will find a User.generated.cs file (or similar) containing the generated Insert(), Query(), Update(), and Delete() methods.

TIP
Add obj/ to your .gitignore. Generated files are recreated on every build and should not be committed to source control.

Verify the generated output

To see the generated files on 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 should 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 will produce.

In Visual Studio and JetBrains Rider, "Go to Definition" on a generated method navigates directly 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 need to use Npgsql APIs directly (for example NpgsqlDataSource or NpgsqlConnection), you can 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.

Next steps