TursoDb - EasyAF

TursoDb provides a powerful, type-safe wrapper around libSQL for Blazor WebAssembly applications. It enables local-first development with SQLite stored in the browser, with optional synchronization to Turso Cloud.

Local-First

Data is stored locally in the browser using SQLite, ensuring your app works offline.

Cloud Sync

Optionally sync with Turso Cloud for multi-device and real-time collaboration.

Type-Safe

Entity attributes and strongly-typed DbSets provide compile-time safety.

Auto Schema

Tables and indexes are automatically created from your entity definitions.

Installation

Install the NuGet package

dotnet add package BlazorEssentials.TursoDb

Install the Server package (required)

TursoDb requires Cross-Origin Isolation headers for SharedArrayBuffer support.

dotnet add package BlazorEssentials.Server

Configure middleware

Add the Cross-Origin Isolation middleware to your server’s Program.cs:

Program.cs

var app = builder.Build();

// Add before other middleware
app.UseCrossOriginIsolation();

app.UseBlazorFrameworkFiles();
app.UseStaticFiles();
// ... rest of your middleware

Cross-Origin Isolation may break third-party scripts, iframes, and CDN resources that aren’t configured for isolated contexts. Test thoroughly before deploying.

Quick Start

Define Your Entities

Use attributes to define how your C# classes map to SQLite tables:

Models/User.cs

using CloudNimble.BlazorEssentials.TursoDb;

[Table("users")]
public class User
{
    [PrimaryKey(AutoIncrement = true)]
    public long Id { get; set; }

    [Column("name")]
    public string Name { get; set; } = "";

    [Column("email")]
    [Index(Unique = true)]
    public string Email { get; set; } = "";

    [Column("age")]
    public int Age { get; set; }

    [Column("is_active")]
    public bool IsActive { get; set; } = true;

    [Column("created_at")]
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

Use [NotMapped] on properties you don’t want persisted to the database.

Create Your Database

Inherit from TursoDatabase and add TursoDbSet<T> properties for each entity:

Data/AppDatabase.cs

using CloudNimble.BlazorEssentials.TursoDb;
using Microsoft.JSInterop;

public class AppDatabase : TursoDatabase
{
    public TursoDbSet<User> Users { get; }
    public TursoDbSet<Post> Posts { get; }

