Android App 升級機制：利用 SQLiteOpenHelper onUpgrade 實現資料庫結構遷移

核心概念

Android 以 DATABASE_VERSION 整數控制資料庫版本。當版本號增大時，框架自動呼叫 onUpgrade()，開發者在其中執行 DDL 遷移腳本。

實作步驟

1. 在 SQLiteOpenHelper 子類別中定義 DATABASE_VERSION 常數。
2. 釋出新版 APK 時，將版本號 +1（如 1 → 2）。
3. 覆寫 onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion)，根據版本差異執行對應 SQL。

程式碼範例

public class DBHelper extends SQLiteOpenHelper {
    private static final int DATABASE_VERSION = 2; // 升級為 2
    private static final String DATABASE_NAME = "EmployeeDB";

    @Override
    public void onCreate(SQLiteDatabase db) {
        db.execSQL("CREATE TABLE contacts (id INTEGER PRIMARY KEY, name TEXT, phone TEXT)");
    }

    @Override
    public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
        if (oldVersion < 2) {
            // v1 → v2：新增 email 欄位
            db.execSQL("ALTER TABLE contacts ADD COLUMN email TEXT DEFAULT ''");
        }
        if (oldVersion < 3) {
            // v2 → v3：建立索引
            db.execSQL("CREATE INDEX idx_contacts_name ON contacts(name)");
        }
        // 依此類推...
    }
}

注意事項

• onUpgrade 運行在交易中，任一 SQL 失敗會整體回滾。
• 避免在 onUpgrade 執行耗時操作（如大量資料轉換），建議啟動 IntentService 或 WorkManager 背景處理。
• 若需刪除整個資料庫重建，可在 onUpgrade 呼叫 context.deleteDatabase(name) 後再 onCreate(db)，但會丟失所有資料。
• 測試時可強制觸發：解除安裝 App 或清除儲存空間，再安裝新版。

APK 升級流程

1. 開發者發布新版 APK（versionCode +1）。
2. 使用者安裝更新（或商店自動更新）。
3. App 首次啟動時，SQLiteOpenHelper 偵測版本號變大，呼叫 onUpgrade。
4. 完成遷移後，App 正常運作於新結構。