---
title: Admin UI Migrations
---

## Migrating IdentityServer and ASP.NET Identity Core to AdminUI

If you have an existing IdentityServer or ASP.NET Identity Core setup then you will need to run script based migrations on their respective databases before being able to apply the AdminUI migrations. The scripts are only 
available for SqlServer and would need to be modified to run for PostgreSql or MySql.

**Before running the migrations scripts you will need to backup your databases as there is no rollback script available from this point.**

To migrate your ASP.NET Identity Core schema to then be able to run further migrations you can use the script found here: [Migration script](https://github.com/RockSolidKnowledge/AdminUI.SchemaMigration/blob/master/MigrateDefaultAspNetIdentityToAdminUiSchema.sql).

This script should work with ASP.NET Identity Core 8.0, 7.0, 6.0, 5.0, and 3.1.

This requires you to have all AspNetUserClaims records to have a ClaimType value and will add columns and tables to your database. Once the script has finished running you can apply the Identity migration from the **AdminUI Migrations** section.

To migrate your IdentityServer schema to then be able to run further migrations you can use the script found here: [Migration script](https://github.com/RockSolidKnowledge/AdminUI.SchemaMigration/blob/master/MigrateDefaultIdentityServerToAdminUiSchema.sql).

Identity Server schema migration script will work for all versions of IdentityServer up to v7. If you are migrating to earlier versions of AdminUI and IdentityServer you may need to consult the below table for
modifications you may need to make to the migration history section if you want to use the AdminUI migration tool when upgrading to future versions.

| Version | Support | Migration History       |
| ------- | ------- | ------- |
| v4      | yes     | Comment out migration history after '20200702080430_V3toV4SqlServerOperationalDbMigration' line 104 |
| v5      | yes     | Comment out migration history after '20210602110024_PersistedGrantConsumeTimeSqlServerOperationalMigration' line 108 |
| v6      | yes     | Comment out migration history after '20230620153729_Duende63ConfigurationUpdate' line 113 |
| v7      | yes     | -- Nothing to do -- |

Once the script has finished running you can apply the Configuration, ExtendedConfiguration and Operational migrations from the **AdminUI Migrations** section.

## AdminUI Migrations

AdminUI comes with a tool to run all the necessary migrations. Alongside its own migrations, AdminUI can optionally run and maintain your IdentityServer and our Identity migrations, or you can handle them yourself. If you own SAML2P or WS-Fed, and wish to use its respective features within AdminUI, you will need to run their migrations.

By navigating to your AdminUI install directory and locating the IdentityExpress.Manager.UI.Duende.dll you can you run the dll using 

```language-bash
dotnet IdentityExpress.Manager.UI.Duende.dll -migrate <migration-to-run>
```

AdminUI has a number of different migrations that need to be run, you can run one individually or choose to run them all at once.

The different migrations options are:

|Migration Type|Description|
|---|---|
|All|Runs all the migrations (Recommended for Demo users)|
|IdentityServerOnly|Runs AdminUI migrations along with the IdentityServer migrations (Migrations: Configuration, Operational, ExtendedConfiguration, Audit, Saml, WsFed and DataProtection)|
|IdentityOnly|Runs AdminUI migrations along with the Identity migrations (Migrations: Identity, ExtendedConfiguration, Audit, Saml, WsFed and DataProtection)|
|AdminUI|Runs only AdminUI migrations (Migrations: ExtendedConfiguration, Audit, Saml, WsFed and DataProtection)|
|Configuration|IdentityServer4 Configuration Migration|
|ExtendedConfiguration|AdminUI IdentityServer4 extension|
|Operational|IdentityServer4 Operational migration|
|Identity|ASP Identity Migration|
|Audit|RSK AdminUI Audit Migration|
|Saml|SAML2P Component migration|
|WsFed|Ws-Federation Component migration|
|DataProtection|DataProtection Key Migration (used if protecting cookies with a Database)|

A help function may be accessed by adding -help 

Supported DbProviders

- `SqlServer`
- `MySql`
- `PostgreSql`

You may also specify a connection string and which database provider you are you using with -connectionstring and -dbprovider. The connection string must be valid and surrounded by quotes. If no connectionstring and dbprovider are given, the migration tool will look in AdminUI's appsettings.json for the values.

### Migration Arguments

- `-dbProvider`
    Allows you to override the configured dbProvider when running migrations, with the value provided following the argument
- `-connectionString`
    Allows you to override the configured database connection string with a value provided following the argument
- `-timeout`
    Allows you to customise the command timeout value used when running migrations

## Schema Checker 

AdminUI also comes with a tool that you can use to compare the expected IdentityServer database schema with your own IdentityServer schema.

By navigating to your AdminUI install directory and locating the IdentityExpress.Manager.UI.Duende.dll you can you run the dll using 

```language-bash
dotnet IdentityExpress.Manager.UI.Duende.dll -schema <schema-to-check>
```

The different schema options are:

|Migration Type|Description|
|---|---|
|Configuration|IdentityServer4 Configuration Migration|
|Operational|IdentityServer4 Operational migration|
|Identity|ASP Identity Migration|
|Audit|RSK AdminUI Audit Migration|
|DataProtection|DataProtection Key Migration (used if protecting cookies with a Database)|

A help function may be accessed by adding -help 

Supported DbProviders

- `SqlServer`
- `MySql`
- `PostgreSql`

After performing the schema check on the specified schema, a JSON encoded response object will be returned in the console. The object contains the following values: 'IsValid', 'Exists', 'ErrorMessages', 'SchemaType'. 

If the response object's 'Exists' value is true, then the schema checker has identified that there are tables present in your database that relate to the schema it is checking.

The response object's 'IsValid' relates to if your database contains all the necessary tables and columns required for the schema you are checking. 'IsValid' is true when all tables and columns exist for a schema, and also when no tables and columns exist for a schema.

The 'ErrorMessages' section of the response object will contain information relating to any missing tables or columns in your database when compared to the schema you are checking.

You may also specify a connection string and which database provider you are you using with -connectionstring and -dbprovider. The connection string must be valid and surrounded by quotes. If no connectionstring and dbprovider are given, the migration tool will look in AdminUI's appsettings.json for the values.

### Schema Check Arguments

- `-dbProvider`
    Allows you to override the configured dbProvider when running migrations, with the value provided following the argument
- `-connectionString`
    Allows you to override the configured database connection string with a value provided following the argument

## Docker Migrations

If the container is not running and you would like to run migrations use the following command

```language-bash
docker run -e "DbProvider=<YourProvider>" -e "IdentityConnectionString=<YourConnectionString>" -e IdentityServerConnectionString="<YourConnectionString>" --entrypoint dotnet rocksolidknowledge/adminui IdentityExpress.Manager.UI.Duende.dll -migrate all
```
Note - The full list of configuration options is avaliable [here](../Configuration_and_Integration/Configuring_AdminUI.md)

If the container is already running the steps to run migrations are as follows:

- Find the container ID by running the “docker container ps” command
- Once found, you can exec the command as follows:

```language-bash
docker exec <container-id> dotnet IdentityExpress.Manager.UI.Duende.dll -migrate all
```

Note - This will use the environment variables already passed into the container.

You will see the output of the migrations in your command line window.

## TargetIdentityServer4

**Make sure to back up your database before running any migrations against it as there is no way to easily revert changes once they have been applied.**

The value of the `TargetIdentityServer4` flag in AdminUI's configuration will determine what kind of database the AdminUI migrations will create/update. 

If set to `true`, the AdminUI migration tool will perform IdentityServer4 migrations. 

If set to `false`, the AdminUI migration tool will perform Duende IdentityServer migrations. 

If you have performed the AdminUI migrations while targeting IdentityServer4 but wish to upgrade your database to target IdentityServer Duende, you can update the `TargetIdentityServer4` flag to `false` and run the migrations again. The AdminUI migration tool will then update your database to be in line with the latest Duende IdentityServer schema. 

## Running Migrations with a Custom Database Schema

AdminUI supports running migrations with a custom database schema in SqlServer and PostgreSql. The schema configuration must be set at the database level rather than in the application configuration.

### Setup Steps

To configure a custom schema:

1. **Create the database and custom schema**
   
   Create your database and define the custom schema within it.

#### PostgreSql

2. **Add the custom schema to your connections string using `Search Path`**

    Example: `"Server=localhost; Port=5433; Uid=MyUserName;Pwd=Password123!;Database=MyDatabase;Search Path=MyCustomSchema;"`

#### SqlServer

2. **Configure a database user**
   
   Create a database user and assign the custom schema as the user's default schema.

3. **Update your connection string**
   
   Use the configured user in your AdminUI database connection string.

When using SQL Server, be aware of the following limitation:

- **Users with `sysadmin` role cannot use custom default schemas**
  
  If your database user is assigned the `sysadmin` fixed server role, SQL Server will ignore the default schema setting and always use `dbo`. This is a SQL Server limitation, not an AdminUI restriction.
  
  To use a custom schema, ensure your database user does not have the `sysadmin` role. Instead, grant only the specific permissions required for running migrations and operating AdminUI.

For more information, see [Microsoft's ALTER USER documentation](https://learn.microsoft.com/en-us/sql/t-sql/statements/alter-user-transact-sql?view=sql-server-ver17#remarks).