SharpCoreDB.Data.Provider 1.1.0

<div align="center"> <img src="https://raw.githubusercontent.com/MPCoreDeveloper/SharpCoreDB/master/SharpCoreDB.jpg" alt="SharpCoreDB Logo" width="200"/>

SharpCoreDB.Data.Provider

ADO.NET Data Provider for SharpCoreDB

</div>

Overview

Complete ADO.NET Data Provider for SharpCoreDB — a high-performance encrypted embedded database engine. Use the familiar DbConnection / DbCommand / DbDataReader APIs with SharpCoreDB's AES-256-GCM encryption, SIMD acceleration, and zero-config deployment.

Features

Installation

dotnet add package SharpCoreDB.Data.Provider

Requirements: .NET 10.0 or later.

Connection String

Examples:

Path=C:\data\mydb.scdb;Password=StrongPassword!
Data Source=./mydb.scdb;Password=secret;ReadOnly=true
Path=/var/lib/myapp/data.scdb;Password=s3cur3;Cache=Shared

Connection String Builder

var builder = new SharpCoreDBConnectionStringBuilder
{
    Path = @"C:\data\mydb.scdb",
    Password = "StrongPassword!",
    ReadOnly = false,
    Cache = "Private"
};

string connStr = builder.ConnectionString;
// "Path=C:\data\mydb.scdb;Password=StrongPassword!;ReadOnly=False;Cache=Private"

Quick Start

Open a Connection and Execute Queries

using SharpCoreDB.Data.Provider;

const string connectionString = "Path=./mydb.scdb;Password=StrongPassword!";

using var connection = new SharpCoreDBConnection(connectionString);
connection.Open();

using var command = connection.CreateCommand();

// Create a table
command.CommandText = "CREATE TABLE users (id INT, name TEXT, age INT)";
command.ExecuteNonQuery();

// Insert data
command.CommandText = "INSERT INTO users VALUES (1, 'Alice', 30)";
command.ExecuteNonQuery();

// Query data
command.CommandText = "SELECT * FROM users";
using var reader = command.ExecuteReader();
while (reader.Read())
{
    Console.WriteLine($"ID={reader.GetInt32(0)}, Name={reader.GetString(1)}, Age={reader.GetInt32(2)}");
}

Async Usage

using SharpCoreDB.Data.Provider;

const string connectionString = "Path=./mydb.scdb;Password=StrongPassword!";

await using var connection = new SharpCoreDBConnection(connectionString);
await connection.OpenAsync();

await using var command = new SharpCoreDBCommand("SELECT COUNT(*) FROM users", connection);
var count = await command.ExecuteScalarAsync();

Console.WriteLine($"Total users: {count}");

Parameterized Queries

Use named parameters prefixed with @ to prevent SQL injection:

using var command = new SharpCoreDBCommand(
    "INSERT INTO users VALUES (@id, @name, @age)", connection);

command.Parameters.Add("@id", 2);
command.Parameters.Add("@name", "Bob");
command.Parameters.Add("@age", 25);

command.ExecuteNonQuery();

Or use SharpCoreDBParameter for explicit type control:

command.Parameters.Add(new SharpCoreDBParameter("@salary", DbType.Decimal) { Value = 75000.00m });

Supported DbType mappings: Int32, Int64, String, Boolean, DateTime, Decimal, Double, Single, Guid, Binary, and ULID (stored as 26-character string).

Transactions

Transactions are backed by SharpCoreDB's batch update mechanism. When the transaction is committed, all deferred index rebuilds and WAL flushes are performed atomically:

using var connection = new SharpCoreDBConnection(connectionString);
connection.Open();

using var transaction = connection.BeginTransaction();

try
{
    using var cmd = new SharpCoreDBCommand(connection: connection)
    {
        Transaction = (SharpCoreDBTransaction)transaction
    };

    cmd.CommandText = "INSERT INTO accounts VALUES (1, 'Savings', 10000)";
    cmd.ExecuteNonQuery();

    cmd.CommandText = "INSERT INTO accounts VALUES (2, 'Checking', 5000)";
    cmd.ExecuteNonQuery();

    transaction.Commit();
}
catch
{
    transaction.Rollback();
    throw;
}

Note: If a transaction is disposed without Commit(), it is automatically rolled back.

DbProviderFactory

Register the provider for use with tooling that relies on DbProviderFactory:

using System.Data.Common;
using SharpCoreDB.Data.Provider;

// Register once at startup
DbProviderFactories.RegisterFactory(
    "SharpCoreDB.Data.Provider",
    SharpCoreDBProviderFactory.Instance);