    public AppDatabase(IJSRuntime jsRuntime) : base(jsRuntime)
    {
        Name = "myapp.db";
        Users = new TursoDbSet<User>(this);
        Posts = new TursoDbSet<Post>(this);
    }
}

Register and Use

builder.Services.AddScoped<AppDatabase>();

@inject AppDatabase Database

@code {
    protected override async Task OnInitializedAsync()
    {
        await Database.ConnectAsync();

        var users = await Database.Users.ToListAsync();
    }
}

Entity Attributes

[Table] - Define table name

Maps a class to a specific table name in SQLite.

[Table("users")]
public class User { }

If omitted, the class name is used as the table name.

[PrimaryKey] - Define primary key

Marks a property as the primary key. Use AutoIncrement = true for auto-generated IDs.

[PrimaryKey(AutoIncrement = true)]
public long Id { get; set; }

[Column] - Define column name

Maps a property to a specific column name. Use snake_case for SQLite conventions.

[Column("created_at")]
public DateTime CreatedAt { get; set; }

[Index] - Create an index

Creates an index on the column for faster queries. Use Unique = true for unique constraints.

[Column("email")]
[Index(Unique = true)]
public string Email { get; set; }

[NotMapped] - Exclude from database

Excludes a property from database persistence.

[NotMapped]
public string FullName => $"{FirstName} {LastName}";

CRUD Operations

Create

var user = new User
{
    Name = "John Doe",
    Email = "john@example.com",
    Age = 30
};

await Database.Users.AddAsync(user);
// user.Id is now populated with the auto-generated ID

Read

var allUsers = await Database.Users.ToListAsync();

var user = await Database.Users.FindAsync(1);

var count = await Database.Users.CountAsync();

Update

var user = await Database.Users.FindAsync(1);
user.Name = "Jane Doe";
user.Age = 31;

await Database.Users.UpdateAsync(user);

Delete

var user = await Database.Users.FindAsync(1);
await Database.Users.RemoveAsync(user);

await Database.Users.RemoveByKeyAsync(1);

Query Builder

Build complex queries with the fluent query API:

var activeAdults = await Database.Users
    .Where("age >= ? AND is_active = ?", 18, true)
    .OrderBy("name")
    .Take(10)
    .ToListAsync();

Available Methods

Method	Description
`Where(clause, params)`	Filter results with a SQL WHERE clause
`OrderBy(column)`	Sort ascending by column
`OrderByDescending(column)`	Sort descending by column
`Take(count)`	Limit results to count
`Skip(count)`	Skip first count results
`ToListAsync()`	Execute and return all results
`FirstOrDefaultAsync()`	Execute and return first result or null
`CountAsync()`	Return count of matching results

Use ? placeholders for parameters to prevent SQL injection. Parameters are passed in order after the SQL clause.

Transactions

Use transactions for atomic operations that should succeed or fail together:

await using var transaction = await Database.BeginTransactionAsync();
try
{
    await Database.Users.AddAsync(new User { Name = "User 1" });
    await Database.Users.AddAsync(new User { Name = "User 2" });

    await transaction.CommitAsync();
}
catch
{
    await transaction.RollbackAsync();
    throw;
}

If you dispose the transaction without calling CommitAsync(), it automatically rolls back.

Prepared Statements

For frequently executed queries, use prepared statements for better performance:

var statement = Database.Prepare<User>("SELECT * FROM users WHERE age > ?");

var youngUsers = await statement.QueryAsync(18);
var olderUsers = await statement.QueryAsync(65);

await statement.DisposeAsync();

var statement = Database.Prepare("UPDATE users SET is_active = ? WHERE age < ?");

await statement.ExecuteAsync(false, 13);
await statement.ExecuteAsync(true, 18);

await statement.DisposeAsync();

Raw SQL

Execute raw SQL when you need full control:

var result = await Database.ExecuteAsync(
    "INSERT INTO users (name, email) VALUES (?, ?)",
    "John", "john@example.com"
);

Console.WriteLine($"Rows affected: {result.RowsAffected}");
Console.WriteLine($"Last insert ID: {result.LastInsertRowId}");

var users = await Database.QueryAsync<User>(
    "SELECT * FROM users WHERE email LIKE ?",
    "%@example.com"
);

var results = await Database.ExecuteBatchAsync(
    ("INSERT INTO users (name) VALUES (?)", new object[] { "User 1" }),
    ("INSERT INTO users (name) VALUES (?)", new object[] { "User 2" }),
    ("INSERT INTO users (name) VALUES (?)", new object[] { "User 3" })
);

Turso Cloud Sync

For multi-device sync and cloud backup, use TursoSyncDatabase:

Setup

Data/SyncedAppDatabase.cs

using CloudNimble.BlazorEssentials.TursoDb;
using Microsoft.JSInterop;

public class SyncedAppDatabase : TursoSyncDatabase
{
    public TursoDbSet<User> Users { get; }

