BitBadger.Documents/src/Sqlite

BitBadger.Documents.Sqlite

This package provides a lightweight document library backed by SQLite. It also provides streamlined functions for traditional ADO.NET functionality where relational data is required. Both C# and F# have first-class implementations.

Features

• Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
• Automatically generate IDs for documents (numeric IDs, GUIDs, or random strings)
• Address documents via ID or via comparison on any field
• Access documents as your domain models (POCOs)
• Use Task-based async for all data access functions
• Use building blocks for more complex queries

Upgrading from v3

There is a breaking API change for ByField (C#) / byField (F#), along with a compatibility namespace that can mitigate the impact of these changes. See the migration guide for full details.

Getting Started

Once the package is installed, the library needs a connection string. Once it has been obtained / constructed, provide it to the library:

// C#
using BitBadger.Documents.Sqlite;

//...
Sqlite.Configuration.UseConnectionString("connection-string");

// A new, open connection to the database can be obtained via
// Sqlite.Configuration.DbConn()

// F#
open BitBadger.Documents.Sqlite

// ...
Configuration.useConnectionString "connection-string"

// A new, open connection to the database can be obtained via
// Configuration.dbConn ()

By default, the library uses a System.Text.Json-based serializer configured to use the FSharp.SystemTextJson converter. To provide a different serializer (different options, more converters, etc.), construct it to implement IDocumentSerializer and provide it via Configuration.useSerializer. If custom serialization makes the serialized Id field not be Id, that will also need to be configured.

Using

Retrieve all customers:

// C#; parameter is table name
// Find.All type signature is Func<string, Task<List<TDoc>>>
var customers = await Find.All<Customer>("customer");

// F#
// Find.all type signature is string -> Task<'TDoc list>
let! customers = Find.all<Customer> "customer"

Select a customer by ID:

// C#; parameters are table name and ID
// Find.ById type signature is Func<string, TKey, Task<TDoc?>>
var customer = await Find.ById<string, Customer>("customer", "123");

// F#
// Find.byId type signature is string -> 'TKey -> Task<'TDoc option>
let! customer = Find.byId<string, Customer> "customer" "123"

(keys are treated as strings in the database)

Count customers in Atlanta:

// C#; parameters are table name, field, operator, and value
// Count.ByFields type signature is Func<string, FieldMatch, IEnumerable<Field>, Task<long>>
var customerCount = await Count.ByFields("customer", FieldMatch.Any, [Field.Equal("City", "Atlanta")]);

// F#
// Count.byFields type signature is string -> FieldMatch -> Field seq -> Task<int64>
let! customerCount = Count.byFields "customer" Any [ Field.Equal "City" "Atlanta" ]

Delete customers in Chicago: (no offense, Second City; just an example...)

// C#; parameters are same as above, except return is void
// Delete.ByFields type signature is Func<string, FieldMatch, IEnumerable<Field>, Task>
await Delete.ByFields("customer", FieldMatch.Any, [Field.Equal("City", "Chicago")]);

// F#
// Delete.byFields type signature is string -> FieldMatch -> Field seq -> Task<unit>
do! Delete.byFields "customer" Any [ Field.Equal "City" "Chicago" ]

More Information

The project site has full details on how to use this library.