如何從既有的 PostgreSQL 匯入資料到 ServBay

ServBay 是專為開發者設計的強大本地 Web 開發環境，整合多種語言環境、Web 伺服器與資料庫系統，包括 PostgreSQL。若您在 ServBay 之外已有一個運作中的 PostgreSQL 資料庫，並希望將其資料遷移至 ServBay 內建的 PostgreSQL 實例，本指南將為您詳細說明操作步驟。

本文將介紹如何利用標準 PostgreSQL 工具 pg_dump 和 pg_restore，搭配指定 ServBay PostgreSQL 的 socket 檔案路徑，完整完成資料匯入作業，確保您的資料無縫遷移。

概述

將既有 PostgreSQL 資料庫資料導入至 ServBay，通常需經過以下幾個主要步驟：

從來源 PostgreSQL 資料庫匯出資料。
在 ServBay 內建的 PostgreSQL 中準備目標資料庫。
將匯出的資料導入 ServBay 目標資料庫。
驗證資料匯入的完整性與正確性。

我們將詳細拆解每個步驟，並說明 ServBay 特有的連線方式（透過 socket 檔案）。

應用情境

將正式或測試環境的 PostgreSQL 資料複製到本地 ServBay 進行開發或除錯。
從獨立的 PostgreSQL 安裝將資料遷移到 ServBay 集中管理。
在 ServBay 建立與外部資料庫結構和資料一致的本地開發副本。

前置條件

在開始資料匯入之前，請確認以下條件皆已具備：

已安裝並運行 ServBay： 請確保您已在 macOS 平台安裝並啟動 ServBay。ServBay 預設已包含 PostgreSQL。
ServBay 內建 PostgreSQL 已啟動： 請在 ServBay 控制面板確認 PostgreSQL 套件已啟動。
來源 PostgreSQL 已運行於系統中： 您需有一個可存取的來源 PostgreSQL 資料庫實例。
安裝 PostgreSQL 客戶端工具： 系統需已安裝 pg_dump 和 pg_restore 等 PostgreSQL 指令工具，這些工具通常隨資料庫安裝而提供。
資料庫存取權限： 確保您擁有來源 PostgreSQL 資料庫的資料匯出權限，以及 ServBay 內建 PostgreSQL 的建立資料庫與匯入資料權限（通常需有如 postgres 超級使用者權限）。

步驟一：從來源 PostgreSQL 匯出資料

首先，需將來源 PostgreSQL 資料庫內容匯出成檔案。建議使用 pg_dump 工具完成。

開啟終端機： 啟動您的終端機應用程式。
執行匯出命令： 使用 pg_dump 連接來源 PostgreSQL 資料庫，並將資料匯出至指定檔案。
bash
```
pg_dump -U your_source_username -d your_source_database_name -F c -b -v -f mydatabase_source.dump
```
1
- -U your_source_username: 請替換成您的來源資料庫使用者名稱。
- -d your_source_database_name: 替換成您欲匯出的資料庫名稱。
- -F c: 指定匯出格式為自定義歸檔，適合用於 pg_restore 的高彈性還原作業。
- -b: 包含大型物件（blobs）資料。
- -v: 啟用詳細輸出模式，以追蹤匯出進度。
- -f mydatabase_source.dump: 指定輸出的檔案名稱及路徑，您可自由設定，如 /path/to/your/directory/mydatabase_source.dump。
視來源資料庫配置，您可能還需設定主機 (-h) 或埠號 (-p)，例如來源資料庫運作於本地，但埠號非預設 5432：
bash
```
pg_dump -U your_source_username -d your_source_database_name -h localhost -p 5433 -F c -b -v -f mydatabase_source.dump
```
1
執行上述命令後，系統可能會要求輸入來源使用者的密碼。

步驟二：準備 ServBay 目標資料庫

匯入資料前，需先在 ServBay 內建 PostgreSQL 實例中新建一個空資料庫做為目標。

