安裝與設定 PostgreSQL 時常見的錯誤

1. PostgreSQL 的主要組件

安裝程式會幫你裝好三個主要東西：server 跟兩個 client。現在我來簡單介紹一下它們。

伺服器 postgres

這就是 PostgreSQL 的核心啦。server 負責：

• 處理 client 的請求。
• 管理資料：讀取、寫入、更新。
• 確保資料的安全性和完整性。

當你啟動 PostgreSQL server，它就準備好接收 client 的請求囉。

客戶端

client 就是那些會連到 server 並送 SQL 請求的程式。在 PostgreSQL 裡有幾個很紅的 client：

• 程式 psql：用 command line 操作 PostgreSQL 的工具。很適合「老派」開發者或 terminal 愛好者。
• 程式 pgAdmin：管理 server 的圖形介面。就像資料庫界的瑞士刀——又美又好用。
• 其他 client：其實還有一堆 library 跟工具可以從其他語言玩 PostgreSQL，比如 Python 的 psycopg3 或 Ruby 的 pg。

這些組件怎麼一起運作？使用者透過 client（psql/pgAdmin）發送請求 → client 把請求送到 postgres server → server 用檔案系統跟記憶體處理請求 → 結果再回傳給 client。

2. 用終端機連接資料庫

希望你還記得，psql 是個用 command line 操作 PostgreSQL 的程式。如果你想快速查東西、執行查詢或研究資料庫，它超方便。

範例：用 psql

# 連接到 server
psql -U postgres

如果一切順利，你會看到類似這樣的畫面：

psql (17.5)
Type "help" for help.

postgres=#

恭喜啦，你已經進到 psql 的 command line 裡了！

連線一建立，你就可以執行指令囉：

-- 建立資料庫
CREATE DATABASE test_db;

-- 查看資料庫清單
\l

-- 切換到指定資料庫
\c test_db

-- 結束 session
\q

這對喜歡「直接來」的人來說超讚。

3. 安裝時的常見問題

那如果出包怎麼辦？如果你沒看到資料庫清單，甚至連登入都不行？安裝程式跑完就沒下文 😡 一堆錯誤、console 罵你、postgres 不啟動，psql 裝死裝不認識你。是不是很熟悉？恭喜你——你正處於「我明明都照做了但就是沒用」的經典新手階段。😅

來，我們一起看看最常踩的地雷，每個新手幾乎都會遇到。冷靜點，泡杯茶，決心幹掉所有 log 裡的錯誤。耐心點——今天我們要讓 PostgreSQL 不再只會在 mentor 電腦上跑。🛠️🐘

問題 1. Port 衝突

這大概是最常見的狀況之一。PostgreSQL 預設用 5432 port 來連 server。如果這個 port 被別的程式佔了，安裝會順利，但 server 就啟動不起來。

怎麼發現這問題？

啟動 PostgreSQL 時 server 不動，或出現像這樣的訊息：

could not bind IPv4 socket: Address already in use

解法：

查一下是哪個程式佔了 5432 port。在 Linux 可以用這指令：

sudo netstat -tuln | grep 5432

Windows 的話在 console 執行：

netstat -ano | find "5432"

如果 port 真的被佔了，你可以改 PostgreSQL 的 port。打開 postgresql.conf（在 PostgreSQL 的 data 資料夾裡），找到這行：

#port = 5432

換成一個沒被用的 port，例如：

port = 5433

記得改完要重啟 server。

問題 2. 權限不足

在 Windows 上你可能會遇到 PostgreSQL 安裝程式沒辦法順利裝完，因為目前的使用者權限不夠。

怎麼發現這問題？

安裝程式卡住或跳出沒權限的訊息。

解法：

用管理員身份執行安裝。右鍵點安裝程式，選「以管理員身份執行」。

問題 3. 環境變數問題

有時候裝完 PostgreSQL，psql 指令在 command line 裡找不到。

怎麼發現這問題？

嘗試執行 psql 時看到這種訊息：

'psql' is not recognized as an internal or external command

解法：

這是因為 PostgreSQL 的 bin 資料夾（例如 C:\Program Files\PostgreSQL\17\bin）沒加到環境變數裡。

在 Windows 上這樣修：

1. 打開「系統內容」→「進階」→「環境變數」。
2. 找到「系統變數」裡的 Path，編輯它。
3. 加上 PostgreSQL 的 bin 資料夾路徑。例如：

   
   C:\Program Files\PostgreSQL\17\bin
           

4. 然後重開 command line。

4. 連接 server 時的錯誤

有時一切順利：你啟動 PostgreSQL，開 psql，連資料庫都沒問題。但也有時候，突然就出錯了。怎麼都進不去。密碼好像沒錯，server 也在跑……結果 psql 一直罵你。

別慌——這種錯誤大家都遇過。下面我們來看最常見的連線問題，還有怎麼快速解決。

問題 1. 使用者 postgres 密碼錯誤

安裝 PostgreSQL 時你會設 superuser postgres 的密碼。如果忘了或打錯，server 就連不上。

怎麼發現這問題？

執行連線指令時：

psql -U postgres

你會看到像這樣的錯誤：

password authentication failed for user "postgres"

解法：

如果你忘了 postgres 的密碼，可以這樣重設：

1. 打開 pg_hba.conf，在 PostgreSQL 的 data 資料夾 C:\Program Files\PostgreSQL\17\data
2. 把這行：

   
   host    all             all             127.0.0.1/32            md5
           

   換成：

   
   host    all             all             127.0.0.1/32            trust
           

   這樣會暫時關掉密碼檢查。

3. 重啟 PostgreSQL server。
4. 不用密碼連資料庫：

   
   psql -U postgres
           

5. 用這指令改密碼：

   
   ALTER ROLE postgres PASSWORD 'new_password';
           

6. 把 pg_hba.conf 改回來，再重啟 server。

問題 2. host 或 port 設錯

如果 psql client 連不上 server，記得檢查設定裡的 host 跟 port 有沒有填對。

怎麼發現這問題？

連線錯誤可能會長這樣：

could not connect to server: Connection refused
    Is the server running on host "127.0.0.1" and accepting
    TCP/IP connections on port 5432?

解法：

先確定 PostgreSQL server 有在跑：

systemctl status postgresql

（Linux）或在 Windows 開「服務」（Ctrl+Shift+Esc）。

如果 server 有跑，再檢查 pg_hba.conf 的設定。確定本機（127.0.0.1）和你的 IP 的連線設定正確。例如：

host    all             all             127.0.0.1/32            md5
host    all             all             192.168.1.100/32        md5

5. 一般排錯建議

• 多看 PostgreSQL log
  log 是你最好的朋友。它們在 PostgreSQL 的 data 資料夾（Linux 通常在 /var/log/postgresql/）。出問題先看 log。
• 查官方文件
  PostgreSQL 的官方文件超強，遇到錯誤很大機率在這裡有解：https://www.postgresql.org/docs/。
• 問社群
  卡住就去 Stack Overflow、ChatGPT 或 PostgreSQL 論壇。很有可能已經有人遇過一樣的問題。

P.S.

很重要！ 如果你還是搞不定——寫信給我們的客服：我們會幫你解決，然後把解法補進這篇文章。