3步搞定MAUI应用SQLite数据库迁移：从崩溃到平滑升级-优快云博客

3步搞定MAUI应用SQLite数据库迁移：从崩溃到平滑升级

【免费下载链接】maui dotnet/maui: .NET MAUI (Multi-platform App UI) 是.NET生态下的一个统一跨平台应用程序开发框架，允许开发者使用C#和.NET编写原生移动和桌面应用，支持iOS、Android、Windows等操作系统。项目地址: https://gitcode.com/GitHub_Trending/ma/maui

你是否遇到过MAUI应用更新后，用户反馈数据丢失或应用崩溃？这很可能是SQLite数据库结构（Schema）变更导致的不兼容问题。本文将通过实际案例，教你如何在MAUI应用中实现安全可靠的数据库迁移，让用户无缝过渡到新版本。读完本文你将掌握：版本跟踪机制设计、无停机迁移实现、数据完整性保障技巧。

理解MAUI中的SQLite挑战

MAUI（Multi-platform App UI）作为跨平台开发框架，其本地数据存储通常依赖SQLite数据库。与服务器数据库不同，移动端SQLite数据库存储在用户设备上，直接修改可能导致：

旧版本应用无法读取新结构数据
新版本应用无法处理旧结构数据
极端情况下导致数据损坏或丢失

项目模板中提供了基础的SQLite使用示例，如src/Templates/src/templates/maui-mobile/Data/TaskRespository.cs所示，通过SqliteConnection创建和操作数据库表。但基础实现缺少版本管理和迁移机制，这正是多数开发者遇到的"升级陷阱"。

实现数据库版本跟踪

版本标识设计

首先需要为数据库添加版本标识。修改src/Templates/src/templates/maui-mobile/Data/Constants.cs，添加数据库版本常量：

public static class Constants
{
    public const string DatabaseFilename = "AppSQLite.db3";
    public const int DatabaseVersion = 2; // 初始版本为1，升级后递增
    
    public static string DatabasePath =>
        $"Data Source={Path.Combine(FileSystem.AppDataDirectory, DatabaseFilename)};Version={DatabaseVersion}";
}

版本表创建

在数据库初始化时创建版本跟踪表，修改TaskRespository.cs的Init方法：

private async Task Init()
{
    if (_hasBeenInitialized)
        return;

    await using var connection = new SqliteConnection(Constants.DatabasePath);
    await connection.OpenAsync();

    // 创建版本表
    var createVersionTableCmd = connection.CreateCommand();
    createVersionTableCmd.CommandText = @"
        CREATE TABLE IF NOT EXISTS DatabaseVersion (
            Version INTEGER PRIMARY KEY NOT NULL
        );";
    await createVersionTableCmd.ExecuteNonQueryAsync();

    // 检查当前版本
    var getVersionCmd = connection.CreateCommand();
    getVersionCmd.CommandText = "SELECT Version FROM DatabaseVersion LIMIT 1";
    var currentVersion = await getVersionCmd.ExecuteScalarAsync() as long?;
    
    if (!currentVersion.HasValue)
    {
        // 新数据库，插入初始版本
        var insertVersionCmd = connection.CreateCommand();
        insertVersionCmd.CommandText = "INSERT INTO DatabaseVersion (Version) VALUES (@version)";
        insertVersionCmd.Parameters.AddWithValue("@version", Constants.DatabaseVersion);
        await insertVersionCmd.ExecuteNonQueryAsync();
    }
    else if (currentVersion < Constants.DatabaseVersion)
    {
        // 需要执行迁移
        await PerformMigration(connection, currentVersion.Value);
        // 更新版本号
        var updateVersionCmd = connection.CreateCommand();
        updateVersionCmd.CommandText = "UPDATE DatabaseVersion SET Version = @version";
        updateVersionCmd.Parameters.AddWithValue("@version", Constants.DatabaseVersion);
        await updateVersionCmd.ExecuteNonQueryAsync();
    }

    // 其余表初始化代码...
    _hasBeenInitialized = true;
}

