Hellnet.Database 1.1.2

Hellnet.Database

Biblioteca de infraestrutura de banco de dados PostgreSQL-first para .NET. Configuração via environment variables, modular, cloud-native.

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

Instalação

dotnet add package Hellnet.Database

Configuração

Via environment variables (recomendado)

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

builder.Services.AddHellnetDatabase();

Via options explícitas

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

Uso

IDatabaseExecutor — SQL puro com Dapper

public class OrderService
{
    private readonly IDatabaseExecutor _db;

    public OrderService(IDatabaseExecutor db) => _db = db;

    // Query
    public async Task<IReadOnlyList<Order>> GetPendingAsync()
        => await _db.QueryAsync<Order>(
            "SELECT * FROM orders WHERE status = @Status",
            new { Status = "pending" });

    // Single row
    public async Task<Order?> GetByIdAsync(int id)
        => await _db.QueryFirstOrDefaultAsync<Order>(
            "SELECT * FROM orders WHERE id = @Id", new { Id = id });

    // Execute (insert/update/delete)
    public async Task<int> UpdateStatusAsync(int id, string status)
        => await _db.ExecuteAsync(
            "UPDATE orders SET status = @Status WHERE id = @Id",
            new { Id = id, Status = status });

    // Scalar
    public async Task<int> CountAsync()
        => await _db.ExecuteScalarAsync<int>(
            "SELECT COUNT(*) FROM orders");
}

Transações

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");
});
// Commit automático. Se exception → rollback automático.

Repository Pattern

public class ProductService
{
    private readonly IRepository<Product> _products;

    public ProductService(IRepository<Product> products) => _products = products;

    public async Task<Product?> GetAsync(int id) => await _products.GetByIdAsync(id);

    public async Task<IReadOnlyList<Product>> SearchAsync(ProductSpec spec)
        => await _products.FindAsync(spec);
}

public sealed class ProductSpec(string term) : ISpecification<Product>
{
    public string Sql => "SELECT * FROM products WHERE name ILIKE @Term";
    public object? Parameters => new { Term = $"%{term}%" };
    public string? OrderBy => null;
}

Resultados tipados

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

Variáveis de Ambiente

Resiliência (Polly)

Retry automático com exponential backoff. Erros permanentes não são retentados:

Desabilitar por env:

export HELLNET_DATABASE_RETRY_ENABLED=false

Arquitetura

Hellnet.Database
├── Abstractions
│   ├── IDatabaseExecutor       ← QueryAsync, ExecuteAsync, Scalar
│   ├── IDatabaseTransaction    ← Begin/Commit/Rollback
│   ├── IDatabaseConnectionFactory ← Factory pattern
│   ├── IRepository<T>          ← CRUD genérico
│   ├── ISpecification<T>       ← Query filters
│   ├── DatabaseResult<T>       ← Typed result
│   └── PageResult<T>           ← Paginated result
├── Configuration
│   ├── HellnetDatabaseOptions  ← Options imutáveis (init)
│   └── DatabaseEnvBinder       ← Env-first reader
├── PostgreSql
│   ├── PostgresConnectionFactory  ← NpgsqlDataSource
│   ├── NpgsqlExecutor             ← Dapper
│   ├── NpgsqlTransaction          ← Transaction
│   └── PostgresRepository<T>      ← Repository implementation
└── Resilience
    └── DatabaseRetryPolicy     ← Polly + SQL state discrimination

Observabilidade

Hellnet.Database não possui instrumentação própria. Use os pacotes OpenTelemetry padrão:

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddNpgsql())
    .WithMetrics(m => m.AddNpgsqlInstrumentation());

Health checks e logging são delegados ao Hellnet.Observability.

Repositórios Relacionados

Licença

Apache 2.0 © 2026 Hellnet