diff --git a/docs/en/Data-Seeding.md b/docs/en/Data-Seeding.md index 0b424e7e0d..3b8e878a4f 100644 --- a/docs/en/Data-Seeding.md +++ b/docs/en/Data-Seeding.md @@ -1,3 +1,73 @@ # Data Seeding +## Introduction + +Some applications (or modules) using a database may need to have some **initial data** to be able to properly start and run. For example, an **admin user** & roles must be available at the beginning. Otherwise you can not **login** to the application to create new users and roles. + +Data seeding is also useful for [testing](Testing.md) purpose, so your automatic tests can assume some initial data available in the database. + +### Why a Data Seed System? + +While EF Core Data Seeding system provides a way, it is very limited and doesn't cover production scenarios. Also, it is only for EF Core. + +ABP Framework provides a data seed system that is; + +* **Modular**: Any [module](Module-Development-Basics.md) can silently contribute to the data seeding process without knowing and effecting each other. In this way, a module seeds its own initial data. +* **Database Independent**: It is not only for EF Core, it also works for other database providers (like [MongoDB](MongoDB.md)). +* **Production Ready**: It solves the problems on production environments. See the "*On Production*" section below. +* **Dependency Injection**: It takes the full advantage of dependency injection, so you can use any internal or external service while seeding the initial data. Actually, you can do much more than data seeding. + +## IDataSeeder + +`IDataSeeder` is the main service that is used to seed initial data. It is pretty easy to use; + +````csharp +public class MyService : ITransientDependency +{ + private readonly IDataSeeder _dataSeeder; + + public MyService(IDataSeeder dataSeeder) + { + _dataSeeder = dataSeeder; + } + + public async Task FooAsync() + { + await _dataSeeder.SeedAsync(); + } +} +```` + +You can [inject](Dependency-Injection.md) the `IDataSeeder` and use it to seed the initial data. We will see the *IDataSeedContributor* section below to learn how to insert data. But before that, we should understand that: Where & how to execute the `IDataSeeder.SeedAsync()`? + +### On Production + +The [application startup template](Startup-Templates/Application.md) comes with a *YourProjectName***.DbMigrator** project (Acme.BookStore.DbMigrator on the picture below), which is a **console application** that is responsible to **migrate** the database schema (for relational databases) and **seed** the initial data: + +![bookstore-visual-studio-solution-v3](images/bookstore-visual-studio-solution-v3.png) + +This console application is properly configured for you. It even supports **multi-tenant** scenarios where each tenant has its own database (migrates & seeds all necessary databases). + +It is expected to run this DbMigrator application whenever you **deploy a new version** of your solution to the server. It will migrate your **database schema** (create new tables/fields... etc.) and **seed new initial data** needed to properly run the new version of your solution. Then you can deploy/start your actual application. + +Even if you are using MongoDB or another NoSQL database, it is recommended to use the DbMigrator application to seed your data or perform your data migration. + +Having such a separate console application has several advantages; + +* You can run it before updating your application, so your application will run on the ready database. +* Your application starts faster compared to if it seeds the initial data itself. +* Your application can properly run on a clustered environment (where multiple instances of your application run concurrently). If you seed data on application startup you would have conflicts in this case. + +### On Development + +We suggest the same way on development. Run the DbMigrator console application whenever you [create a database migration](https://docs.microsoft.com/en-us/ef/ef6/modeling/code-first/migrations/) (using EF Core `Add-Migration` command, for example) or change the data seed code (will be explained later). + +You can continue to use the standard `Update-Database` command for EF Core, but it will not seed if you've created a new seed data. + +### On Testing + +TODO + +## IDataSeedContributor + TODO \ No newline at end of file