执行安全的数据库迁移

迁移方法实现

添加迁移执行方法，处理不同版本间的结构变更：

private async Task PerformMigration(SqliteConnection connection, long currentVersion)
{
    _logger.LogInformation($"Migrating database from version {currentVersion} to {Constants.DatabaseVersion}");
    
    // 版本1到版本2的迁移示例：添加DueDate字段
    if (currentVersion == 1 && Constants.DatabaseVersion == 2)
    {
        var alterTableCmd = connection.CreateCommand();
        alterTableCmd.CommandText = "ALTER TABLE Task ADD COLUMN DueDate TEXT";
        await alterTableCmd.ExecuteNonQueryAsync();
        
        // 可以添加数据转换逻辑
    }
    
    // 后续版本迁移可以继续添加if-else块
}

迁移事务管理

为确保迁移过程中的数据安全，使用事务包装所有迁移操作：

private async Task PerformMigration(SqliteConnection connection, long currentVersion)
{
    using var transaction = await connection.BeginTransactionAsync();
    try
    {
        // 迁移逻辑...
        
        await transaction.CommitAsync();
        _logger.LogInformation("Database migration completed successfully");
    }
    catch (Exception ex)
    {
        await transaction.RollbackAsync();
        _logger.LogError(ex, "Database migration failed");
        throw; // 传播异常，让应用知道迁移失败
    }
}

高级迁移场景处理

复杂表结构变更

对于需要重命名列或表的复杂变更，推荐采用"创建-复制-删除-重命名"模式：

// 复杂迁移示例：重命名列
var createTempTableCmd = connection.CreateCommand();
createTempTableCmd.CommandText = @"
    CREATE TABLE Task_Temp AS SELECT ID, Title, IsCompleted, ProjectID, DueDate AS DueDateTime FROM Task;
    DROP TABLE Task;
    ALTER TABLE Task_Temp RENAME TO Task;";
await createTempTableCmd.ExecuteNonQueryAsync();

迁移状态记录

对于大型数据库迁移，可添加迁移状态跟踪，实现断点续传：

// 创建迁移状态表
var createMigrationStatusTableCmd = connection.CreateCommand();
createMigrationStatusTableCmd.CommandText = @"
    CREATE TABLE IF NOT EXISTS MigrationStatus (
        MigrationId TEXT PRIMARY KEY NOT NULL,
        Completed INTEGER NOT NULL DEFAULT 0,
        CompletedAt TEXT
    );";
await createMigrationStatusTableCmd.ExecuteNonQueryAsync();

迁移测试与验证

测试策略

推荐的迁移测试流程：

使用实际用户数据样本创建测试环境
备份测试数据
执行迁移
验证数据完整性
测试回滚机制
在各种版本组合间测试

数据验证

迁移后验证关键数据：

private async Task VerifyMigration(SqliteConnection connection)
{
    var verifyCmd = connection.CreateCommand();
    verifyCmd.CommandText = "SELECT COUNT(*) FROM Task WHERE DueDate IS NOT NULL";
    var count = await verifyCmd.ExecuteScalarAsync() as long?;
    _logger.LogInformation($"Migration verification: {count} records updated with DueDate");
    
    // 可以添加更多验证逻辑
}

完整迁移流程总结

mermaid

通过以上步骤，你的MAUI应用现在具备了安全可靠的数据库迁移能力。记住迁移设计的黄金法则：

始终备份数据
小步增量迁移
完善日志记录
全面测试验证

项目中更多SQLite使用示例可参考src/Essentials/src/Contacts/Contacts.android.cs等文件，了解不同平台下的数据库操作实现。数据库迁移是应用生命周期管理的重要组成部分，良好的迁移策略能显著提升用户体验和应用可靠性。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考