Hellnet.Database 1.0.9

Hellnet Database

PostgreSQL-first database infrastructure library for .NET. Env-first, modular, cloud-native.

Env vars → HellnetDatabaseOptions → NpgsqlDataSource → IDatabaseExecutor / IRepository<T>

Quick Start

1. Install

dotnet add package Hellnet.Database

2. Set environment variables

export HELLNET_DATABASE_HOST=localhost
export HELLNET_DATABASE_PORT=5432
export HELLNET_DATABASE_NAME=mydb
export HELLNET_DATABASE_USERNAME=postgres
export HELLNET_DATABASE_PASSWORD=password

export HELLNET_DATABASE_POOL_MIN_SIZE=10
export HELLNET_DATABASE_POOL_MAX_SIZE=100
export HELLNET_DATABASE_COMMAND_TIMEOUT_SECONDS=30

3. Register in DI

using Hellnet.Database;

var builder = WebApplication.CreateBuilder(args);

// From environment variables (recommended)
builder.Services.AddHellnetDatabase();

// Or with explicit options
builder.Services.AddHellnetDatabase(new HellnetDatabaseOptions
{
    Host = "pg.internal",
    Database = "orders",
    Username = "app",
    Password = "secret",
});

4. Use

public class OrderService
{
    private readonly IDatabaseExecutor _db;
    private readonly IRepository<Order> _orders;

    public OrderService(IDatabaseExecutor db, IRepository<Order> orders)
    {
        _db = db;
        _orders = orders;
    }

    public async Task<IReadOnlyList<Order>> GetPendingAsync()
    {
        return await _db.QueryAsync<Order>(
            "SELECT * FROM orders WHERE status = 'pending'");
    }

    public async Task<Order?> GetByIdAsync(int id)
    {
        return await _orders.GetByIdAsync(id);
    }
}

Features

Connection Management

Uses NpgsqlDataSource for connection pooling, lifecycle, and diagnostics. Configured entirely via environment variables — no connection strings in code.

Resilience (Polly)

Automatic retry with exponential backoff and permanent error discrimination. Does not retry:

Repository Pattern

public interface IRepository<T> where T : class
{
    Task<T?> GetByIdAsync<TId>(TId id, CancellationToken ct = default);
    Task<IReadOnlyList<T>> GetAllAsync(CancellationToken ct = default);
    Task<IReadOnlyList<T>> FindAsync(ISpecification<T> spec, CancellationToken ct = default);
    Task<PageResult<T>> PaginateAsync(ISpecification<T> spec, int page, int pageSize, CancellationToken ct = default);
    Task<int> CountAsync(ISpecification<T> spec, CancellationToken ct = default);
}

Transactions

await db.TransactionAsync(async tx =>
{
    await tx.ExecuteAsync("UPDATE accounts SET balance = balance - 100 WHERE id = 1");
    await tx.ExecuteAsync("UPDATE accounts SET balance = balance + 100 WHERE id = 2");
});

Typed Results

DatabaseResult<User> result = await DatabaseResult<User>.Success(user, duration);
if (result.IsSuccess) { /* use result.Data */ }

PageResult<Order> page = new()
{
    Items = orders,
    TotalCount = 100,
    Page = 1,
    PageSize = 20,
};

Architecture

Hellnet.Database
├── Abstractions/          ← Pure contracts (no Npgsql dependency)
│   ├── IDatabaseExecutor       Query, Execute, Scalar
│   ├── IDatabaseTransaction    Begin/Commit/Rollback
│   ├── IRepository<T>          Generic repository
│   ├── ISpecification<T>       Query specification
│   ├── DatabaseResult<T>       Typed result wrapper
│   └── PageResult<T>           Paginated result
├── Configuration/         ← Env-first (HELLNET_DATABASE_*)
│   ├── HellnetDatabaseOptions   Individual host/port/user/pass
│   └── DatabaseEnvBinder        Reads env vars, builds connection string
├── PostgreSql/            ← Npgsql implementation
│   ├── PostgresConnectionFactory  NpgsqlDataSource wrapper
│   ├── NpgsqlExecutor             Dapper-based executor
│   ├── NpgsqlTransaction          Transaction support
│   └── PostgresRepository<T>      Repository implementation
└── Resilience/            ← Polly retry with error discrimination
    └── DatabaseRetryPolicy

Package structure (future)

Hellnet.Database.Abstractions      → Contracts only (no Npgsql)
Hellnet.Database.PostgreSql        → PostgreSQL implementation
Hellnet.Database.Resilience        → Polly retry policies
Hellnet.Database.SqlServer         → (future)
Hellnet.Database.MySql             → (future)
Hellnet.Database.Testing           → (future)

Observability

This library provides infrastructure only. Observability (metrics, tracing, health checks, logging) is delegated to Hellnet.Observability.

To instrument database calls:

• Use OpenTelemetry's Npgsql instrumentation to capture query duration, errors, and connection pool metrics
• Hellnet.Observability handles OTel setup automatically

Configuration precedence

Environment Variables  ← highest priority
IConfiguration
HellnetDatabaseOptions
Default values         ← lowest priority

License

Apache 2.0 — see LICENSE.

Related repos