連線至 ServBay PostgreSQL： ServBay 的 PostgreSQL 預設使用 socket 檔案進行本地連線，其路徑通常為 /Applications/ServBay/tmp。可用 psql 工具進行連線。
bash
```
psql -U postgres -h /Applications/ServBay/tmp postgres
```
1
- -U postgres: postgres 是預設的超級使用者。ServBay PostgreSQL 初始即設為此使用者。
- -h /Applications/ServBay/tmp: 此為連線 ServBay PostgreSQL 的關鍵參數。 藉由指定路徑，透過 socket 文件連線，而非 TCP/IP 埠號。
- postgres: 即連線時預設的管理資料庫名稱。
執行命令後，系統將提示輸入 postgres 的密碼。如不知密碼，可於 ServBay 控制面板或文件查詢或重設。連線成功後，會看到 psql 的指令提示符。
建立目標資料庫： 在 psql 提示符下執行 SQL 指令新建資料庫，建議名稱與來源資料庫相近，如 mydatabase_servbay。
sql
```
CREATE DATABASE mydatabase_servbay;
```
1
請將 mydatabase_servbay 換成您所需的名稱。建立成功後，可用 \q 指令退出 psql。

步驟三：導入資料至 ServBay PostgreSQL

接下來，利用 pg_restore 工具，將先前匯出的 .dump 檔匯入 ServBay 新建的目標資料庫。

開啟終端機： 若已關閉，請重新開啟終端機。
執行匯入命令： 使用 pg_restore 連線至 ServBay PostgreSQL 並進行匯入。
bash
```
pg_restore -U postgres -d mydatabase_servbay -v mydatabase_source.dump -h /Applications/ServBay/tmp
```
1
- -U postgres: 使用 ServBay PostgreSQL 超級使用者。
- -d mydatabase_servbay: 請替換成步驟二所建的目標資料庫名稱。
- -v: 啟用詳細輸出，以便即時檢查匯入進度與錯誤。
- mydatabase_source.dump: 替換成步驟一匯出的 .dump 檔案路徑。
- -h /Applications/ServBay/tmp: 再次強調，透過 socket 文件連線 ServBay PostgreSQL。
執行後，系統會提示輸入 ServBay PostgreSQL postgres 密碼。匯入過程所需時間視資料量及複雜度而異。

步驟四：驗證資料匯入

匯入完畢後，務必連線至 ServBay 目標資料庫，確認資料已正確匯入。

連線至 ServBay 目標資料庫：
bash
```
psql -U postgres -h /Applications/ServBay/tmp mydatabase_servbay
```
1
請將 mydatabase_servbay 替換為您目標資料庫名稱。輸入密碼後即可連線。
執行查詢驗證： 在 psql 提示符下執行 SQL 查詢，檢查資料內容。
- 列出所有資料表：\dt
- 查詢特定資料表前幾筆資料：
  sql
```
SELECT * FROM your_table_name LIMIT 10;
```
  1
  請把 your_table_name 換成實際資料表名稱。
- 檢查資料表筆數：
  sql
```
SELECT COUNT(*) FROM your_table_name;
```
  1
透過上述查詢，可初步檢驗資料表結構、資料內容及筆數是否符合預期。

處理可能的相容性問題

雖然 PostgreSQL 各版本間大多相容，但跨版本或特殊配置時仍偶有問題。

版本差異： 若來源與目標資料庫 PostgreSQL 版本差距較大，部份功能、語法或系統目錄可能不同。
- 解決方式： 請查閱 PostgreSQL 官方文檔瞭解兩版本間的變動。必要時，需手動修正匯出 SQL 或於匯入前/後執行特定遷移腳本。
擴充套件/模組不兼容或缺失： 來源資料庫使用的部份擴充套件（如 uuid-ossp, pgcrypto 等）或自訂函數，在 ServBay 的 PostgreSQL 可能未安裝或版本不符。
- 解決方式： 在匯入資料前或後，請先連線至 ServBay 目標資料庫安裝相關擴充套件：
  sql
```
CREATE EXTENSION IF NOT EXISTS your_extension_name;
```
  1
  若版本不符，可尋找替代方案或於 ServBay 升級 PostgreSQL（如 ServBay 有提供新版本）。
