Update Database Schema and Migrations in EF Core

• Jul 09, 2025
• 4 minutes to read

When you develop an application (in Debug mode) you can use the following options to update database schema when the structure of business objects changes:

• Automatic Database Schema Update (default behavior)
  XAF automatically updates database schema when you change the data model of your application.
• EF Core Migrations
  You can manually generate and apply migrations to a database every time you change the data model of your application.

To update the production database, run the XAF application with specific command line parameters. See the following help topic for additional information: Production Database and Application Updates.

Automatic Database Schema Update

In Debug mode, XAF automatically updates database schema when the structure of business objects changes. For instance, when you add a new business class or a property, or remove a property, XAF can create missing tables, add or remove columns, indexes, etc.

Important

Note that you can lose data if you delete columns, change column types, delete/recreate indexes, or otherwise modify the database.

We recommend that you use automatic database schema update with test databases. Be prepared to lose and recreate data frequently.

In a multi-tenant application, login to every tenant to let XAF automatically update that tenant’s database schema.

Limitations

The database schema update mechanism is based on the standard functionality of EF Core. EF Core limitations are reflected in the update mechanism.

• If a table contains data, table update can fail. For instance, if you change a column type and it does not match the type of existing data.
• The XAF automatic update mechanism has the same scenario limitations as the functionality of standard EF Core migrations.
• If you want to use EF Core migrations, automatic database schema updates cannot be active.

Disable Automatic Updates

You can disable automatic database schema updates in the following ways:

• Disable the DatabaseUpdateMode option:
  File: MySolution.Blazor.Server\Startup.cs or MySolution.Win\Startup.cs

  XafApplication.DatabaseUpdateMode = DatabaseUpdateMode.None;
  

• Disable schema updates for a particular object space provider in ApplicationBuilder:
  File: MySolution.Blazor.Server\BlazorApplication.cs or MySolution.Win\Program.cs

  builder.ObjectSpaceProviders
      .AddEFCore(options => options.SchemaUpdateOptions.DisableUpdateSchema = true)
      .WithDbContext<...>(...)
      // ...
  

EF Core Migrations

Note

If you use EF Core migrations in your project, disable the automatic database schema update since it can disrupt migrations.

Migrations are native to EF Core. They allow you to manually update the database schema and keep it in sync with the application’s data model while preserving existing data.

Before you run the application for the first time, or anytime after you change the data model, you need to generate a migration and then apply it to the database.

Set Up Migrations

Important

Delete the existing database (if there is one) before you proceed, because Entity Framework Core does not take the existing database schema into consideration when it generates the first migration.

1. Add the Microsoft.EntityFrameworkCore.Tools NuGet package to the YourProjectName.Module project and build the solution.

   The package’s version must match the version of Entity Framework Core supported in XAF. You can find the currently supported EF Core package versions in the following help topic: Supported EF Core Versions. To locate the version you use, check the Microsoft.EntityFrameworkCore package - a dependency of the YourProjectName.Module project.

2. In the YourProjectName.Module project, go to the BusinessObjects folder and open the YourProjectNameDbContext.cs file. Replace the declaration of the YourProjectNameDesignTimeDbContextFactory class with the following code snippet:

   namespace YourProjectName.Module.BusinessObjects;
   //...
   public class YourProjectNameDesignTimeDbContextFactory : DesignTimeDbContextFactory<YourProjectNameDbContext> {
      protected override string ConnectionString  => 
        "Integrated Security=SSPI;Pooling=false;Data Source=(localdb)\\mssqllocaldb;Initial Catalog=YourProjectName";
      }
   }
   

3. In Visual Studio, open the Package Manager Console and use the following command to add a migration:

   add-migration MyInitialMigrationName -StartupProject "YourProjectName.Module" -Project "YourProjectName.Module"
   

4. Update the database with the following command:

   update-database -StartupProject "YourProjectName.Module" -Project "YourProjectName.Module"
   

   Note that in a multi-tenant application, you should apply a migration to every tenant database. Refer to the following topic for additional details: Use EF Core Migrations to Update the Database Schema in Multi-Tenant Applications.

Update the database if you add, rename, or delete a class/property, or if you otherwise change the data model in your application. To do this, repeat steps 3 and 4 of this tutorial. Make sure to use a unique migration name for each new migration.