# Installation

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

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

```bash
dotnet add package Socigy.OpenSource.DB
```

Or add it directly in your `.csproj`:

```xml
<ItemGroup>
  <PackageReference Include="Socigy.OpenSource.DB" Version="0.2.0" />
</ItemGroup>
```

### What the package contains

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

```infotabs
## Core runtime DLL
- The base classes and interfaces shared across all DB operations.
- Manages the Npgsql connection lifecycle for you.

## Roslyn source generator
- Runs during `dotnet build` — no runtime reflection.
- Reads `[Table]` and `[Column]` attributes, emits typed C# methods.

## CLI migration tool
- Standalone `socigy-db` binary included with the package.
- Run `socigy-db apply` in CI to keep the schema in sync.
```

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

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

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

```xml
<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>
```

After building, confirm the generated files exist:

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

```bash
dotnet add package Npgsql
```

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

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

```bash
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](https://github.com/settings/tokens).

---

## Next steps

- Walk through a complete example in [Quickstart](/database/0.3.1/getting-started/quickstart).
- Understand the recommended directory layout in [Project structure](/database/0.3.1/getting-started/project-structure).
- Configure `socigy.json` for migrations and DI code generation in [Configuration](/database/0.3.1/getting-started/configuration).

## Dependencies (v0.2.0+)

The package now declares two dependencies used by the diagnostics pipeline:

- `System.Diagnostics.DiagnosticSource` — OpenTelemetry `ActivitySource` / `Meter`.
- `Microsoft.Extensions.Logging.Abstractions` — `ILogger` support.

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