SqliteWasmBlazor 0.8.1-pre

SqliteWasmBlazor

The first known solution providing true filesystem-backed SQLite database with full EF Core support for Blazor WebAssembly.

Try the Live Demo - Experience persistent SQLite database in your browser! Can be installed as a Progressive Web App (PWA) for offline use.

About This Project

This is a non-commercial hobby project maintained in my spare time - no fixed update cycle or roadmap. However, "hobby" refers to time and commitment, not craftsmanship: the project is developed with professional standards including proper test coverage and attention to code quality.

Open source thrives on community involvement. The project grows through bug reports, feature requests, pull requests, and real-world feedback. If you're considering this for production use, I'd encourage you to contribute back - that's how open source stays alive, not through promises from a single maintainer, but through shared ownership.

Stability & Status

The public API surface is intentionally kept minimal to reduce the risk of breaking changes. While the API has been stable in practice, this project is pre-1.0: broader real-world feedback is needed before committing to long-term API guarantees. Contributions and usage reports help move toward that goal.

What's New

• Raw Database Import/Export - Export and import complete .db files directly from/to OPFS with schema validation and automatic backup/restore on failure (details)
• Multi-Database Support - Run multiple independent SQLite databases simultaneously in the same Web Worker, each with its own OPFS file, DbContext, and migration history. Supports cross-database references via loose Guid linking (details)
• Multi-View Demo - Floating draggable/resizable dialog windows using lightweight JS interop on top of standard MudBlazor dialogs (details)
• Incremental Database Export/Import - File-based delta sync with checkpoint management and conflict resolution for offline-first PWAs (details)
• Database Import/Export - Schema-validated MessagePack serialization for backups and data migration (details)
• Real-World Sample - Check out the Datasync TodoApp for offline-first data synchronization with SqliteWasmBlazor

Breaking Changes

• v0.7.2-pre - SqliteWasmWorkerBridge is now internal. Use ISqliteWasmDatabaseService via DI instead:

  // Program.cs - add service registration
  builder.Services.AddSqliteWasm();
  
  // Components - inject the interface
  @inject ISqliteWasmDatabaseService DatabaseService
  
  // Replace SqliteWasmWorkerBridge.Instance.DeleteDatabaseAsync(...)
  // with:   DatabaseService.DeleteDatabaseAsync(...)
  

What Makes This Special?

Unlike other Blazor WASM database solutions that use in-memory storage or IndexedDB emulation, SqliteWasmBlazor is the first implementation that combines:

• True Filesystem Storage - Uses OPFS (Origin Private File System) with synchronous access handles
• Full EF Core Support - Complete ADO.NET provider with migrations, relationships, and LINQ
• Real SQLite Engine - Official sqlite-wasm (3.50.4) running in Web Worker
• Persistent Data - Survives page refreshes, browser restarts, and even browser updates
• No Server Required - Everything runs client-side in the browser

Public API

SqliteWasmBlazor exposes a stable public API for database management operations via dependency injection:

ISqliteWasmDatabaseService

The primary interface for database operations outside of EF Core:

public interface ISqliteWasmDatabaseService
{
    /// <summary>Check if a database exists in OPFS.</summary>
    Task<bool> ExistsDatabaseAsync(string databaseName, CancellationToken cancellationToken = default);

    /// <summary>Delete a database from OPFS.</summary>
    Task DeleteDatabaseAsync(string databaseName, CancellationToken cancellationToken = default);

    /// <summary>Rename a database in OPFS (atomic operation).</summary>
    Task RenameDatabaseAsync(string oldName, string newName, CancellationToken cancellationToken = default);

    /// <summary>Close a database connection in the worker.</summary>
    Task CloseDatabaseAsync(string databaseName, CancellationToken cancellationToken = default);

    /// <summary>Import a raw .db file into OPFS.</summary>
    Task ImportDatabaseAsync(string databaseName, byte[] data, CancellationToken cancellationToken = default);

    /// <summary>Export a raw .db file from OPFS.</summary>
    Task<byte[]> ExportDatabaseAsync(string databaseName, CancellationToken cancellationToken = default);
}

Usage in components:

@inject ISqliteWasmDatabaseService DatabaseService

@code {
    private async Task ResetDatabaseAsync()
    {
        // Delete and recreate database
        await DatabaseService.DeleteDatabaseAsync("MyApp.db");

        await using var context = await DbContextFactory.CreateDbContextAsync();
        await context.Database.MigrateAsync();
    }

    private async Task ExportAsync()
    {
        // Export raw .db file (closes DB for consistent snapshot, auto-reopens on next query)
        byte[] data = await DatabaseService.ExportDatabaseAsync("MyApp.db");
    }

    private async Task ImportAsync(byte[] data)
    {
        // Import raw .db file (validates SQLite header)
        await DatabaseService.ImportDatabaseAsync("MyApp.db", data);
    }
}

Other Public Types

All internal implementation details (worker bridge, serialization, etc.) are encapsulated and not part of the public API.

Installation

NuGet Package

dotnet add package SqliteWasmBlazor --prerelease

