SoftwareDriven.Persistence.SQLite 3.4.2

dotnet add package SoftwareDriven.Persistence.SQLite --version 3.4.2
                    
NuGet\Install-Package SoftwareDriven.Persistence.SQLite -Version 3.4.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SoftwareDriven.Persistence.SQLite" Version="3.4.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SoftwareDriven.Persistence.SQLite" Version="3.4.2" />
                    
Directory.Packages.props
<PackageReference Include="SoftwareDriven.Persistence.SQLite" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SoftwareDriven.Persistence.SQLite --version 3.4.2
                    
#r "nuget: SoftwareDriven.Persistence.SQLite, 3.4.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package SoftwareDriven.Persistence.SQLite@3.4.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=SoftwareDriven.Persistence.SQLite&version=3.4.2
                    
Install as a Cake Addin
#tool nuget:?package=SoftwareDriven.Persistence.SQLite&version=3.4.2
                    
Install as a Cake Tool

SoftwareDriven.Persistence.SQLite

A document persistence layer for SQLite building on SoftwareDriven.Persistence: the models are stored as JSON documents, one table per model type. Nested models need no mapping, and new fields need no schema change. Built on Microsoft.Data.Sqlite, without Entity Framework.

Installation

dotnet add package SoftwareDriven.Persistence.SQLite

Setup

services.AddSingleton(new JsonSerializerOptions());   // optional, the defaults otherwise
services.AddSQLiteDocuments();
services.AddSQLiteDocumentProvider<Session>(map => map
    .Index(x => x.StudyId)
    .Index(x => new { x.StudyId, x.ParticipantHash })
    .UniqueIndex(x => x.Token));

var manager = serviceProvider.GetRequiredService<SQLiteDocumentManager>();
await manager.Connect("data/player.db");

Keyed registration works as with the other packages: AddSQLiteDocuments("Offline"), AddSQLiteDocumentProvider<Session>(map => ..., "Offline").

Storage layout

Each table has the columns Id (primary key), Revision and Doc (the JSON document). The table is named after the type or the name registered with manager.RegisterTableName<T>(...), and is created on first use together with the declared indexes. Indexes are expression indexes over json_extract(Doc, ...). The database runs in WAL mode with synchronous=NORMAL: a power failure may take the last commits with it, the database stays intact.

Files stored via IFileProvider go to the local file system by default ({BasePath}/{FileFolder}/{fileId}), or to the file backend registered via AddLocalFileStorage() / AddS3FileStorage().

Queries

Predicates are translated to SQL conditions over the documents as far as possible and evaluated on the documents read as well, so every predicate gives the same result as in memory. Translated are comparisons of fields of type string, bool, integer and double (also nullable) with values not depending on the model, &&, ||, ! on a bool field, Contains of a value list and string.StartsWith. Field names follow the JsonSerializerOptions. Documents lacking a field of a value type - written before the field was added - match as its default value, as the deserialized model does.

A predicate that cannot be translated, or only partly, reads all candidate rows; projections, sorting and paging run in memory on the documents matching the predicate. Fully translated predicates are counted and deleted in SQL.

The translation assumes the default JSON representation of strings, numbers and booleans. Switch it off per type with map.TranslateQueries = false for models with custom converters for such members.

Conditional writes

SQLiteDocumentProvider<T> implements IConditionalPersistenceProvider<T> for models implementing IRevisioned: TryInsert and TryReplace are checked by the database, across connections and processes using the file. A violated unique index is reported as WriteOutcome.Conflict by TryInsert.

Migrations

AddSQLiteDocuments registers the providers of MigrationStatus and MigrationLease, so the MigrationManager runs with its lock:

await new MigrationManager(serviceProvider)
    .UseDatabase<SQLiteDocumentManager>("_migrations")
    .UseAssembly(Assembly.GetExecutingAssembly())
    .Run();

The database type of the migrations is SQLiteDocument.

Maintenance

var statistics = await manager.GetStatistics();  // file plus WAL, free list
var result = await manager.Compact();            // VACUUM plus wal_checkpoint(TRUNCATE)

Features

  • SupportsTotalCount: true
  • SupportsPagingState: false (offset-based pagination, in memory)
  • DefaultIdSource: GuidSource
  • SupportsMaintenance: true when connected
  • Full IPersistenceProvider<T> support including nested collection projections and element match queries

License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.4.2 59 11/11/2026