Teclimit.Sql.Data.Materializer 4.0.0

Teclimit.Sql.Data.Materializer

A lightweight, explicit, and provider-agnostic SQL materialization framework for .NET.

Teclimit.Sql.Data.Materializer is a micro-ORM designed for developers who require full control over SQL execution, predictable behavior, and efficient entity materialization, without introducing hidden abstractions or proprietary query languages.

The framework intentionally sits between raw ADO.NET and heavyweight ORMs such as Entity Framework, offering a Dapper-like experience enhanced with hierarchical entity materialization, metadata caching, and native support for nested entities.

✨ Key Features

• Explicit SQL execution (Text and Stored Procedures)
• Automatic materialization of entities (ISqlEntity)
• Support for nested entities (flat JOINs → object graphs)
• Thread-safe metadata caching with optimized reflection
• Native support for SQL IN clauses with safe parameter expansion
• SQL command logging similar to Entity Framework
• Fully provider-agnostic (ADO.NET based)
• Compatible with .NET Core 3.1 and later
• Zero external dependencies
• Distributed under the MIT License

📦 Installation

dotnet add package Teclimit.Sql.Data.Materializer

🚀 Basic Usage

Executing SQL Commands

materializer.ExecuteNonQuery(
    "INSERT INTO orders (id, total) VALUES (@id, @total)",
    new
    {
        id = Guid.NewGuid(),
        total = 150.75m
    }
);

Querying Entities

var orders = materializer.Query<Order>(
    "SELECT id, total FROM orders WHERE total > @min",
    new { min = 100 }
);

Native IN Clause Support

var orders = materializer.Query<Order>(
    "SELECT * FROM orders WHERE id IN (@ids)",
    new
    {
        ids = new[] { id1, id2, id3 }
    }
);

The framework automatically expands the query into:

WHERE id IN (@ids_0, @ids_1, @ids_2)

Each value is bound as an individual parameter, ensuring safety and compatibility across providers.

🧱 Defining Entities

Simple Entity

[SqlEntity]
public class Order : ISqlEntity
{
    [SqlField]
    public Guid Id { get; set; }

    [SqlField]
    public decimal Total { get; set; }
}

Nested Entities (Flat JOINs)

[SqlEntity]
public class Order : ISqlEntity
{
    [SqlField]
    public Guid Id { get; set; }

    [SqlEntity(PrimaryKey = "Id")]
    public Customer Customer { get; set; }
}

The materializer automatically constructs the object graph when the related data is present, preventing the creation of empty nested objects when LEFT JOINs return null values.

🔄 Transactions

materializer.OpenConnection();
materializer.BeginTransaction(IsolationLevel.ReadCommitted);

try
{
    materializer.ExecuteNonQuery(...);
    materializer.ExecuteNonQuery(...);

    materializer.CommitTransaction();
}
catch
{
    materializer.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)
--------------------------------------------------

🎯 Design Philosophy

Teclimit.Sql.Data.Materializer is built around the following principles:

• SQL should remain explicit and visible
• Developers must retain full control over execution
• No hidden behaviors or implicit query generation
• Performance, predictability, and transparency over convenience
• ADO.NET as a solid and proven foundation

🧩 Provider Compatibility

• Microsoft SQL Server
• PostgreSQL
• MySQL
• Oracle
• Any ADO.NET-compatible data provider

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE and NOTICE files for details.

👨‍💻 Author

Marcelo Matos - TecLimit Digital Solutions®