使用者與權限： pg_dump 預設會匯出使用者、角色與權限資訊，但這些物件在 ServBay 內可能需重設，尤其來源使用者並非 ServBay 預設帳號時。
- 解決方式： 匯入後，手動在 ServBay PostgreSQL 建立來源使用者與角色，並授予所需權限。
  sql
```
CREATE USER your_source_username WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE mydatabase_servbay TO your_source_username;
-- 若需更細緻控制請再授予
```
  1
  2
  3
  亦可在 pg_dump 時搭配 --no-owner 和 --no-acl 選項排除所有者與權限，任務結束後再手動設定。
編碼或地區設定 (Locale) 問題： 來源資料庫和目標資料庫編碼或地區設定不一致，易導致匯入錯誤或資料亂碼。
- 解決方式： 請於建立 ServBay 目標資料庫時選擇與來源相同編碼和地區設定。可於 CREATE DATABASE 指令中指定 ENCODING 與 LOCALE：
  sql
```
CREATE DATABASE mydatabase_servbay ENCODING 'UTF8' LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
```
  1
  請依來源資料庫實際配置調整。

遇到匯入問題時，詳細閱讀 pg_restore 輸出（-v 參數相當重要），通常可定位錯誤原因。

注意事項

ServBay Socket 路徑： ServBay 的 PostgreSQL 預設以 socket 方式連線，路徑為 /Applications/ServBay/tmp。所有連線 ServBay PostgreSQL 的命令（psql, pg_dump, pg_restore）均須搭配 -h /Applications/ServBay/tmp。
權限問題： 請確保用於執行命令的使用者有讀寫檔案權限，並且 PostgreSQL 連線帳號（如 postgres）有足夠資料庫建立與匯入權限。
檔案大小： 資料庫較大時，匯出匯入所需時間及空間也大，請確保系統資源充足。
密碼管理： 連線 ServBay PostgreSQL 時需輸入 postgres 密碼，請妥善保管。

常見問題集 (FAQ)

Q1: 忘記 ServBay PostgreSQL postgres 使用者密碼怎麼辦？

A1: 可於 ServBay 控制面板或查閱官方文件以查詢或重設 PostgreSQL 的 root (postgres) 密碼。

Q2: 為何無法用 localhost 或 127.0.0.1 連線 ServBay 的 PostgreSQL？

A2: ServBay 的 PostgreSQL 預設僅透過本地 socket 檔案接受連線，更加安全。若需用 TCP/IP 連線，必須修改 ServBay PostgreSQL 配置檔（一般本地開發環境不建議變更）。請採用 -h /Applications/ServBay/tmp 方式連線。

Q3: 匯入失敗怎麼排查？

A3: 請詳細檢查 pg_restore 輸出訊息，尤其有 -v 參數時。錯誤訊息會提示問題，例如語法錯誤、權限不足、物件重複或缺失等。可參照「處理可能的相容性問題」以協助排查。

Q4: 是否可用 ServBay 其他資料庫工具（如 pgAdmin）匯入資料？

A4: 可以。使用如 pgAdmin 等圖形化工具，在連線設定中將 Host/socket path 指定為 /Applications/ServBay/tmp，而非填主機名稱或 IP。之後即可透過工具匯入 .dump 檔案資料。

結論

將既有 PostgreSQL 資料庫資料匯入至 ServBay 內建的 PostgreSQL 為常見需求，只需善用標準 pg_dump 和 pg_restore 工具，並正確指定 ServBay PostgreSQL 的 socket 路徑（-h /Applications/ServBay/tmp），即可高效完成資料遷移。只要遵循本文流程並妥善處理可能的相容性問題，便能在 ServBay 本地開發環境建立與外部資料庫一致的工作環境。ServBay 為開發者提供整合便利的環境，讓資料庫管理與遷移更加省時省力。

如何從既有的 PostgreSQL 匯入資料到 ServBay ​

概述 ​

應用情境 ​

前置條件 ​

步驟一：從來源 PostgreSQL 匯出資料 ​

步驟二：準備 ServBay 目標資料庫 ​

步驟三：導入資料至 ServBay PostgreSQL ​

步驟四：驗證資料匯入 ​

處理可能的相容性問題 ​

注意事項 ​

常見問題集 (FAQ) ​

結論 ​