How to Change the Database Type

EasyAdminBlazor uses FreeSql for data access. The template defaults to SQLite (Data Source=easyadminblazor.db), so it runs without any setup. To switch to MySQL, SQL Server, PostgreSQL, or another database, change three things:

  1. Install the matching FreeSql provider package;
  2. Change DataType in Program.cs;
  3. Update the connection string in appsettings.json.

See the FreeSql official documentation for more database adapters.

1. Default Template Configuration

The generated Program.cs configures FreeSql like this:

FreeSqlBuilder = a => a
    .UseConnectionString(DataType.Sqlite, configuration["ConnectionStrings:default"])
    .UseMonitorCommand(cmd => System.Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {cmd.CommandText}\r\n"))
    .UseAutoSyncStructure(true)

And appsettings.json:

{
  "ConnectionStrings": {
    "Default": "Data Source=easyadminblazor.db"
  }
}

To switch databases, update DataType and the connection string together, and install the matching provider package.

2. Supported Databases

Database DataType NuGet package Connection string example
SQLite (template default) DataType.Sqlite FreeSql.Provider.Sqlite Data Source=easyadminblazor.db
MySQL / MariaDB DataType.MySql FreeSql.Provider.MySqlConnector (recommended) Data Source=127.0.0.1;Port=3306;User ID=root;Password=your_password;Initial Catalog=yourdb;Charset=utf8mb4;SslMode=none
SQL Server DataType.SqlServer FreeSql.Provider.SqlServer Data Source=localhost;User Id=sa;Password=your_password;Initial Catalog=yourdb;Encrypt=True;TrustServerCertificate=True
PostgreSQL DataType.PostgreSQL FreeSql.Provider.PostgreSQL Host=localhost;Port=5432;Database=yourdb;Username=postgres;Password=your_password
Oracle DataType.Oracle FreeSql.Provider.Oracle See FreeSql documentation
Others / domestic databases See FreeSql docs See FreeSql docs See FreeSql documentation

Tip: FreeSql.Provider.MySqlConnector is built on the open-source community driver and is the recommended option in the FreeSql docs. The official MySQL driver is available as FreeSql.Provider.MySql.

3. Step-by-Step (Switch to MySQL as an Example)

Step 1: Replace the NuGet package

Run these commands in the project root:

# Optional: remove the SQLite provider that the template includes
dotnet remove package FreeSql.Provider.Sqlite

# Install the provider for the target database
dotnet add package FreeSql.Provider.MySqlConnector

For another database, use its package instead:

dotnet add package FreeSql.Provider.SqlServer     # SQL Server
dotnet add package FreeSql.Provider.PostgreSQL    # PostgreSQL
dotnet add package FreeSql.Provider.Oracle        # Oracle

Step 2: Update Program.cs

Change DataType.Sqlite to DataType.MySql in the FreeSqlBuilder:

FreeSqlBuilder = a => a
    .UseConnectionString(DataType.MySql, configuration["ConnectionStrings:default"])
    .UseMonitorCommand(cmd => System.Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {cmd.CommandText}\r\n"))
    .UseAutoSyncStructure(true)

Step 3: Update the connection string

Change appsettings.json to use the target database:

{
  "ConnectionStrings": {
    "Default": "Data Source=127.0.0.1;Port=3306;User ID=root;Password=your_password;Initial Catalog=yourdb;Charset=utf8mb4;SslMode=none"
  }
}

In production, avoid committing the database password. Override it with an environment variable such as ConnectionStrings__Default=....

Step 4: Start and verify

  1. Create an empty database (e.g. yourdb) on the database server first. SQLite creates the .db file automatically, so this step is not needed for SQLite;
  2. In development, keep UseAutoSyncStructure(true). On first startup, EasyAdminBlazor syncs the schema and initializes the default administrator (admin / 123yyq);
  3. Start the app, sign in, and check that login, menus, and user management work normally;
  4. After verification, publish following the Deployment guide. Set UseAutoSyncStructure to false in production.

4. What About Existing SQLite Data?

Switching the database type does not migrate existing data automatically. If you already have business data:

  • For small amounts of data, export the tables with a SQLite tool and import them into the new database;
  • For larger data sets, use a dedicated migration or ETL tool;
  • If the project is still new with no real business data, just switch the database and let the first run create the tables.

5. FAQ

“Cannot connect to the database” on startup

  • Confirm the target database service is running;
  • Check the account, password, port, and database name;
  • Confirm appsettings.json or the environment variable points to the connection string you just changed;
  • For remote databases, check the firewall and security group.

Garbled Chinese text in MySQL

Add Charset=utf8mb4 to the connection string, and make sure the database itself uses the utf8mb4 character set.

SQL Server certificate error

For local/test environments with self-signed certificates, add TrustServerCertificate=True to the connection string.

I installed several provider packages

That does not conflict. The database actually used is decided by DataType in Program.cs. It is still a good idea to remove providers you do not need to keep the publish output smaller.

“No type mapping found” error

Usually the installed package and DataType do not match, or Program.cs still uses DataType.Sqlite. Check both against the table above.