Or install a specific version:

dotnet add package SqliteWasmBlazor --version 0.6.5-pre

Visit NuGet.org for the latest version.

From Source

git clone https://github.com/bernisoft/SqliteWasmBlazor.git
cd SqliteWasmBlazor
dotnet build

Quick Start

1. Configure Your Project

Program.cs:

using SqliteWasmBlazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

// Add your DbContext with SqliteWasm provider
builder.Services.AddDbContextFactory<TodoDbContext>(options =>
{
    var connection = new SqliteWasmConnection("Data Source=TodoDb.db");
    options.UseSqliteWasm(connection);
});

// Register initialization service
builder.Services.AddSingleton<IDBInitializationService, DBInitializationService>();

// Register SqliteWasm database management service (for ISqliteWasmDatabaseService)
builder.Services.AddSqliteWasm();

var host = builder.Build();

// Initialize SqliteWasm database with automatic migration support
await host.Services.InitializeSqliteWasmDatabaseAsync<TodoDbContext>();

await host.RunAsync();

The InitializeSqliteWasmDatabaseAsync extension method automatically:

• Initializes the Web Worker bridge
• Applies pending migrations (with automatic migration history recovery)
• Handles multi-tab conflicts with helpful error messages
• Tracks initialization status via IDBInitializationService

2. Define Your DbContext

using Microsoft.EntityFrameworkCore;

public class TodoDbContext : DbContext
{
    public TodoDbContext(DbContextOptions<TodoDbContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<TodoItem>(entity =>
        {
            entity.HasKey(e => e.Id);
            entity.Property(e => e.Title).IsRequired().HasMaxLength(200);
        });
    }
}

public class TodoItem
{
    public int Id { get; set; }
    public string Title { get; set; }
    public bool IsCompleted { get; set; }
    public DateTime CreatedAt { get; set; }
}

3. Use in Your Components

@inject IDbContextFactory<TodoDbContext> DbFactory

<h3>Todo List</h3>

@foreach (var todo in todos)
{
    <div>
        <input type="checkbox" @bind="todo.IsCompleted" @bind:after="() => SaveTodo(todo)" />
        <span>@todo.Title</span>
    </div>
}

@code {
    private List<TodoItem> todos = new();

    protected override async Task OnInitializedAsync()
    {
        await using var db = await DbFactory.CreateDbContextAsync();
        todos = await db.TodoItems.OrderBy(t => t.CreatedAt).ToListAsync();
    }

    private async Task SaveTodo(TodoItem todo)
    {
        await using var db = await DbFactory.CreateDbContextAsync();
        db.TodoItems.Update(todo);
        await db.SaveChangesAsync(); // Automatically persists to OPFS!
    }
}

Features

Full EF Core Support

// Migrations
await dbContext.Database.MigrateAsync();

// Complex queries with LINQ
var results = await dbContext.Orders
    .Include(o => o.Customer)
    .Where(o => o.Total > 100)
    .OrderByDescending(o => o.Date)
    .ToListAsync();

// Relationships
public class Order
{
    public int Id { get; set; }
    public Customer Customer { get; set; }
    public List<OrderItem> Items { get; set; }
}

// Decimal arithmetic (via ef_ scalar functions)
var expensive = await dbContext.Products
    .Where(p => p.Price * 1.2m > 100m)
    .ToListAsync();

High Performance

• Efficient Serialization - JSON for requests (small), MessagePack for responses (optimized for data)
• Typed Column Information - Worker sends type metadata to reduce .NET marshalling overhead
• OPFS SAHPool - Near-native filesystem performance with synchronous access
• Direct Execution - Queries run directly on persistent storage, no copying needed

Enterprise-Ready

• Type Safety - Full .NET type system with proper decimal support
• EF Core Functions - All ef_* scalar and aggregate functions implemented
• JSON Collections - Store List<T> with proper value comparers
• Logging - Configurable logging levels (Debug/Info/Warning/Error)
• Error Handling - Proper async error propagation

Documentation

Browser Support

All modern browsers (2023+) support OPFS with Synchronous Access Handles, including mobile browsers (iOS/iPadOS Safari, Android Chrome).

Roadmap

• Core ADO.NET provider
• OPFS SAHPool integration
• EF Core migrations support
• MessagePack serialization
• Custom EF functions (decimals)
• FTS5 full-text search with highlighting and snippets
• MudBlazor demo app
• NuGet package pre-release
• Database export/import API (MessagePack serialization + raw .db files)
• Backup/restore utilities (delta sync with checkpoints)
• Raw database import/export with schema validation
• Stable NuGet package release
• Multi-database support
• Performance profiling tools

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Credits

Author: bernisoft License: MIT

Built with:

• SQLite - The world's most deployed database
• sqlite-wasm - Official SQLite WebAssembly build
• Entity Framework Core - Modern data access
• MessagePack - Efficient binary serialization
• MudBlazor - Material Design components

License

MIT License - Copyright (c) 2025 bernisoft

See LICENSE file for details.

Built with love for the Blazor community

If you find this useful, please star the repository!