Store content in SQL Server

SQL Server is SunBird's default database. Client sites in production use Azure SQL in the elastic pool, and developers can use SQL Server LocalDB on their own machine.

1. Add the packages

dotnet add package HCI.SunBird
dotnet add package HCI.SunBird.Data.SqlServer

2. Add a connection string

In appsettings.json, or in the App Service configuration for a deployed site:

{
  "ConnectionStrings": {
    "SunBird": "Server=(localdb)\\MSSQLLocalDB;Database=MySite;Trusted_Connection=True"
  }
}

The database user needs rights to create and alter tables (for example db_ddladmin), because SunBird applies its own migrations at startup.

3. Register SunBird and map it

In Program.cs:

using HCI.SunBird.Data.SqlServer;
using HCI.SunBird.Web;

var builder = WebApplication.CreateBuilder(args);

builder.AddSunBird().UseSqlServer(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

  • SunBird's tables live in their own sunbird schema: sunbird.Pages, sunbird.PageVersions and sunbird.SlotValues, and for fragments sunbird.Fragments, sunbird.FragmentVersions and sunbird.FragmentSlotValues. They can share a database with the site's own tables without clashing.
  • SunBird records its migrations in sunbird.__SunBirdMigrationsHistory, separate from any EF Core migrations the site has of its own.
  • 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 and the shared database

The staging slot and production share one database during a release (see Staging mode). Each SunBird release therefore only adds to the schema. It never drops, renames or changes a column the previous release still uses. When the new release starts in staging and migrates the database, production keeps working on the old code until the swap.

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