CSharpDB.Data 3.1.2

CSharpDB.Data

ADO.NET provider for the CSharpDB embedded database engine. Standard DbConnection, DbCommand, and DbDataReader with parameterized queries and transactions.

Overview

CSharpDB.Data provides a standard System.Data.Common (ADO.NET) data provider for CSharpDB. Use familiar DbConnection/DbCommand/DbDataReader patterns to query and modify your database. Supports parameterized queries, transactions, prepared statements, prepared-template caching, schema introspection, embedded file-backed and in-memory connection modes, and daemon-backed remote connections over the CSharpDB.Daemon gRPC host.

Key Types

Usage

using CSharpDB.Data;

// Open a connection
await using var connection = new CSharpDbConnection("Data Source=myapp.db");
await connection.OpenAsync();

// Create a table
await using var cmd = connection.CreateCommand();
cmd.CommandText = """
    CREATE TABLE products (
        id INTEGER PRIMARY KEY,
        name TEXT,
        price REAL
    )
    """;
await cmd.ExecuteNonQueryAsync();

// Insert with parameters
cmd.CommandText = "INSERT INTO products VALUES (@id, @name, @price)";
cmd.Parameters.AddWithValue("@id", 1);
cmd.Parameters.AddWithValue("@name", "Widget");
cmd.Parameters.AddWithValue("@price", 9.99);
await cmd.ExecuteNonQueryAsync();

// Query with a data reader
cmd.CommandText = "SELECT name, price FROM products WHERE price < @max";
cmd.Parameters.Clear();
cmd.Parameters.AddWithValue("@max", 50.0);

await using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    Console.WriteLine($"{reader.GetString(0)}: ${reader.GetDouble(1):F2}");
}

// Transactions
await using var tx = await connection.BeginTransactionAsync();
cmd.Transaction = (CSharpDbTransaction)tx;
cmd.CommandText = "INSERT INTO products VALUES (2, 'Gadget', 19.99)";
await cmd.ExecuteNonQueryAsync();
await tx.CommitAsync();

// Save an in-memory connection back to disk
await connection.SaveToFileAsync("products.db");

// Schema introspection
var csConn = (CSharpDbConnection)connection;
var tables = csConn.GetTableNames();
var schema = csConn.GetTableSchema("products");

Using DbProviderFactory

var factory = CSharpDbFactory.Instance;
await using var conn = factory.CreateConnection();
conn.ConnectionString = "Data Source=myapp.db";
await conn.OpenAsync();

Daemon-Backed Connections

Use a remote transport connection string when you want ADO.NET to talk to a running CSharpDB.Daemon host instead of opening the database file directly:

await using var connection = new CSharpDbConnection(
    "Transport=Grpc;Endpoint=http://localhost:5000");
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) FROM products";
var count = (long)(await command.ExecuteScalarAsync() ?? 0L);

Connection-string rules:

• Embedded/direct mode: use Data Source=...
• Daemon-backed mode: use Transport=Grpc;Endpoint=http://...
• Data Source, Load From, and connection pooling are embedded-only options
• Endpoint requires an explicit Transport

For a daemon host, Grpc is the primary transport today:

Transport=Grpc;Endpoint=http://localhost:5000

That gives you standard ADO.NET commands and transactions against the daemon-managed database while keeping the existing embedded connection-string shape unchanged.

Transport guidance:

• Direct with Data Source=... is still faster than any network hop when the caller can open the database locally
• Grpc is the fastest supported network transport in the current CSharpDB stack
• NamedPipes is not implemented end to end today, so do not target it yet for daemon-backed ADO.NET
• for daemon-backed workloads, reuse open connections instead of reconnecting for each command

In-Memory Connection Strings

Data Source=:memory:

Creates a private in-memory database scoped to a single connection.

Data Source=:memory:shared-cache

Creates or attaches to a named shared in-memory database within the current process.

Data Source=:memory:shared-cache;Load From=seed.db

Seeds an in-memory database from seed.db on first open. For named shared memory, later opens must either omit Load From or use the same source path.

Named shared in-memory connections allow multiple live connections at once. One connection may own an explicit transaction at a time; other connections can still run reads against the last committed snapshot while that transaction is active.

Connection Pooling (Opt-In)

Connection pooling is disabled by default. Enable it explicitly in the connection string:

Data Source=myapp.db;Pooling=true;Max Pool Size=16

To force-release pooled physical connections (for example before deleting database files):

CSharpDbConnection.ClearPool("Data Source=myapp.db;Pooling=true;Max Pool Size=16");
CSharpDbConnection.ClearAllPools();

ClearPool and ClearAllPools also clear named shared in-memory hosts.

Installation

dotnet add package CSharpDB.Data

For the recommended all-in-one package:

dotnet add package CSharpDB

Dependencies

• CSharpDB.Engine - embedded database engine

Related Packages

License

MIT - see LICENSE for details.