使用 H2 應用程式資料庫或從其遷移

您已安裝 Metabase，但是

• 您嘗試將應用程式資料庫從 H2 遷移到另一個資料庫，但發生錯誤，
• 您嘗試降級而不是升級，
• 當您嘗試執行 Metabase 時，Metabase 記錄了 liquibase 錯誤訊息，
• Metabase 在執行時記錄了另一個錯誤訊息，其中提及 H2 或 h2，或
• 您使用的是 Windows 10，並收到有關檔案權限的警告。

您目前是否使用 H2 作為您的應用程式資料庫？

根本原因： Metabase 將有關使用者、問題等的資訊儲存在其自身的資料庫中，稱為「應用程式資料庫」或簡稱「app database」。預設情況下，Metabase 使用 H2 作為應用程式資料庫，但我們不建議在生產環境中使用，因為它是磁碟上的資料庫，因此對檔案系統錯誤（例如磁碟機損壞或檔案未正確刷新）很敏感。

採取步驟

1. 若要檢查您正在使用哪個應用程式資料庫，請前往 管理面板，開啟 疑難排解 標籤，向下捲動至「診斷資訊」，並在顯示的 JSON 中尋找 application-database 金鑰。
2. 請參閱 從 H2 遷移 以取得有關如何遷移到更穩健的應用程式資料庫的說明。

您是否嘗試將應用程式資料庫從 H2 遷移到其他資料庫？

根本原因： 您嘗試使用 load-from-h2 命令將應用程式資料庫從 H2 遷移到生產資料庫（例如 PostgreSQL 或 MySQL/MariaDB），但由於資料庫檔案名稱不正確而失敗，並顯示類似以下的錯誤訊息

Command failed with exception: Unsupported database file version or invalid file header in file <YOUR FILENAME>

採取步驟

1. 建立已匯出的 H2 資料庫副本（請參閱 備份 Metabase 應用程式資料）。在完成此操作之前，請勿繼續，以防發生任何錯誤。

2. 檢查您匯出的 H2 資料庫檔案是否名為 metabase.db.mv.db。

3. H2 會自動將 .mv.db 副檔名新增至您在命令列上指定的資料庫路徑，因此請確保您傳遞給命令的 DB 檔案路徑不包含 .mv.db 副檔名。例如，如果您已匯出應用程式資料庫，並且想要使用 load-from-h2 將資料從該 H2 資料庫載入到 PostgreSQL 資料庫中，則您的命令看起來會像這樣

   export MB_DB_TYPE=postgres
   export MB_DB_DBNAME=metabase
   export MB_DB_PORT=5432
   export MB_DB_USER=<username>
   export MB_DB_PASS=<password>
   export MB_DB_HOST=localhost
   java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar load-from-h2 /path/to/metabase.db # do not include .mv.db
   

如果您使用的是 Pro 或 Enterprise 版本的 Metabase，則可以使用序列化來快照您的應用程式資料庫。當您想要在新 Metabase 實例中預先載入問題和儀表板時，序列化非常有用。

您是否嘗試降級？

根本原因： Metabase 不支援降級（即還原到應用程式的早期版本）。

採取步驟

1. 關閉 Metabase。
2. 還原您在嘗試升級或降級之前建立的應用程式資料庫備份副本。
3. 還原您要還原的舊版本 JAR 檔案或容器。
4. 重新啟動 Metabase。

應用程式資料庫是否已鎖定？

根本原因： 有時 Metabase 無法啟動，因為在先前的執行期間未正確清除應用程式資料庫鎖定。錯誤訊息看起來像這樣

liquibase.exception.DatabaseException: liquibase.exception.LockException: Could not acquire change log lock.

採取步驟

1. 在安裝 Metabase 的伺服器上開啟 shell，並手動執行以下命令清除鎖定

   java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar migrate release-locks
   

2. 此命令完成後，正常重新啟動您的 Metabase 實例（不帶 migrate release-locks 標誌）。

應用程式資料庫是否已損壞？

根本原因： H2 的可靠性不如生產品質的資料庫管理系統，有時資料庫本身會損壞。這可能會導致應用程式資料庫中的資料遺失，但不會損壞 Metabase 連接的資料庫中的資料。

採取步驟： 錯誤訊息可能會因應用程式資料庫損壞的方式而異，但在大多數情況下，日誌訊息會提及 h2。典型的命令和訊息如下

myUser@myIp:~$ java --add-opens java.base/java.nio=ALL-UNNAMED -cp metabase.jar org.h2.tools.RunScript -script whatever.sql -url jdbc:h2:~/metabase.db
Exception in thread "main" org.h2.jdbc.JdbcSQLException: Row not found when trying to delete from index """"".I37: ( /* key:7864 */ X'5256470012572027c82fc5d2bfb855264ab45f8fec4cf48b0620ccad281d2fe4', 165)" [90112-194]
    at org.h2.message.DbException.getJdbcSQLException(DbException.java:345)
    [etc]

如何修復： 並非所有 H2 錯誤都可以復原（這就是為什麼如果您使用 H2，請為應用程式資料庫檔案制定備份策略）。

如果您執行的是最新版本並使用 H2，則應用程式資料庫會儲存在 metabase.db.mv.db 中。 - 在 Metabase 實例執行的伺服器上開啟 shell，並嘗試執行以下四個命令來恢復損壞的 H2 檔案

java -cp metabase.jar org.h2.tools.Recover

mv metabase.db.mv.db metabase-old.db.mv.db

touch metabase.db.mv.db

java --add-opens java.base/java.nio=ALL-UNNAMED -cp target/uberjar/metabase.jar org.h2.tools.RunScript -script metabase.db.h2.sql -url jdbc:h2:`pwd`/metabase.db

您是否在 Windows 10 上使用 H2 執行 Metabase？

根本原因： 在 Windows 10 上的某些情況下，Metabase JAR 需要具有建立應用程式資料庫本機檔案的權限。執行 JAR 時，您會看到類似以下的錯誤訊息

Exception in thread "main" java.lang.AssertionError: Assert failed: Unable to connect to Metabase DB.

採取步驟

1. 在 Metabase JAR 檔案上按一下滑鼠右鍵（不是應用程式資料庫檔案）。
2. 選取「內容」。
3. 選取「解除封鎖」。

應用程式資料庫載入時間是否過長？

根本原因： 您正在使用 H2 作為您的應用程式資料庫，並且應用程式資料庫太大，以至於無法在 5 秒內載入（這是預設逾時值）。當您嘗試啟動 Metabase 時，您會在主控台中看到訊息「Timeout」。

採取步驟

1. 使用生產級品質的資料庫（例如 PostgreSQL）作為應用程式資料庫（首選）。
2. 前往管理面板並增加應用程式資料庫的逾時設定。
3. 將 Metabase 移至更快的伺服器（尤其是具有更快磁碟的伺服器）。