https://github.com/marcelo-mattos/hydrix
Hydrix is a minimal ORM for .NET designed for developers who prefer full control over their SQL, offering fast, predictable, and transparent object hydration.
https://github.com/marcelo-mattos/hydrix
ado-net hydration hydrix materializer micro-orm sql
Last synced: 10 days ago
JSON representation
Hydrix is a minimal ORM for .NET designed for developers who prefer full control over their SQL, offering fast, predictable, and transparent object hydration.
- Host: GitHub
- URL: https://github.com/marcelo-mattos/hydrix
- Owner: marcelo-mattos
- License: apache-2.0
- Created: 2025-12-17T22:58:57.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-01-03T04:59:58.000Z (2 months ago)
- Last Synced: 2026-01-04T22:50:22.683Z (2 months ago)
- Topics: ado-net, hydration, hydrix, materializer, micro-orm, sql
- Language: C#
- Homepage:
- Size: 1.14 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Roadmap: ROADMAP.md
- Notice: NOTICE
Awesome Lists containing this project
README
# Hydrix
[](https://sonarcloud.io/summary/new_code?id=marcelo-mattos_hydrix)
⚡**A high-performance, lightweight, provider-agnostic SQL materializer for .NET.**
Hydrix is a **micro-ORM** built for developers who demand:
- Full control over SQL execution
- Explicit and predictable behavior
- High performance without hidden abstractions
- Efficient hierarchical entity materialization
It intentionally sits between **raw [ADO.NET](https://learn.microsoft.com/pt-br/dotnet/framework/data/adonet/ado-net-overview)** and heavyweight ORMs such as Entity Framework, offering a Dapper-like experience enhanced with:
- Nested entity materialization
- Intelligent metadata caching
- Optimized enum handling
- Zero reflection in the hot path
---
## 🧭 Why Hydrix?
Hydrix is designed for performance-sensitive systems where:
* * SQL must remain explicit and visible
* Developers retain full control over execution
* Behavior must be predictable and transparent
* Object graphs must be materialized efficiently from flat JOINs
Hydrix does not attempt to abstract SQL away from you.
---
## ⚠️ What Hydrix is not?
* A LINQ provider
* An automatic SQL generator
* An entity tracking or state management framework
---
## ⚙️ Supported frameworks
* .NET Core 3.1
* .NET 6
* .NET 8
* .NET 10
---
## ✨ Key Features
* Explicit SQL execution (Text and Stored Procedures)
* Entity materialization via standard .NET DataAnnotations
* Nested entity support (flat JOIN → object graph)
* Thread-safe metadata caching
* Zero reflection in the materialization hot path
* Compiled enum converters (no `Enum.ToObject` per row)
* Native SQL `IN` clause expansion
* SQL command logging
* Fully provider-agnostic ([ADO.NET](https://learn.microsoft.com/pt-br/dotnet/framework/data/adonet/ado-net-overview))
* Zero external dependencies
* Apache 2.0 licensed
## ⚡ Performance Design (Hydrix 2.0)
* Hydrix 2.0 introduces architectural improvements focused on runtime efficiency:
* Metadata is built once per type and cached
* Property setters are compiled into delegates
* Enum conversions use compiled converters
* No reflection during row materialization
* No `Activator.CreateInstance` in hot paths
* No `Enum.ToObject` in hot paths
* Minimal allocations during nested resolution
Hydrix is engineered for predictable runtime behavior and low GC pressure.
---
## 📦 Installation
```bash
dotnet add package Hydrix
```
---
## 🚀 Basic Usage
### Executing SQL Commands
```csharp
hydrix.ExecuteNonQuery(
"INSERT INTO orders (id, total) VALUES (@id, @total)",
new
{
id = Guid.NewGuid(),
total = 150.75m
}
);
```
---
### Querying Entities
```csharp
var orders = hydrix.Query(
"SELECT id, total FROM orders WHERE total > @min",
new { min = 100 }
);
```
---
### Native `IN` Clause Support
```csharp
var orders = hydrix.Query(
"SELECT * FROM orders WHERE id IN (@ids)",
new
{
ids = new[] { id1, id2, id3 }
}
);
```
Hydrix automatically expands:
```sql
WHERE id IN (@ids_0, @ids_1, @ids_2)
```
Each value is safely parameterized.
---
## 🧱 Defining Entities
### Simple Entity
```csharp
using System.ComponentModel.DataAnnotations.Schema;
[Table("orders", Schema = "pos")]
public class Order :
DatabaseEntity, ITable
{
[Key, DatabaseGenerated(DatabaseGeneratedOption.None)]
[Column("id")]
public Guid Id { get; set; }
[Column("total")]
public decimal Total { get; set; }
}
```
---
### Nested Entities (Flat JOINs)
```csharp
[Table("orders", Schema = "pos")]
public class Order :
DatabaseEntity, ITable
{
[Key, DatabaseGenerated(DatabaseGeneratedOption.None)]
[Column("id")]
public Guid Id { get; set; }
[ForeignKey("CustomerId")]
[Column("customerId")]
public Guid? CustomerId { get; set; }
[ForeignTable("customer", Schema = "pos", PrimaryKeys = new[] { "Id" }, ForeignKeys = new[] { "CustomerId" })]
public Customer Customer { get; set; }
}
```
Hydrix only materializes nested entities when related data is present, preventing empty object creation in LEFT JOIN scenarios.
---
### Stored Procedures
```csharp
[Procedure("sp_create_order", Schema = "pos")]
public class CreateOrder :
DatabaseEntity, IProcedure
{
[Parameter("p_id", DbType.Guid)]
public Guid Id { get; set; }
[Parameter("p_total", DbType.Decimal)]
public decimal Total { get; set; }
}
```
---
## 🔄 Transactions
```csharp
hydrix.OpenConnection();
hydrix.BeginTransaction(IsolationLevel.ReadCommitted);
try
{
await hydrix.ExecuteNonQueryAsync(...);
await hydrix.ExecuteNonQueryAsync(...);
hydrix.CommitTransaction();
}
catch
{
hydrix.RollbackTransaction();
throw;
}
```
---
## 📝 SQL Command Logging
```
Executing DbCommand
SELECT * FROM orders WHERE id IN (@ids_0, @ids_1)
Parameters:
@ids_0 = 'a3f9...' (Guid)
@ids_1 = 'b4c1...' (Guid)
```
---
## 🧩 Provider Compatibility
Hydrix works with any ADO.NET-compatible provider:
* SQL Server
* PostgreSQL
* MySQL
* Oracle
* Others
---
## 🎯 Design Philosophy
Hydrix is built around the following principles:
* Explicit SQL
* Deterministic behavior
* Performance first
* No hidden abstractions
* [ADO.NET](https://learn.microsoft.com/pt-br/dotnet/framework/data/adonet/ado-net-overview) as a solid foundation
---
## ❤️ Supporting Hydrix
Hydrix is an open-source project built and maintained with care, transparency, and a long-term vision.
If Hydrix helps you build reliable, predictable, and high-performance data access layers, consider supporting the project. Your support helps ensure ongoing maintenance, improvements, documentation, and long-term sustainability.
You can support Hydrix through GitHub Sponsors:
👉 https://github.com/sponsors/marcelo-mattos
Every contribution, whether financial or by sharing feedback and usage experiences, is deeply appreciated.
---
## 📄 License
This project is licensed under the Apache License 2.0.
See the LICENSE and NOTICE files for details.
---
## 👨💻 Author
**Marcelo Matos dos Santos**
Software Engineer • Open Source Maintainer.
Engineering clarity. Delivering transformation.