    public SyncedAppDatabase(IJSRuntime jsRuntime) : base(jsRuntime)
    {
        Name = "myapp.db";
        SyncUrl = "libsql://mydb-myorg.turso.io";
        SyncAuthToken = "your-auth-token";
        Users = new TursoDbSet<User>(this);
    }
}

Never hardcode auth tokens in production code. Use configuration or secure storage.

Sync Operations

// Download changes from Turso Cloud
var result = await Database.PullAsync();
Console.WriteLine($"Synced {result.FramesSynced} frames in {result.DurationMs}ms");

// Upload local changes to Turso Cloud
var result = await Database.PushAsync();

// Pull then push in one operation
var result = await Database.SyncAsync();

Sync Events

Subscribe to sync lifecycle events:

Database.SyncStarted += (sender, e) =>
{
    Console.WriteLine("Sync started...");
};

Database.SyncCompleted += (sender, result) =>
{
    Console.WriteLine($"Sync completed: {result.FramesSynced} frames");
};

Database.SyncFailed += (sender, ex) =>
{
    Console.WriteLine($"Sync failed: {ex.Message}");
};

Sync Options

Property	Description	Default
`SyncUrl`	Turso Cloud database URL	Required
`SyncAuthToken`	Authentication token	Required
`SyncOnConnect`	Sync automatically on connect	`true`
`SyncIntervalMs`	Auto-sync interval (0 = disabled)	`0`
`EncryptionEnabled`	Enable local database encryption	`false`
`EncryptionKey`	Encryption key for local database	`null`

Cross-Origin Isolation

TursoDb requires Cross-Origin Isolation headers for SharedArrayBuffer support. The BlazorEssentials.Server package provides middleware to add these headers.

Basic Configuration

app.UseCrossOriginIsolation();

Advanced Configuration

app.UseCrossOriginIsolation(options =>
{
    // Use less strict policy for better compatibility
    options.CoepPolicy = "credentialless";

    // Exclude paths that need third-party resources
    options.ExcludePaths.Add("/api/");
    options.ExcludePaths.Add("/external/");

    // Disable CORP header if causing issues
    options.IncludeCorpHeader = false;
});

Headers Added

Header	Value	Purpose
`Cross-Origin-Opener-Policy`	`same-origin`	Isolates browsing context
`Cross-Origin-Embedder-Policy`	`require-corp`	Requires resources to grant permission
`Cross-Origin-Resource-Policy`	`same-origin`	Controls resource sharing

Type Mapping

TursoDb automatically maps C# types to SQLite types:

C# Type	SQLite Type
`int`, `long`, `short`, `byte`	`INTEGER`
`float`, `double`, `decimal`	`REAL`
`string`	`TEXT`
`bool`	`INTEGER` (0/1)
`DateTime`, `DateTimeOffset`	`TEXT` (ISO 8601)
`Guid`	`TEXT`
`byte[]`	`BLOB`

Best Practices

Use dependency injection

builder.Services.AddScoped<AppDatabase>();

Connect once, early

Connect to the database early in your app lifecycle, such as in App.razor or a layout component:

protected override async Task OnInitializedAsync()
{
    await Database.ConnectAsync();
}

Handle sync conflicts

When using cloud sync, implement conflict resolution strategies for your use case. Consider using timestamps or version numbers to detect conflicts.

Troubleshooting

SharedArrayBuffer is not defined

This error indicates Cross-Origin Isolation is not configured. Ensure:

BlazorEssentials.Server is installed
app.UseCrossOriginIsolation() is called before other middleware
Headers are not being stripped by a proxy or CDN

Third-party scripts not loading

Cross-Origin Isolation may break external scripts. Options:

Use options.CoepPolicy = "credentialless" for less strict isolation
Add script paths to options.ExcludePaths
Ensure external resources have Cross-Origin-Resource-Policy headers

Sync authentication failed

Verify your Turso Cloud credentials:

Check SyncUrl format: libsql://[db-name]-[org].turso.io
Ensure SyncAuthToken is valid and not expired
Verify the database exists in your Turso dashboard

API Reference

TursoDatabase

Base class for local databases

TursoSyncDatabase

Sync-enabled database with Turso Cloud

TursoDbSet

Typed collection for entity CRUD operations

TursoQueryBuilder

Fluent query builder API

Local-First

Cloud Sync

Type-Safe

Auto Schema

​Installation

​Quick Start

​Define Your Entities

​Create Your Database

​Register and Use

​Entity Attributes

​CRUD Operations

​Create

​Read

​Update

​Delete

​Query Builder

​Available Methods

​Transactions

​Prepared Statements

​Raw SQL

​Turso Cloud Sync

​Setup

​Sync Operations

​Sync Events

​Sync Options

​Cross-Origin Isolation

​Basic Configuration

​Advanced Configuration

​Headers Added

​Type Mapping

​Best Practices

​Troubleshooting

​API Reference

TursoDatabase

TursoSyncDatabase

TursoDbSet

TursoQueryBuilder

Installation

Quick Start

Define Your Entities

Create Your Database

Register and Use

Entity Attributes

CRUD Operations

Create

Read

Update

Delete

Query Builder

Available Methods

Transactions

Prepared Statements

Raw SQL

Turso Cloud Sync

Setup

Sync Operations

Sync Events

Sync Options

Cross-Origin Isolation

Basic Configuration

Advanced Configuration

Headers Added

Type Mapping

Best Practices

Troubleshooting

API Reference