LiteDB, un database NoSQL embedded: usarlo in C#

LiteDB è un database NoSQL (ovvero non relazionale), con la particolare caratteristica di essere embedded, ed in particolare pensato per essere incluso all'interno di progetti relativamente piccoli in .NET.
In applicazioni abbastanza semplici, siano esse web, mobile o desktop-oriented, può in effetti tornare utile una soluzione embedded come LiteDB, soprattutto se non è necessario supportare molti accessi concorrenti in scrittura. In questo articolo vedremo quindi come operare con questo database sfruttando C#.

Introduzione a LiteDB

Prima di mettere mano al codice, partiamo da alcuni concetti di base. LiteDB fa parte di una classe di database NoSQL, comune anche a MongoDB, che è quella dei database a documenti. In breve, i documenti sono utilizzati per incapsulare i dati del database, ed in genere sono caratterizzati da una certa flessibilità, che si ripercuote soprattutto nella loro struttura (spesso non fissa). La definizione dei documenti su LiteDB viene effettuata istanziando classi POCO (acronimo che sta per Plain Old C# Object, ovvero semplici classi C#) oppure sfruttando la classe BsonDocument. In entrambi i casi, gli oggetti vengono comunque trasformati in formato BSON (Binary JSON, estensione di JSON non nuova a chi proviene da MongoDB) prima della memorizzazione vera e propria nel database.

In modo analogo a quanto accade su MongoDB, LiteDB organizza i documenti in collezioni (o collection). Ogni collezione è identificata univocamente da un nome, e può contenere uno o più documenti, oltre a fornire una serie di metodi di comodo (ognuno appartenente alla classe LiteCollection):

• Insert: permette di aggiungere un nuovo documento alla collection
• Update: aggiorna un documento esistente
• Delete: elimina un documento
• FindById e Find: eseguendo una query
• Include: utilizzato per popolare una collection a partire da altre
• EnsureIndex: crea un nuovo indice se esso non esiste

Installazione

Poiché LiteDB è una soluzione serverless, non è necessario installare nulla sul nostro sistema. L'unica cosa di cui abbiamo bisogno è aggiungere un riferimento alla libreria tramite Visual Studio, includendo nel nostro progetto LiteDB. Possiamo farlo sfruttando l'integrazione con NuGet su Visual Studio, oppure digitando tramite lo strumento a riga di comando di NuGet quanto segue:

> Install-Package LiteDB

Non ci resta che imparare ad utilizzare LiteDB con C#.

Creare una classe POCO in LiteDB con C#

Nel seguito, sfrutteremo gli esempi discussi su un post di Joydip Kanjilal, Microsoft Architect, pubblicato su InfoWorld.

Creiamo una nuova Applicazione console, selezionando la voce corrispondente nella finestra che viene mostrata in fase di creazione del progetto. Quindi, creiamo una nuova classe POCO che rappresenterà un documento fortemente tipizzato.

public class Author
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

Si noti che la classe appena creata ha una proprietà Id, che deve necessariamente essere presente se vogliamo utilizzare le istanza di tale classe con LiteDB. In alternativa, potremmo decidere di decorare una qualunque proprietà specificando l'attributo [BsonId]. In entrambi i casi, poiché l'Id deve essere univoco e non nullo, nel caso in cui lasciamo tale proprietà vuota, sarà LiteDB ad occuparsi di generare automaticamente un valore opportuno in fase di inserimento di una nuova entry.

Inserimento di una entry su LiteDB

A questo punto, non resta che capire come inserire una entry nel nostro database:

using (var db = new LiteDatabase(connectionString))
    {
       var collection = db.GetCollection<Author>("authors");
       var author = new Author
         {
             FirstName = "Joydip",
             LastName = "Kanjilal",
             Address = "Hyderabad"
          };
         collection.Insert(author);
     }

Abbiamo innanzitutto creato una nuova istanza di LiteDatabase. Quindi, otteniamo una collection pre-esistente (nel caso in cui ne esista una identificata come authors) oppure ne generiamo una nuova (nel caso in cui non ne venga trovata nessuna con il nome specificato). Tale collection viene poi popolata mediante l'uso del metodo Insert (già precedentemente menzionato), che in questo caso creerà anche un Id per il documento (dal momento che non lo abbiamo specificato in fase di creazione dell'oggetto).

Query con LiteDB

Una volta inserito un documento, possiamo ovviamente eseguire una query. Ecco un esempio:

using (var db = new LiteDatabase(connectionString))
   {
     var collection = db.GetCollection<Author>("authors");
     var author = collection.FindById(1);
     Console.WriteLine(author.FirstName + "\t" +author.LastName);
   }

Abbiamo utilizzato il metodo FindById che restituisce un documento a partire dal suo Id, oppure dall'indice di chiave primaria. Possiamo creare tale indice con il metodo EnsureIndex:

authors.EnsureIndex("FirstName");

In alternativa, possiamo eseguire query sfruttando il metodo Find e la seguente sintassi:

var results = collection.Find(x => x.Address.Contains("Hyderabad"));

Aggiornamento di un documento su LiteDB

L'aggiornamento di un documento viene effettuato sfruttando il metodo Update, come mostrato di seguito:

var author = collection.FindById(1);
author.Address ="Via Roma";
collection.Update(author);

Lavorare con i file

LiteDB fornisce anche una particolare collection denominata FileStorage, che permette di lavorare con i file. In breve, essa permette di effettuare il download o l'upload di un file sul database, utilizzando due semplici metodi: Upload e Download:

db.FileStorage.Upload("Mia-Foto", @"C:\Temp\Vito.jpg"); // Carica un'immagine sul DB
db.FileStorage.Download("Mia-Foto”, @”C:\MioPath\Vito.jpg”); // Salva l'immagine sul file system

Si noti che LiteDB crea due collection per lavorare con i file, denominate rispettivamente _files e _chunks. La prima contiene informazioni relative ai metadati dei file, mentre la seconda contiene i dati veri e propri.

Conclusioni

Quanto visto è ovviamente solo una breve panoramica di LiteDB, database embedded che può tornare comodo in molte situazioni. La sua natura NoSQL lo rende flessibile e facilmente adattabile a vari contesti, sebbene progetti molto grandi possano richiedere soluzioni più appropriate.

Tutte le informazioni su LiteDB possono essere reperite su sito ufficiale del progetto.