CosmoSQLClient

A lightweight, high-performance database client library for .NET designed for low-latency, high-throughput applications. CosmoSQLClient provides a unified interface for multiple database engines while minimizing memory allocations and binary footprint.

NuGet Packages

Package	NuGet
CosmoSQLClient.Core
CosmoSQLClient.MsSql
CosmoSQLClient.Postgres
CosmoSQLClient.MySql
CosmoSQLClient.Sqlite
CosmoSQLClient.MsSql.EntityFrameworkCore
CosmoSQLClient.Postgres.EntityFrameworkCore
CosmoSQLClient.MySql.EntityFrameworkCore
CosmoSQLClient.Sqlite.EntityFrameworkCore

Key Features

• High-Performance Pipeline Architecture: Built on top of System.IO.Pipelines for efficient asynchronous I/O and protocol decoding.
• Zero-Allocation Row Decoding: Employs a strictly-constrained generic pipeline and struct-based token handlers to eliminate boxing and reduce heap pressure.
• Native Streaming: Supports IAsyncEnumerable for row-by-row processing, ideal for large datasets and reactive streams.
• Lightweight Footprint: Core library and providers are significantly smaller than standard ADO.NET implementations (e.g., MSSQL provider is ~207KB vs ~17MB for Microsoft.Data.SqlClient).
• Unified API: Shared ISqlDatabase interface across all supported engines (MSSQL, PostgreSQL, MySQL, SQLite).
• Entity Framework Core Integration: Optional bridge packages let you use CosmoSQLClient connections with the standard EF Core relational providers for MSSQL, PostgreSQL, MySQL, and SQLite.
• Advanced JSON Support: Direct streaming of database results to JSON (NDJSON/JSON array) with minimal buffering.

Supported Database Engines

Engine	Protocol	Supported Features
MSSQL	TDS 7.x	Integrated Security (NTLMv2), Stored Procedures, Transactions, Named Instances
PostgreSQL	Frontend/Backend 3.0	MD5/Scram-SHA-256 Auth, Transactions, Parameterized Queries
MySQL	MySQL Protocol 4.1+	Standard Auth, Transactions, Parameterized Queries
SQLite	Local File	Native engine integration, Online Backup, Transactions

Installation

Add the package for your specific database engine:

dotnet add package CosmoSQLClient.MsSql
dotnet add package CosmoSQLClient.Postgres
dotnet add package CosmoSQLClient.MySql
dotnet add package CosmoSQLClient.Sqlite

For Entity Framework Core integration, install the matching bridge package for your provider:

dotnet add package CosmoSQLClient.MsSql.EntityFrameworkCore
dotnet add package CosmoSQLClient.Postgres.EntityFrameworkCore
dotnet add package CosmoSQLClient.MySql.EntityFrameworkCore
dotnet add package CosmoSQLClient.Sqlite.EntityFrameworkCore

Provider package	EF Core bridge package	Extension method
CosmoSQLClient.MsSql	CosmoSQLClient.MsSql.EntityFrameworkCore	UseCosmoSqlServer(...)
CosmoSQLClient.Postgres	CosmoSQLClient.Postgres.EntityFrameworkCore	UseCosmoPostgres(...)
CosmoSQLClient.MySql	CosmoSQLClient.MySql.EntityFrameworkCore	UseCosmoMySql(...)
CosmoSQLClient.Sqlite	CosmoSQLClient.Sqlite.EntityFrameworkCore	UseCosmoSqlite(...)

Quick Start

Basic Query (MSSQL)

using CosmoSQLClient.MsSql;

var connStr = "Server=localhost;Database=Sales;User Id=sa;Password=your_password;";
await using var conn = await MsSqlConnection.OpenAsync(connStr);

await using var cmd = conn.CreateCommand("SELECT TOP 10 * FROM Invoices");
await using var reader = await cmd.ExecuteReaderAsync();

while (await reader.ReadAsync())
{
    var total = reader.GetDecimal("TotalAmount");
    Console.WriteLine($"Invoice Total: {total}");
}

Advanced Streaming (IAsyncEnumerable)

Rows are yielded as they arrive from the socket, ensuring the full result set is never buffered in memory.

await foreach (var row in conn.Advanced.QueryStreamAsync("SELECT * FROM LargeTable"))
{
    var id = row["Id"].AsInt32();
    // Process one row at a time
}

Entity Framework Core

CosmoSQLClient can be used as the underlying DbConnection for the standard EF Core relational providers. Install the matching EF Core bridge package, then configure your DbContext with the Cosmo-specific extension for that database.

using Microsoft.EntityFrameworkCore;

services.AddDbContext<AppDbContext>(options =>
    options.UseCosmoSqlServer("Server=localhost;Database=Sales;User Id=sa;Password=your_password;TrustServerCertificate=True;"));

services.AddDbContext<AppDbContext>(options =>
    options.UseCosmoPostgres("Host=localhost;Database=Sales;User Id=postgres;Password=your_password;"));

services.AddDbContext<AppDbContext>(options =>
    options.UseCosmoMySql(
        "Host=localhost;Database=Sales;User Id=root;Password=your_password;",
        new MySqlServerVersion(new Version(8, 0, 0))));

services.AddDbContext<AppDbContext>(options =>
    options.UseCosmoSqlite("Data Source=sales.db"));

Technical Architecture

Zero-Allocation Pipeline

CosmoSQLClient implements a generic protocol decoder (ProcessTokensAsync) using struct handlers. This architecture ensures:

• No Boxing: SqlRow and SqlValue types are never cast to object during decoding.
• JIT Devirtualization: The row-parsing path is inlined by the .NET JIT compiler, removing interface dispatch overhead.
• Minimal Heap Pressure: Bounded memory footprint regardless of result set size.

Package Size Comparison

CosmoSQLClient avoids heavy dependencies like Azure.Identity, MSAL, or Microsoft.Data.SqlClient.SNI.

Library	Published Footprint
CosmoSQLClient.MsSql	~207 KB
Microsoft.Data.SqlClient	~17 MB+

SqlValue Type Mapping

SqlValue is the universal cell type returned by advanced query methods. It wraps the raw wire value and provides typed accessors:

SqlValue Accessor	.NET Type
AsInt32() / AsInt64()	int / long
AsString()	string
AsDecimal()	decimal
AsDouble() / AsFloat()	double / float
AsBoolean()	bool
AsDateTime() / AsDateTimeOffset()	DateTime / DateTimeOffset
AsGuid()	Guid
AsBytes()	byte[]
IsNull	bool

Advanced Usage

Integrated Security (MSSQL)

Supports native NTLMv2 authentication for Windows/Linux environments without external dependencies.

var connStr = "Server=myserver;Integrated Security=SSPI;Trust Server Certificate=true;";
await using var conn = await MsSqlConnection.OpenAsync(connStr);

JSON Streaming

Stream query results directly to a PipeWriter or Stream as JSON with zero intermediate allocations.

await conn.Advanced.QueryJsonStreamAsync(
    "SELECT * FROM Users",
    pipeWriter,
    format: JsonOutputFormat.Array);

Stored Procedures (MSSQL)

var result = await conn.Advanced.ExecuteProcAsync("GetCustomerInvoices", new {
    CustomerId = 123,
    Year = 2024
});

Related Projects

• CosmoSQLClient-Swift — Swift NIO port of CosmoSQLClient with the same API design and wire-protocol implementations for server-side Swift.
• SQLClient-Swift — The original MSSQL driver using FreeTDS (predecessor to the Swift port).

License

Licensed under the MIT License.