From 063bf1721f3939b27ecac407c42cd528fcf1ecab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 2 Jan 2020 11:05:28 +0300 Subject: [PATCH] Complete the Connection Strings document --- docs/en/Best-Practices/Index.md | 2 +- docs/en/Connection-Strings.md | 67 +++++++++++++++++++++++++++++---- docs/en/docs-nav.json | 41 ++++++++++++-------- 3 files changed, 86 insertions(+), 24 deletions(-) diff --git a/docs/en/Best-Practices/Index.md b/docs/en/Best-Practices/Index.md index 1a48c6b46b..f3f626ca63 100644 --- a/docs/en/Best-Practices/Index.md +++ b/docs/en/Best-Practices/Index.md @@ -23,5 +23,5 @@ Also, this guide is mostly usable for general **application development**. * [Data Transfer Objects](Data-Transfer-Objects.md) * Data Access * [Entity Framework Core Integration](Entity-Framework-Core-Integration.md) - * [MongoDB Integration](MongoDB-Integration.md) + * [MongoDB Integration](MongoDB-Integration.md) diff --git a/docs/en/Connection-Strings.md b/docs/en/Connection-Strings.md index 36103011e1..a080e10dea 100644 --- a/docs/en/Connection-Strings.md +++ b/docs/en/Connection-Strings.md @@ -1,11 +1,64 @@ -# Data Access +# Connection Strings -ABP framework was designed as database agnostic, it can work any type of data source by the help of the [repository](Repositories.md) and [unit of work](Unit-Of-Work.md) abstractions. +ABP Framework is designed to be [modular](Module-Development-Basics.md), [microservice compatible](Microservice-Architecture.md) and [multi-tenancy](Multi-Tenancy.md) aware. Connection string management is also designed to support these scenarios; -However, currently the following providers are implements: +* Allows to set separate connection strings for every module, so every module can have its own physical database. Modules even might be configured to use different DBMSs. +* Allows to set separate connection string and use a separate database per tenant (in a SaaS application). -* [Entity Framework Core](Entity-Framework-Core.md) (works with [various DBMS and providers](https://docs.microsoft.com/en-us/ef/core/providers/?tabs=dotnet-core-cli).) -* [MongoDB](MongoDB.md) -* [Dapper](Dapper.md) +It also supports hybrid scenarios; -More providers might be added in the next releases. \ No newline at end of file +* Allows to group modules into databases (all modules into a single shared database, 2 modules to database A, 3 modules to database B, 1 module to database C and rest of the modules to database D... etc.) +* Allows to group tenants into databases, just like the modules. +* Allows to separate databases per tenant per module (which might be harder to maintain for you because of too many databases, but the ABP framework supports it). + +All the [pre-built application modules](Modules/Index.md) are designed to be compatible these scenarios. + +## Configure the Connection Strings + +See the following configuration: + +````json +"ConnectionStrings": { + "Default": "Server=localhost;Database=MyMainDb;Trusted_Connection=True;", + "AbpIdentityServer": "Server=localhost;Database=MyIdsDb;Trusted_Connection=True;", + "AbpPermissionManagement": "Server=localhost;Database=MyPermissionDb;Trusted_Connection=True;" +} +```` + +> ABP uses the `IConfiguration` service to get the application configuration. While the simplest way to write configuration into the `appsettings.json` file, it is not limited to this file. You can use environment variables, user secrets, Azure Key Vault... etc. See the [configuration](Configuration.md) document for more. + +This configuration defines three different connection strings: + +* `MyMainDb` (the `Default` connection string) is the main connection string of the application. If you don't specify a connection string for a module, it fallbacks to the `Default` connection string. The [application startup template](Startup-Templates/Application.md) is configured to use a single connection string, so all the modules uses a single shared database. +* `MyIdsDb` is used by the [IdentityServer](Modules/IdentityServer.md) module. +* `MyPermissionDb` is used by the [Permission Management](Modules/Permission-Management.md) module. + +[Pre-built application modules](Modules/Index.md) define constants for the connection string names. For example, the IdentityServer module defines a ` ConnectionStringName ` constant in the ` AbpIdentityServerDbProperties ` class (located in the ` Volo.Abp.IdentityServer ` namespace). Other modules similarly define constants, so you can investigate the connection string name. + +## Set the Connection String Name + +A module typically has a unique connection string name associated to its `DbContext` class using the `ConnectionStringName` attribute. Example: + +````csharp +[ConnectionStringName("AbpIdentityServer")] +public class IdentityServerDbContext + : AbpDbContext, IIdentityServerDbContext +{ +} +```` + +For [Entity Framework Core](Entity-Framework-Core.md) and [MongoDB](MongoDB.md), write this to your `DbContext` class (and the interface if it has). + +> If you are developing a reusable, database provider independent module see also [the best practices guide](Best-Practices/Index.md). + +## Database Migrations for the Entity Framework Core + +Relational databases require to create the database and the database schema (tables, views... etc.) before using it. + +The startup template (with EF Core ORM) comes with a single database and a `.EntityFrameworkCore.DbMigrations` project that contains the migration files for that database. This project mainly defines a *YourProjectName*MigrationsDbContext that calls the `Configure...()` methods of the used modules, like `builder.ConfigurePermissionManagement()`. + +Once you want to separate a module's database, you typically will need to create a second migration path. The easiest way to create a copy of the `.EntityFrameworkCore.DbMigrations` project with the `DbContext` inside it, change its content to only call the `Configure...()` methods of the modules needs to be stored in the second database and re-create the initial migration. In this case, you also need to change the `.DbMigrator` application to be able to work with these second database too. In this way, you will have a separate migrations DbContext per database. + +## Multi-Tenancy + +See [the multi-tenancy document](Multi-Tenancy.md) to learn how to use separate databases for tenants. \ No newline at end of file diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index f42a484b02..e7370a5d05 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -257,29 +257,38 @@ }, { "text": "Data Access", - "path": "Data-Access.md", + "path": "Data-Access.md", "items": [ { - "text": "Entity Framework Core Integration", - "path": "Entity-Framework-Core.md", + "text": "Connection Strings", + "path": "Connection-Strings.md" + }, + { + "text": "Database Providers", "items": [ { - "text": "Switch to MySQL", - "path": "Entity-Framework-Core-MySQL.md" + "text": "Entity Framework Core", + "path": "Entity-Framework-Core.md", + "items": [ + { + "text": "Switch to MySQL", + "path": "Entity-Framework-Core-MySQL.md" + }, + { + "text": "Switch to PostgreSQL", + "path": "Entity-Framework-Core-PostgreSQL.md" + } + ] }, - { - "text": "Switch to PostgreSQL", - "path": "Entity-Framework-Core-PostgreSQL.md" + { + "text": "MongoDB", + "path": "MongoDB.md" + }, + { + "text": "Dapper", + "path": "Dapper.md" } ] - }, - { - "text": "MongoDB Integration", - "path": "MongoDB.md" - }, - { - "text": "Dapper Integration", - "path": "Dapper.md" } ] },