Libsql.Client

August 30, 2025 · View on GitHub

Libsql.Client

A .NET client library for libsql.

This project is still in early development and not ready for production use.

Currently Supported Features

Creating a database:
- In memory.
- From file.
- From connection string.
Executing SQL statements:
- Non-parameterised.

Planned Features

Positional and named arguments.
Embedded replicas.
Prepared statements.
Batched statements.
Transactions.

Usage

For an example, see the Demo project in the repository.

Creating a Database

You can open a database in different locations:

In-Memory Database

// Create an in-memory database.
var dbClient = await DatabaseClient.Create(opts => {
    opts.Url = ":memory:";
});

From a File

// Creates or opens a database stored in a local file.
var dbClient = await DatabaseClient.Create(opts => {
    opts.Url = "file:./mydb.sqlite";
});

From a Connection String

// Opens a database using a full connection string.
var dbClient = await DatabaseClient.Create(opts => {
    opts.Url = "https://my-remote-db.example.com";
});

Provide Additional Connection Options

Remote Databases

For remote libSQL databases, use client options for authentication and secure connections:

// Connect to a remote database with authentication and HTTPS enabled
var dbClient = await DatabaseClient.Create(opts =>
{
    opts.Url = "https://my-remote-db.example.com";
    opts.AuthToken = "MY_TOKEN";
    opts.UseHttps = true;
});

Local File Databases

For local files, you can pass standard query parameters via the file URI:

// Open a local database with query parameters
var dbClient = await DatabaseClient.Create(opts =>
{
    opts.Url = "file:mydb.sqlite?mode=rwc&cache=shared";
});

Executing SQL Statements

Using direct queries

await dbClient.Execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, height REAL)");

Using positional arguments

await dbClient.Execute("SELECT name FROM users WHERE id = ?", userId);

Querying the Database

User ToUser(IEnumerable<Value> row)
{
    var rowArray = row.ToArray();

    if (
        rowArray[0] is Integer { Value: var id } && 
        rowArray[1] is Text { Value: var name } && 
        rowArray[2] is Real { Value: var height }
    {
        return new User(id, name, height);   
    }

    throw new ArgumentException();
}

var result = await dbClient.Execute("SELECT * FROM users");

var users = result.Rows.Select(ToUser);

Closing the Database

dbClient.Dispose();

or with a using statement:

using (var dbClient = await DatabaseClient.Create(opts => {
    opts.Url = ":memory:";
}))
{
    // ...
}

Disclaimer

This project is still in early development and not ready for production use. The API is subject to include breaking changes on minor versions until version 1.0.

The full test suite is run only on a Linux x64 platform. Most of the test suite is run on Linux, Windows, and macOS x64 platforms. The test suite runs on .NET 7.