Store content in SQLite

SQLite keeps SunBird's content in a single file next to the site, with no database server. Use it for small sites and local development. Client sites in production on Azure use SQL Server.

1. Add the packages

dotnet add package HCI.SunBird
dotnet add package HCI.SunBird.Data.Sqlite

2. Add a connection string

In appsettings.json:

{
  "ConnectionStrings": {
    "SunBird": "Data Source=App_Data/sunbird.db"
  }
}

SunBird creates the database file if it does not exist, but the folder (App_Data here) must exist. The site needs write access to the folder, because SQLite writes a journal file beside the database.

Keep the database file out of source control, and out of wwwroot so it is never served.

3. Register SunBird and map it

In Program.cs:

using HCI.SunBird.Data.Sqlite;
using HCI.SunBird.Web;

var builder = WebApplication.CreateBuilder(args);

builder.AddSunBird().UseSqlite(builder.Configuration.GetConnectionString("SunBird")!);

var app = builder.Build();

app.MapSunBird();

app.Run();

MapSunBird() applies any pending SunBird migrations before the site starts serving requests. If no storage package was configured, it fails at startup with an error that says so.

What SunBird creates

  • SQLite has no schemas, so SunBird's table names start with SunBird_: SunBird_Pages, SunBird_PageVersions and SunBird_SlotValues, and for fragments SunBird_Fragments, SunBird_FragmentVersions and SunBird_FragmentSlotValues. They can share a database file with the site's own tables without clashing.
  • SunBird records its migrations in __SunBirdMigrationsHistory, separate from any EF Core migrations the site has of its own.
  • While it migrates, EF Core holds a lock in a __EFMigrationsLock table. That table is shared with the site's own EF Core migrations, if it has any, which is safe: they just take turns.
  • A page's rows appear only when an editor first saves it. Until then, every slot shows its markup default. See Pages and slots.

Upgrades

Each SunBird release only adds to the schema. It never drops, renames or changes a column the previous release still uses, so a database file works with the release before and the release after.

If two editors save the same page

SunBird checks for conflicting changes. If a page was changed by someone else after it was opened, the later save is refused instead of overwriting their work.

Edit this page