// Resolve via factory name
var factory = DbProviderFactories.GetFactory("SharpCoreDB.Data.Provider");
using var connection = factory.CreateConnection()!;
connection.ConnectionString = "Path=./mydb.scdb;Password=StrongPassword!";
connection.Open();

Dependency Injection

Basic Registration

using SharpCoreDB.Data.Provider;

var builder = WebApplication.CreateBuilder(args);

// Register the provider factory
builder.Services.AddSharpCoreDBDataProvider();

Registration with Default Connection String

builder.Services.AddSharpCoreDBDataProvider(
    "Path=./mydb.scdb;Password=StrongPassword!");

This registers:

• DbProviderFactory as SharpCoreDBProviderFactory
• SharpCoreDBConnection (transient) pre-configured with the connection string
• DbConnection resolving to SharpCoreDBConnection

Inject in a Service

public class UserRepository(SharpCoreDBConnection connection)
{
    public async Task<int> GetUserCountAsync(CancellationToken ct = default)
    {
        await connection.OpenAsync(ct);

        await using var cmd = new SharpCoreDBCommand("SELECT COUNT(*) FROM users", connection);
        var result = await cmd.ExecuteScalarAsync(ct);

        return Convert.ToInt32(result);
    }
}

Schema Discovery

Query table and column metadata through standard ADO.NET schema APIs:

using var connection = new SharpCoreDBConnection(connectionString);
connection.Open();

// List tables
var tables = connection.GetSchema("Tables");
foreach (DataRow row in tables.Rows)
{
    Console.WriteLine($"Table: {row["TABLE_NAME"]}, Type: {row["TABLE_TYPE"]}");
}

// List columns for a specific table
var columns = connection.GetSchema("Columns", ["users"]);
foreach (DataRow row in columns.Rows)
{
    Console.WriteLine($"  {row["COLUMN_NAME"]} ({row["DATA_TYPE"]})");
}

Supported schema collections: MetaDataCollections, Tables, Columns.

DataAdapter / DataSet

Fill a DataTable or DataSet using the standard adapter pattern:

using var adapter = new SharpCoreDBDataAdapter(
    "SELECT * FROM users", connection);

var dataTable = new DataTable();
adapter.Fill(dataTable);

foreach (DataRow row in dataTable.Rows)
{
    Console.WriteLine($"{row["name"]} — age {row["age"]}");
}

Auto-generate INSERT/UPDATE/DELETE commands with SharpCoreDBCommandBuilder:

using var adapter = new SharpCoreDBDataAdapter("SELECT * FROM users", connection);
using var builder = new SharpCoreDBCommandBuilder(adapter);

// builder.GetInsertCommand(), builder.GetUpdateCommand(), etc.

Advanced: Direct Database Access

For scenarios that need access to the underlying engine (compiled queries, VACUUM, storage statistics):

using var connection = new SharpCoreDBConnection(connectionString);
connection.Open();

// Access the IDatabase instance
var db = connection.DbInstance!;

// Compiled query for hot paths (5-10x faster)
var stmt = db.Prepare("SELECT * FROM users WHERE age > @age");
var results = db.ExecuteCompiledQuery(stmt, new() { ["age"] = 25 });

// VACUUM
var vacuumResult = await db.VacuumAsync(VacuumMode.Quick);

// Storage statistics
var stats = db.GetStorageStatistics();
Console.WriteLine($"Database size: {stats.TotalSizeBytes} bytes");

Connection Pooling

The provider includes built-in instance pooling. Multiple SharpCoreDBConnection objects sharing the same connection string will reuse a single database instance, preventing file-locking issues:

Connection A ─┐
              ├─► Pooled IDatabase instance (ref count = 3)
Connection B ─┤
              │
Connection C ─┘

When the last connection is closed, the instance is flushed, saved, and disposed.

Call SharpCoreDBInstancePool.Instance.Clear() during application shutdown to force-release all pooled instances:

// In Program.cs or a hosted service shutdown handler
SharpCoreDBInstancePool.Instance.Clear();

Class Reference

Performance

The provider inherits SharpCoreDB's performance characteristics:

• 345× faster analytics than LiteDB with SIMD vectorization
• 11.5× faster than SQLite for aggregations
• AES-256-GCM encryption with near-zero overhead
• B-tree indexes for O(log n) range queries
• Compiled queries for 5-10× faster repeated execution

For detailed benchmarks, see the main repository.

License

MIT License — see LICENSE for details.

Contributing

Contributions are welcome! Please see the contributing guidelines.

Support

• GitHub Issues
• Documentation