entity-framework/core/modeling/data-seeding.md
Data seeding is the process of populating a database with an initial set of data.
There are several ways this can be accomplished in EF Core:
UseSeeding)HasData)<a name="use-seeding-method"></a>
UseSeeding and UseAsyncSeeding methodsEF 9 introduced xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* methods, which provide a convenient way of seeding the database with initial data. These methods aim to improve the experience of using custom initialization logic (explained below). They provide one clear location where all the data seeding code can be placed. Moreover, the code inside xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* methods is protected by the migration locking mechanism to prevent concurrency issues.
The new seeding methods are called as part of xref:Microsoft.EntityFrameworkCore.Storage.IDatabaseCreator.EnsureCreated* operation, xref:Microsoft.EntityFrameworkCore.RelationalDatabaseFacadeExtensions.Migrate* and dotnet ef database update command, even if there are no model changes and no migrations were applied.
[!TIP] Using xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* is the recommended way of seeding the database with initial data when working with EF Core.
These methods can be set up in the options configuration step. Here is an example:
[!code-csharpContextOptionSeeding]
[!NOTE] xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* is called from the xref:Microsoft.EntityFrameworkCore.Storage.IDatabaseCreator.EnsureCreated* method, and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* is called from the xref:Microsoft.EntityFrameworkCore.Storage.IDatabaseCreator.EnsureCreatedAsync* method. When using this feature, it is recommended to implement both xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* methods using similar logic, even if the code using EF is asynchronous. EF Core tooling currently relies on the synchronous version of the method and will not seed the database correctly if the xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* method is not implemented.
<a name="custom-initialization-logic"></a>
A straightforward and powerful way to perform data seeding is to use xref:Microsoft.EntityFrameworkCore.DbContext.SaveChangesAsync* before the main application logic begins execution. It is recommended to use xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* for that purpose, however sometimes using these methods is not a good solution. An example scenario is when seeding requires using two different contexts in one transaction. Below is a code sample performing custom initialization in the application directly:
[!code-csharpMain]
[!WARNING] The seeding code should not be part of the normal app execution as this can cause concurrency issues when multiple instances are running and would also require the app having permission to modify the database schema.
Depending on the constraints of your deployment the initialization code can be executed in different ways:
This can usually be automated by using publish profiles.
<a name="model-seed-data"></a>
Data can also be associated with an entity type as part of the model configuration. Then, EF Core migrations can automatically compute what insert, update or delete operations need to be applied when upgrading the database to a new version of the model.
[!WARNING] Migrations only considers model changes when determining what operation should be performed to get the managed data into the desired state. Thus any changes to the data performed outside of migrations might be lost or cause an error.
As an example, this will configure managed data for a Country in OnModelCreating:
[!code-csharpCountrySeed]
To add entities that have a relationship the foreign key values need to be specified:
[!code-csharpCitySeed]
When managing data for many-to-many navigations, the join entity needs to be configured explicitly. If the entity type has any properties in shadow state (e.g. the LanguageCountry join entity below), an anonymous class can be used to provide the values:
[!code-csharpLanguageSeed]
Owned entity types can be configured in a similar fashion:
[!code-csharpLanguageDetailsSeed]
See the full sample project for more context.
Once the data has been added to the model, migrations should be used to apply the changes.
[!TIP] If you need to apply migrations as part of an automated deployment you can create a SQL script that can be previewed before execution.
Alternatively, you can use xref:Microsoft.EntityFrameworkCore.Infrastructure.DatabaseFacade.EnsureCreatedAsync* to create a new database containing the managed data, for example for a test database or when using the in-memory provider or any non-relational database. Note that if the database already exists, xref:Microsoft.EntityFrameworkCore.Infrastructure.DatabaseFacade.EnsureCreatedAsync* will neither update the schema nor managed data in the database. For relational databases you shouldn't call xref:Microsoft.EntityFrameworkCore.Infrastructure.DatabaseFacade.EnsureCreatedAsync* if you plan to use Migrations.
[!NOTE] Populating the database using the xref:Microsoft.EntityFrameworkCore.Metadata.Builders.EntityTypeBuilder`1.HasData* method used to be referred to as "data seeding". This naming sets incorrect expectations, as the feature has a number of limitations and is only appropriate for specific types of data. That is why we decided to rename it to "model managed data". xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* methods should be used for general purpose data seeding.
This type of data is managed by migrations and the script to update the data that's already in the database needs to be generated without connecting to the database. This imposes some restrictions:
Therefore this feature is most useful for static data that's not expected to change outside of migrations and does not depend on anything else in the database, for example ZIP codes.
If your scenario includes any of the following it is recommended to use xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseSeeding* and xref:Microsoft.EntityFrameworkCore.DbContextOptionsBuilder.UseAsyncSeeding* methods described in the first section:
DateTime.Now.<a name="manual-migration-customization"></a>
When a migration is added the changes to the data specified with xref:Microsoft.EntityFrameworkCore.Metadata.Builders.EntityTypeBuilder`1.HasData* are transformed to calls to InsertData(), UpdateData(), and DeleteData(). One way of working around some of the limitations of xref:Microsoft.EntityFrameworkCore.Metadata.Builders.EntityTypeBuilder`1.HasData* is to manually add these calls or custom operations to the migration instead.
[!code-csharpCustomInsert]