如何將現有 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 用戶端工具： 系統上需具備 pg_dump 與 pg_restore 等 PostgreSQL 命令列工具，通常安裝 PostgreSQL 伺服器或客戶端時會一併裝上。
有相應權限： 請確認你擁有來源資料庫的匯出權限，以及 ServBay 內建 PostgreSQL 的新建資料庫與匯入資料權限（建議使用超級用戶，如 postgres）。

步驟一：從來源 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: 替換為連線來源 PostgreSQL 的用戶名稱。
- -d your_source_database_name: 替換為欲匯出的來源資料庫名稱。
- -F c: 指定輸出格式為自訂歸檔格式，配合 pg_restore 可進行彈性還原（例如選取資料表逐步還原）。
- -b: 匯出大物件（blob）資料。
- -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 檔案本地連線，socket 路徑一般位於 /Applications/ServBay/tmp。可用 psql 工具連線。
bash
```
psql -U postgres -h /Applications/ServBay/tmp postgres
```
1
- -U postgres: postgres 為預設超級用戶，ServBay 通常預設設定此用戶。
- -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 postgres 用戶密碼。匯入程序所需時間視檔案大小與資料庫複雜度而定。

步驟四：驗證資料匯入結果

資料匯入完成後，請務必連線至 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 通常相容良好，但在跨大版本或特殊設定下仍可能遇到困難。

版本差異： 若來源與目標資料庫版本差距大，可能有語法或內部目錄差異。
- 解決方式： 參閱官方文件查明兩版本間的變動。如需可先調整 SQL 檔或在匯入前／後執行補充遷移指令。
擴展套件或模組相容性／缺失： 若來源資料庫有某些 extension（如 uuid-ossp, pgcrypto）或自訂函式，可能 ServBay 內建 PostgreSQL 未安裝或版本不同。
- 解決方式： 匯入前後，在目標資料庫安裝所需 extension，例如：
  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 資料庫時指定和來源一致的編碼與 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。無論 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 標準工具，並正確指定 socket 連線路徑（-h /Applications/ServBay/tmp）即可高效完成遷移。依循本指引步驟，適當處理相容性問題，你就能快速打造出與外部資料庫一致的本地開發環境。ServBay 為開發者提供了整合便利的平台，讓資料庫管理及移轉變得輕鬆容易。

如何將現有 PostgreSQL 資料匯入到 ServBay ​

概述 ​

應用情境 ​

前置條件 ​

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

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

步驟三：將資料匯入 ServBay PostgreSQL ​

步驟四：驗證資料匯入結果 ​

處理相容性問題 ​

注意事項 ​

常見問題解答 (FAQ) ​

總結 ​