C# Driver
High-performance .NET driver for Stoolap. Binds directly to libstoolap through source-generated [LibraryImport] P/Invoke (no C/C++ shim, no JNI layer). Ships with a full ADO.NET provider for drop-in use with System.Data.Common, Dapper, and anything that speaks DbConnection.
Targets .NET 8 and .NET 9. Supported platforms: macOS (arm64/x64), Linux (x64/arm64), Windows (x64).
Installation
dotnet add package Stoolap
Or in your project file:
<PackageReference Include="Stoolap" Version="0.5.0" />
Driver 0.5.0 is built on Stoolap engine 0.5.0. The package ships the native library for every supported platform under runtimes/<rid>/native/. Requires .NET 8 SDK or newer. To build from source instead, see Building from Source.
Native Library Loading
The driver searches for libstoolap.{dylib,so,dll} in this order. On Windows the native file is libstoolap.dll rather than stoolap.dll, so it cannot collide with the managed Stoolap.dll on the case-insensitive filesystem.
- Absolute path in the
STOOLAP_LIB_PATHenvironment variable. - The RID-specific folder
runtimes/<rid>/native/next to the running assembly. This is the canonical NuGet layout and is the resolver’s preferred location, both for packed-package consumers and for project-reference consumers (the build targets copy the host platform’s binary into this subfolder). - The assembly’s base directory next to
Stoolap.dll, where a RID-specific build or publish places it. - The OS loader search path (
LD_LIBRARY_PATH,DYLD_LIBRARY_PATH,PATH,/usr/local/lib, etc.).
export STOOLAP_LIB_PATH=/absolute/path/to/libstoolap.dylib
dotnet run
Resolution is wired through NativeLibrary.SetDllImportResolver so there is no platform-specific loader code in user projects.
Quick Start
using Stoolap;
using var db = Database.OpenInMemory();
db.Execute("""
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
email TEXT
)
""");
db.Execute("INSERT INTO users (id, name, email) VALUES (?, ?, ?)",
1, "Alice", "alice@example.com");
var result = db.Query("SELECT id, name, email FROM users ORDER BY id");
foreach (var row in result.Rows)
{
long id = (long)row[0]!;
string name = (string)row[1]!;
string? email = row[2] as string;
Console.WriteLine($"{id} {name} {email}");
}
Opening a Database
// In-memory (isolated, each call creates a new instance)
using var db = Database.OpenInMemory();
// In-memory via DSN (one engine per DSN string)
using var db = Database.Open("memory://");
// File-based (data persists across restarts)
using var db = Database.Open("file:///absolute/path/to/db");
Database.OpenInMemory() always returns a fresh engine. Database.Open(dsn) routes through a global DSN registry: opening a DSN that is already open gives a new session on the same engine, with its own transaction state, so two handles on memory:// see the same tables. For isolated in-memory databases, prefer OpenInMemory() or a unique DSN suffix like memory://test-{guid}.
Core API
| Method | Returns | Description |
|---|---|---|
Database.Open(dsn) |
Database |
Open a database by DSN |
Database.OpenInMemory() |
Database |
Open a fresh in-memory database |
Database.Version |
string |
Version of the underlying libstoolap |
db.Execute(sql) |
long |
Execute DDL/DML, returns rows affected |
db.Execute(sql, params) |
long |
Execute with positional parameters |
db.Query(sql) |
QueryResult |
Materialized query (one-call path) |
db.Query(sql, params) |
QueryResult |
Materialized parameterized query |
db.QueryStream(sql) |
Rows |
Streaming row reader |
db.QueryStream(sql, params) |
Rows |
Streaming parameterized query |
db.Prepare(sql) |
PreparedStatement |
Create a prepared statement |
db.Begin() |
Transaction |
Begin a transaction (READ COMMITTED) |
db.Begin(isolation) |
Transaction |
Begin with explicit isolation level |
db.Clone() |
Database |
Clone for multi-threaded use |
db.Dispose() |
void |
Close the database |
QueryResult vs Rows
The driver exposes two read paths so callers can pick per workload:
QueryResult. Fully materialized. Backed bystoolap_query_params_all/stoolap_stmt_query_all, which run the statement and pack the entire result set into one binary buffer in a single P/Invoke call, with no rows handle to open or close.BinaryRowParserthen decodes it in one pass. Use for small-to-medium result sets where the ergonomicrow[0]/result.ColumnsAPI is useful.Rows. Streaming reader. One P/Invoke call per row advance, per-cell accessors (GetInt64,GetString, etc.). Use for large result sets, LINQ-style iteration, or when you want to stop early.
// Materialized (one call, all rows decoded up-front)
var result = db.Query("SELECT id, name FROM users LIMIT 100");
foreach (var row in result.Rows)
{
Console.WriteLine(row[0]);
}
// Streaming (per-row iteration, no full materialization)
using var rows = db.QueryStream("SELECT id, name FROM users");
while (rows.Read())
{
long id = rows.GetInt64(0);
string? name = rows.GetString(1);
Console.WriteLine($"{id} {name}");
}
Parameters
Positional ? placeholders are the native parameter style:
db.Execute("INSERT INTO t VALUES (?, ?, ?)", 1, "hello", 3.14);
db.Query("SELECT * FROM t WHERE id = ? AND name = ?", 1, "hello");
Parameters are marshalled with zero heap allocations in the driver layer: a stack-allocated Span<StoolapValue> holds the FFI-ready values, and a stack-allocated 1 KiB byte* scratch buffer receives UTF-8 payloads for short string/blob parameters. Only oversized payloads fall back to Marshal.AllocHGlobal, which is freed at the end of the call.
Every placeholder needs a value: a missing one is an error, and so is mixing positional (?, $1) and named (:name) placeholders in one statement.
Supported parameter types: null / DBNull, bool, sbyte/byte/short/ushort/int/uint/long/ulong, float/double/decimal, string, DateTime/DateTimeOffset (as TIMESTAMP with nanosecond precision), byte[] / ReadOnlyMemory<byte> (as a VECTOR payload of packed little-endian float32 values; any other length is an error, since Stoolap has no byte BLOB type), float[] (as VECTOR), Guid (as TEXT).
Prepared Statements
using var db = Database.OpenInMemory();
db.Execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)");
using var insert = db.Prepare("INSERT INTO users VALUES (?, ?, ?)");
insert.Execute(1, "Alice", "alice@example.com");
insert.Execute(2, "Bob", "bob@example.com");
using var lookup = db.Prepare("SELECT * FROM users WHERE id = ?");
var result = lookup.Query(1);
Console.WriteLine(result[0, 1]); // "Alice"
Prepared statements cache the parsed AST on the Rust side, so every subsequent Execute/Query skips SQL parsing entirely. The C# side remembers the last result header of each statement and reuses its decoded column names while the header bytes stay the same; a schema change after Prepare produces a different header, which is decoded afresh.
PreparedStatement Methods
| Method | Returns | Description |
|---|---|---|
Execute(params) |
long |
Execute DDL/DML, returns rows affected |
Query(params) |
QueryResult |
Materialized query |
QueryStream(params) |
Rows |
Streaming query |
Sql |
string |
The SQL text used to prepare |
Dispose() |
void |
Finalize the native handle |
Transactions
using var db = Database.OpenInMemory();
db.Execute("CREATE TABLE accounts (id INTEGER, balance INTEGER)");
db.Execute("INSERT INTO accounts VALUES (1, 100)");
db.Execute("INSERT INTO accounts VALUES (2, 0)");
using (var tx = db.Begin())
{
tx.Execute("UPDATE accounts SET balance = balance - 50 WHERE id = 1");
tx.Execute("UPDATE accounts SET balance = balance + 50 WHERE id = 2");
tx.Commit();
}
// Disposing without Commit automatically rolls back.
Snapshot Isolation
// StoolapIsolationLevel lives in the Stoolap.Native namespace.
using (var tx = db.Begin(StoolapIsolationLevel.Snapshot))
{
// Sees a consistent view from the transaction's start point.
// Writes from other connections are invisible until commit.
var snapshot = tx.Query("SELECT * FROM t");
tx.Commit();
}
Prepared statements inside a transaction
using var stmt = db.Prepare("INSERT INTO t VALUES (?, ?)");
using var tx = db.Begin();
for (int i = 0; i < 1000; i++)
{
tx.Execute(stmt, i, $"row-{i}");
}
tx.Commit();
Transaction Methods
| Method | Returns | Description |
|---|---|---|
Execute(sql, params) |
long |
Execute DDL/DML |
Query(sql, params) |
QueryResult |
Materialized query (one-call path) |
QueryStream(sql, params) |
Rows |
Streaming row reader inside the transaction |
Execute(stmt, params) |
long |
Execute a prepared statement in this transaction |
Query(stmt, params) |
QueryResult |
Query a prepared statement in this transaction |
Commit() |
void |
Commit the transaction |
Rollback() |
void |
Rollback the transaction (idempotent) |
Dispose() |
void |
Auto-rollback if not committed |
A transaction keeps its database’s native handle alive until it commits, rolls back or is disposed, so disposing the Database first does not cut it off.
Multi-Threaded Use
A single Database instance owns one query executor and is intended to be used from a single thread at a time. For parallel workloads, call Clone() once per worker thread:
using var main = Database.Open("file:///var/data/mydb");
void Worker()
{
using var local = main.Clone(); // per-thread handle, shared engine
var r = local.Query("SELECT COUNT(*) FROM t");
Console.WriteLine(r[0, 0]);
}
var t1 = new Thread(Worker);
var t2 = new Thread(Worker);
t1.Start(); t2.Start();
t1.Join(); t2.Join();
Clones share the underlying engine (data, indexes, WAL) but each has its own executor and error state. Cloning is cheap.
Objects that come from a handle (Transaction, PreparedStatement, Rows, and the ADO.NET connection, command and reader) are not thread-safe either, but they are not tied to the thread that created them: using one from different threads one after another, for example across an await, is fine. A transaction that is never disposed is rolled back, and releases its connection, on the finalizer thread.
ADO.NET Provider
A full System.Data.Common implementation lives in the Stoolap.Ado namespace. Any library that accepts a DbConnection, like Dapper, LINQ to DB, Entity Framework Core (with an adapter), or custom code, works out of the box.
Connection String
| Keyword | Description |
|---|---|
Data Source |
DSN to pass to Database.Open (e.g. memory://, file:///path/to/db) |
DataSource |
Alias for Data Source |
DSN |
Alias for Data Source |
using Stoolap.Ado;
using var conn = new StoolapConnection("Data Source=file:///var/data/mydb");
conn.Open();
using var cmd = conn.CreateCommand();
cmd.CommandText = "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)";
cmd.ExecuteNonQuery();
Named Parameters
ADO.NET idiom is named parameters (@name, :name, $name). The command layer rewrites these into numbered placeholders ($1, $2, …), one per distinct name, before sending them to the engine, so a name used twice is one value (two anonymous ? are two different expressions in Stoolap 0.5). String literals, double-quoted and backtick-quoted identifiers, line/block comments and the :: cast operator are left alone. A command whose SQL names a parameter missing from its Parameters collection throws before it runs.
using var cmd = conn.CreateCommand();
cmd.CommandText = "INSERT INTO users VALUES (@id, @name)";
cmd.Parameters.Add(new StoolapParameter("@id", 1));
cmd.Parameters.Add(new StoolapParameter("@name", "Alice"));
cmd.ExecuteNonQuery();
using var read = conn.CreateCommand();
read.CommandText = "SELECT name FROM users WHERE id = @id";
read.Parameters.Add(new StoolapParameter("@id", 1));
var name = (string?)read.ExecuteScalar();
The leading sigil (@, :, or $) is stripped when ParameterName is normalized, so "@id" and "id" refer to the same parameter in the collection.
DataReader
using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT id, name FROM users ORDER BY id";
using var reader = cmd.ExecuteReader();
while (reader.Read())
{
long id = reader.GetInt64(0);
string name = reader.GetString(1);
Console.WriteLine($"{id} {name}");
}
StoolapDataReader wraps a streaming Rows handle, for connection-level and transaction-level commands alike: one P/Invoke call per Read and per-cell native accessors. ExecuteScalar uses the materialized one-call path.
Behaviour that ADO.NET consumers such as Dapper rely on:
- Column types are learned from the data. The engine reports each value’s type, not a result column’s declared type. The reader reads the first row when it opens, and when a column is NULL there it reads ahead (up to 64 rows, replayed in order) until every column has shown a value, so
GetFieldTypeis right before the firstReadeven when the first rows hold NULLs. A column that is NULL in all of those rows, and every column of an empty result, reportsobject. Dapper copes with that when a class property’s type is exactly the value’s type (long?,double?,string,DateTime?,bool?): an empty result maps to an empty list, and so doesQueryFirstOrDefault. Two cases still fail, because the engine does not report column types on its own: constructor mapping of a positionalrecordon an empty result, and a narrower property (such asint?for an INTEGER column) whose column’s first value comes after the first 64 rows. Prefer classes with exact property types for queries that can return no rows or long runs of NULLs. - Typed getters are strict.
GetInt64,GetStringand the other typed getters throwInvalidCastExceptionon a NULL value; checkIsDBNullor read the value withGetValue, which returnsDBNull.Value. A getter reads a value of its own type, and converts between INTEGER, FLOAT, BOOLEAN and numeric TEXT (GetStringalso formats numbers and booleans); any other conversion, such asGetStringon a TIMESTAMP orGetInt64on non-numeric TEXT, throwsInvalidCastException. An ordinal outside the result throwsIndexOutOfRangeException. RecordsAffectedis the number of rows a DML statement changed and -1 for a query, and stays readable after the reader is closed.- Closing the connection closes its open readers and rolls back its transactions that have not ended.
CommandBehavior.CloseConnectioncloses the connection when the reader closes. GetFieldValue<T>converts through the typed getters (GetFieldValue<int>works on an INTEGER column), andGetSchemaTabledescribes the result, soDataTable.Loadworks.- Not supported: a command returns one result set (
NextResultis always false, so Dapper’sQueryMultiplecannot be used);CommandTimeoutis not applied (set a per-connection limit with thequery_timeoutDSN key orPRAGMA query_timeout); aGuidis stored as TEXT, so Dapper needs a type handler (SqlMapper.AddTypeHandler) to map it back to aGuidproperty.
All standard accessors are implemented: GetInt32, GetInt64, GetString, GetDouble, GetBoolean, GetDateTime, GetFieldValue<T>, GetValues, IsDBNull, GetOrdinal, GetName, GetFieldType, GetSchemaTable, string indexer, integer indexer, NextResult.
Transactions via ADO.NET
using var conn = new StoolapConnection("Data Source=memory://test");
conn.Open();
using var tx = conn.BeginTransaction();
using (var cmd = conn.CreateCommand())
{
cmd.Transaction = tx;
cmd.CommandText = "INSERT INTO accounts VALUES (@id, @bal)";
cmd.Parameters.Add(new StoolapParameter("@id", 1));
cmd.Parameters.Add(new StoolapParameter("@bal", 100));
cmd.ExecuteNonQuery();
}
tx.Commit();
IsolationLevel.Snapshot and IsolationLevel.ReadCommitted are supported; IsolationLevel.Unspecified defaults to READ COMMITTED.
Dapper
using Stoolap.Ado;
using Dapper;
await using var conn = new StoolapConnection("Data Source=memory://");
conn.Open();
await conn.ExecuteAsync("""
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)
""");
await conn.ExecuteAsync(
"INSERT INTO users VALUES (@id, @name)",
new { id = 1, name = "Alice" });
var users = await conn.QueryAsync<User>(
"SELECT id, name FROM users WHERE id >= @min",
new { min = 1 });
record User(long Id, string Name);
The provider has no native async I/O: the async methods are the System.Data.Common defaults, which run synchronously on the calling thread and return a completed task.
Type Mapping
| .NET (write) | Stoolap | .NET (read) |
|---|---|---|
long, int, short, sbyte, byte, ushort, uint, ulong |
INTEGER |
long |
double, float, decimal |
FLOAT |
double |
string |
TEXT |
string |
bool |
BOOLEAN |
bool |
DateTime, DateTimeOffset |
TIMESTAMP (nanos UTC) |
DateTime (UTC) |
string (JSON) |
JSON |
string |
byte[], ReadOnlyMemory<byte> (packed little-endian f32, length a multiple of 4) |
VECTOR |
float[] |
float[] |
VECTOR |
float[] |
Guid |
TEXT (string form) |
string |
null, DBNull.Value |
NULL |
null |
enum |
INTEGER (underlying value) |
long |
char |
TEXT |
string |
Any other parameter type throws NotSupportedException rather than being stored in some string form. ulong values above long.MaxValue throw OverflowException, and DateTime values outside 1677-09-21 to 2262-04-11 (the range of an i64 nanosecond TIMESTAMP) throw ArgumentOutOfRangeException.
Aggregate results (SUM, AVG over integer columns) may be returned as long or double depending on the planner’s promotion rules. Use Convert.ToInt64 / Convert.ToDouble when reading aggregate output.
Performance
The driver is built around six performance principles:
- Source-generated P/Invoke. Every native entry point uses
[LibraryImport], which generates marshalling stubs at compile time instead of at JIT time. No per-call IL stubs, full AOT compatibility. - UTF-8 end to end. Stoolap is UTF-8 throughout, and
StringMarshalling.Utf8skips the UTF-16 round trip a plainDllImportwould force. - Zero-allocation parameter binding.
Span<StoolapValue>viastackallocholds FFI values on the stack, and a 1 KiBbyte*scratch buffer receives short UTF-8 payloads.[SkipLocalsInit]on the hot path avoids zeroing the scratch buffer. The driver itself allocates zero bytes per call; all per-call heap traffic is at the caller (theparams object?[]array, value-type boxes, and string interpolations). - One-call read path.
Query()onDatabase,TransactionandPreparedStatementissues one P/Invoke call:stoolap_query_params_all/stoolap_stmt_query_allrun the statement and pack the whole result into a buffer owned by the handle, so there is no rows handle to open, no second call to fetch, and nothing to free. The buffer is decoded in one pass over aReadOnlySpan<byte>. A prepared point lookup costs about a quarter less than the v0.4 open-fetch-close sequence. - Cached column headers. Each connection and prepared statement remembers the last result header and reuses its decoded column names when the next result has the same bytes.
SafeHandleeverywhere. Every opaque pointer (StoolapDB*,StoolapStmt*,StoolapRows*,StoolapTx*) is wrapped in aSafeHandlesubclass, so handles are freed on every exception path and during AppDomain teardown without leaking.
Running the Benchmark
The driver ships with benchmark/Stoolap.Benchmark.csproj, which runs a fixed set of operations against both Stoolap and Microsoft.Data.Sqlite on the same in-memory dataset. Run it yourself:
dotnet run --project benchmark/Stoolap.Benchmark.csproj -c Release
Error Handling
All driver errors surface as StoolapException, which extends Exception:
using Stoolap;
using var db = Database.OpenInMemory();
try
{
db.Execute("CREATE TABLE t (id INTEGER PRIMARY KEY)");
db.Execute("INSERT INTO t VALUES (1)");
db.Execute("INSERT INTO t VALUES (1)"); // duplicate PK
}
catch (StoolapException ex)
{
Console.Error.WriteLine($"Database error ({ex.StatusCode}): {ex.Message}");
}
Inside the ADO.NET layer, the same exception propagates through DbCommand.ExecuteNonQuery / ExecuteReader calls and can be caught directly as a StoolapException or as its base Exception.
Architecture
+------------------------------------------------------+
| Your .NET application |
+------------------------------------------------------+
| Stoolap.Ado.* (ADO.NET) | Stoolap.* (core) |
| +-- StoolapConnection | +-- Database |
| +-- StoolapCommand | +-- PreparedStatement |
| +-- StoolapDataReader | +-- Transaction |
| +-- StoolapParameter | +-- Rows / QueryResult |
| +-- NamedParameterRewriter| +-- ParameterBinder |
| +-- StoolapTransaction | +-- BinaryRowParser |
+------------------------------------------------------+
| Stoolap.Native (bindings internal; public enums) |
| +-- NativeMethods [LibraryImport] bindings |
| +-- StoolapValue [StructLayout] tagged union |
| +-- SafeHandle wrappers |
| +-- LibraryResolver (STOOLAP_LIB_PATH + RID lookup) |
+------------------------------------------------------+
|
| P/Invoke (stable C ABI)
v
+------------------------------------------------------+
| libstoolap.{dylib,so,dll} (Rust, --features ffi) |
| src/ffi/{database,statement,transaction,rows}.rs |
+------------------------------------------------------+
|
v
+------------------------------------------------------+
| stoolap crate (Rust) |
| MVCC, columnar indexes, volume storage, WAL |
+------------------------------------------------------+
Testing
The repository ships with a full xUnit suite across thirteen test files, covering both target frameworks (net8.0 and net9.0):
SmokeTests.cs. Open/close, execute, query, streaming, prepared statements, transactions, clone, NULL parameters.ParameterBinderTests.cs. Scratch-buffer fast path, HGlobal slow path, boundary cases, all primitive types, stackalloc capacity transitions.NamedParameterRewriterTests.cs.@/:/$sigils, string literals, escaped quotes, quoted identifiers, line/block comments, emails, duplicate names.ConnectionStringBuilderTests.cs.DataSourceround-trip,DSNalias normalization, indexer.CommandAndParameterTests.cs. Command lifecycle, parameter collection, named parameter rewriting, scalar/non-query execution, positional fallback, missing-parameter errors.DataReaderTests.cs.FieldCount,GetName/GetOrdinal, numeric getters,GetValues,IsDBNull,NextResult, empty result,GetFieldType, indexers.SqlFeatureTests.cs. Aggregates,GROUP BY,HAVING,ORDER BY,LIMIT/OFFSET,INNER/LEFT JOIN,DISTINCT,IN,LIKE, CTEs, subqueries,CASE,DROP TABLE.ErrorHandlingTests.cs. Invalid SQL, missing tables, duplicate tables, disposed objects, transaction-after-end, null arguments.TypeRoundTripTests.cs. Every Stoolap type through both the binary and streaming read paths, including 100 K-byte strings, Unicode payloads, timestamps, vectors, JSON, and NULL.AdoTests.cs. ADO.NET connection lifecycle, reader streaming, transaction rollback.FastPathTests.cs. One-call queries on every handle, the column header cache across schema changes, transaction reads of uncommitted writes, a transaction outliving itsDatabase, engine error messages, streaming every value type.AdoContractTests.cs. Dapper mapping with NULL-first rows, column type look-ahead, connection close andCloseConnection,RecordsAffected, ordinal and NULL errors,GetFieldValue,GetSchemaTable, parameter type rules.RegressionTests.cs. Driver-contract regressions:HasRowsaccuracy on empty results,GetFieldTypeschema stability beforeRead(), transaction-foreign-connection rejection, transactionalExecuteReaderstreaming behavior.
Run the full suite:
dotnet test -c Release
Building from Source
Requires:
- Rust (stable)
- .NET 8 SDK or newer
git clone https://github.com/stoolap/stoolap-csharp.git
cd stoolap-csharp
# Build the native library for the host platform.
# Auto-clones the stoolap engine at the pinned ref if no source is found.
./build/build-native.sh
# Build and test everything
dotnet build -c Release
dotnet test -c Release
# Run the comparison benchmark
dotnet run --project benchmark/Stoolap.Benchmark.csproj -c Release
The build script resolves the stoolap source in this order:
$STOOLAP_ROOTif set and points at a Cargo project.../stoolap(a sibling checkout next to this repo).- Auto-clones
github.com/stoolap/stoolapat the version pinned inSTOOLAP_ENGINE_REF(defaultv0.5.0) intobuild/.stoolap-engine/. The clone is gitignored and reused on subsequent runs.
It then runs cargo build --release --features ffi, detects the host OS/arch, and drops the resulting binary into runtimes/<rid>/native/, the standard NuGet convention. This is the same layout the published package uses to ship per-platform binaries.
The repo also includes a global.json pinning the .NET SDK to 9.0 with latestFeature rollforward, so the multi-target net8.0;net9.0 build works from a single SDK install.
License
Apache-2.0.