Database changes

A release can change the model behind the CMS: a new table, a new column. The migrations for those changes ship inside the Cendia packages, in Cendia.Data. You never write one for Cendia's tables. What you decide is when they are applied to a given database.

After you update the packages

Change the Cendia.CMS version as Packages and versions describes, then:

• In Development, on a database on your machine (LocalDB, as the Starter has it), run the site. It applies the new migrations as it starts.

• Against any other database, apply them yourself, from Visual Studio's Package Manager Console:

  Update-Database
  

  Or from the site's folder:

  dotnet ef database update
  

A Development run pointed at a shared or production database never migrates it, so pressing F5 cannot change the live site's schema by accident.

When you deploy

Outside Development nothing migrates by default. A published site starts on whatever database it is given and leaves its schema alone, because a deployment that rewrites a database without being asked is worse than one that stops. Pick one of these and make it part of how you deploy.

Apply it from your machine or pipeline. Point the command at the production database and run it before the new build goes live:

dotnet ef database update --connection "<production connection string>"

Hand a script to whoever runs the database. An idempotent script checks the migrations history itself, so it is safe against a database at any earlier version:

dotnet ef migrations script --idempotent --output deploy.sql

Let the site migrate itself. Set this on the host, as an environment variable rather than in appsettings.json:

Cendia__MigrateOnStartup=true

Every start then applies the migrations the packages carry. A migration that fails stops the site, so it never serves against a half-updated database. It is ignored in Development. Use it when the site is the only thing using its database.

On Cendia Hosting a site always migrates itself as it starts. There is nothing to do.

The startup check

Each time the site starts it compares its database with the Cendia it runs, and writes a warning to the log when they disagree:

The site still starts. Much of it works on a database one release behind, and refusing to start would take a working site down over a page that reads a new column. But the pages that need the change will fail until the migrations are applied. Nothing is logged when everything agrees.

Your own tables

Keep them out of CmsDbContext. Give your site a DbContext of its own, with its own migrations in your project, and give its tables a prefix of your own. cms_ is Cendia's, and a table of yours with that prefix can collide with one a later release adds. A plugin uses a prefix of its own too.

Give your context its own history table as well, so its migrations and Cendia's are never read as one list:

builder.Services.AddDbContext<MySiteDbContext>(options =>
    options.UseSqlServer(connectionString,
        sql => sql.MigrationsHistoryTable("__MySiteMigrationsHistory")));

Your migrations are then yours to add and apply, Add-Migration -Context MySiteDbContext and Update-Database -Context MySiteDbContext, and a Cendia update never touches them.