TeaQL.Sql 0.2.6

TeaQL .NET SDK

TeaQL .NET SDK is the C#/.NET implementation of the TeaQL framework, designed to bring the highly abstract, efficient, and robust data modeling and SQL execution engine to the modern .NET ecosystem.

Recommended Agent Harness

When building database-backed applications with the TeaQL .NET runtime, we recommend using it together with the TeaQL Agent Kit. The Agent Kit is TeaQL's continuously evolving Harness Engineering method. It gives coding agents a model-mediated, executable workflow for domain modeling, deterministic evaluation and repair, code generation, implementation, and evidence-based verification as the generator and runtimes evolve.

1. Minimum Version Requirements

• .NET SDK: .NET 8.0+ (C# 12+)
• (Optional) Third-party Services: Redis (For CacheIntegration Module), Sqlite/PostgreSQL/MySQL (For Data Providers)

2. Tests Performed

This project incorporates a comprehensive unit testing suite, having successfully completed the following verifications:

• ✅ TeaQL.Core Tests: Includes ValueTests (base types and nullability evaluation), EntityGraphTests (creation and deletion of nodes and relationships), SelectQueryTests (query conditions and AST composition), and SafeExpressionTests & EvalTests (expression evaluation and safe execution).
• ✅ Entity Abstraction & Metadata Tests: Validated metadata behaviors via DescriptorsTests and TimestampTests.
• ✅ Fundamental Data Structure Tests: Tested boundary conditions for custom data structures like SmartListTests and TrimmedStringConverterTests.
• ✅ Cross-Language API Parity: API signatures are heavily inspired by best practices from the Rust, Golang, and Python equivalents, specifically adapted and aligned for .NET features.

3. Available Modules

To ensure high extensibility and dependency isolation, this project adopts a multi-project architecture:

• TeaQL.Core: Foundational core structures (Entity Metadata, Value, AST node abstractions, etc.).
• TeaQL.DataService: Platform-agnostic data service contract abstraction layer (e.g., QueryRequest, QueryResult).
• TeaQL.Sql: SQL compilation and execution engine (SqlDialect, SqlDataServiceExecutor).
• TeaQL.Runtime: Application runtime context handling (UserContext, RuntimeModule).
• TeaQL.Provider.*: Physical transport implementation modules for various relational databases (Sqlite, PostgreSql, MySql).
• TeaQL.CacheIntegration.Redis: Transparent distributed cache provider extension.
• TeaQL.WebIntegration.AspNetCore: Seamless web interface integration and endpoint mounting middleware tailored for ASP.NET Core environments.

4. Features

• Core Architecture: Provides a strong-typing system mapping mechanism based on the Value wrapper type, completely eliminating boxing/unboxing overheads and cross-database NULL handling issues, alongside a robust Entity Descriptor modeling system.
• SQL Dialect Generator: Highly secure SQL AST construction that dynamically translates into native parameterized SQL queries/commands for Sqlite, Postgres, and MySQL, inherently preventing SQL injection.
• Unified Runtime Context: A centralized UserContext runtime that natively supports chained storage propagation and dependency injection, ensuring environment variables seamlessly pass through various services alongside the request.
• ASP.NET Core Web Endpoint: Integrates instantly with Microsoft.AspNetCore.Builder, exposing underlying abstract data services as RESTful endpoints with just a few lines of code.
• Redis Cache Decorator: The RedisDataServiceDecorator enables transparent, underlying distributed caching for data interactions out-of-the-box.

Quick Start

Local dynamic-search schema drift

TeaQL.Core.DynamicSearch.Normalize validates a local UI search envelope such as {"filter":{"name":{"$contains":"Campus"}},"orderBy":[{"field":"id","direction":"desc"}]} against application-owned SearchModel metadata. Unknown fields or relation paths remove the whole clause and return DYNAMIC_SEARCH_UNKNOWN_FIELD warnings (entity, clause and field path, never the submitted value). Warnings also go to stderr by default; pass a callback to integrate structured logging.

DynamicSearch.Merge accepts an already-scoped SelectQuery and trusted filter/order bindings that produce native Expr/OrderBy objects. It clones the query, ANDs filters and appends ordering, retaining existing filters, hard limit, pagination and intent. Bindings must enforce related-query authorization too. Warnings are emitted only after all validation and bindings succeed.

Supported scalar metadata types are string, integer, number, boolean, date (yyyy-MM-dd), timestamp (integer epoch milliseconds), and decimal (use a string for exact decimal digits). Operators are $eq, $ne, $gt, $gte, $lt, $lte, $in, $notIn, and string $contains. The default limit is 100 filter/order clauses, 16 path segments and 1,000 IN-list values. Invalid operators/types, malformed JSON and client-supplied trusted controls remain errors. TFP validation is unchanged. Generated automatic bindings are not supplied by this adapter; do not use it as an authorization policy.

Regression evidence lives in DynamicSearchTests and SqliteTransportTests.DynamicSearchKeepsOuterAndNestedTenantScopesWithUnknownClauses.

Build and test

The solution is natively built for .NET 8. You can build and test using the .NET CLI:

dotnet build TeaQL.sln
dotnet test src/TeaQL.Core.Tests/TeaQL.Core.Tests.csproj