// 免費工具

PostgreSQL 連線字串產生器

從同一個表單建立 PostgreSQL 連線 URI、libpq 關鍵字/值字串、Npgsql (ADO.NET) 字串、JDBC URL 等,或者貼上其中任何一種以檢視每個參數的作用,以及 sslmode 是否真的能保護你。 一切都在你的瀏覽器中執行:你輸入的任何內容都不會外傳。

在 SQLly 中開啟此連線

開啟 SQLly 的連線編輯器,並自動填入內容。

設計即私密。 建構器和解碼器都是在此分頁中執行的純 JavaScript。頁面不會發送你輸入的任何請求,也不會儲存任何資料(甚至不在你的瀏覽器中),載入後可離線使用。開啟 SQLly 的連結會從你的瀏覽器直接進入你電腦上的應用程式。

PostgreSQL 連線字串格式

大多數 PostgreSQL 驅動程式不是基於 libpq,就是沿用它的規則,所以 URI postgresql://user:password@host:5432/db?sslmode=verify-full 以及關鍵字/值形式 host=... dbname=... 幾乎在所有地方都有效:psql、psycopg、pgx、lib/pq、node-postgres。Npgsql (.NET) 與 pgJDBC (Java) 則有自己的寫法。

最重要的參數是 sslmode。它的預設值, prefer,伺服器有提供 TLS 時會用,但從不檢查憑證,還會悄悄退回純文字。只有 verify-full 會檢查憑證鏈和主機名稱。

URI libpq、psql、psycopg、pgx、node-postgres、Prisma

postgresql://app_user:[email protected]/sales?sslmode=verify-full

關鍵字/值 libpq conninfo、psycopg、pgx、lib/pq

host=db.example.com dbname=sales user=app_user password=your_password sslmode=verify-full

ADO.NET (Npgsql) Npgsql、Entity Framework Core

Host=db.example.com;Database=sales;Username=app_user;Password=your_password;SSL Mode=VerifyFull

JDBC PostgreSQL JDBC 驅動程式 (pgJDBC)

jdbc:postgresql://db.example.com/sales?user=app_user&password=your_password&sslmode=verify-full

ODBC psqlODBC

Driver={PostgreSQL Unicode};Server=db.example.com;Database=sales;Uid=app_user;Pwd=your_password;SSLmode=verify-full;

SQLAlchemy URL Python SQLAlchemy 搭配 psycopg 3

postgresql+psycopg://app_user:[email protected]/sales?sslmode=verify-full

多部主機(容錯移轉) libpq 10+、pgx、Npgsql、pgJDBC

postgresql://[email protected]:5432,db2.example.com:5432/sales?target_session_attrs=read-write

預留位置,例如 your_password 就只是這個意思:用上面的表單組出你自己的字串。更多關於把 SQLly 連上 PostgreSQL 的說明: 適用於 PostgreSQL 的 SQLly.

libpq 參數(URI 與關鍵字/值)

URI 格式: postgresql://[user[:password]@][host][:port][,...][/dbname][?param=value&...] (postgres:// 也適用);特殊字元要百分比編碼,包括作為主機使用的 Unix socket 路徑中的斜線。鍵/值形式: key=value 以空格分隔的鍵值組;空的值或含有空格的值請用單引號括住,並寫 \' 和 \\ 在其中使用引號或反斜線。

關鍵字同義詞預設其作用
host - 位於 /tmp 的 Unix socket(Windows 上則為本機) 主機名稱、IP,或作為 Unix 通訊端的目錄。逗號分隔清單會依序嘗試。
hostaddr - - 使用數字 IP,略過 DNS(主機名稱仍用於 TLS 驗證)。
port - 5432(建置時的預設值) 一個連接埠,或每個主機一個。
dbname - 使用者名稱 要連線的資料庫。
user - 作業系統使用者 連線時使用的角色。
password - - 最好儲存在 ~/.pgpass (或者 PGPASSWORD)比字串裡的還多。
passfile - ~/.pgpass(Windows 上為 %APPDATA%\postgresql\pgpass.conf) 密碼檔。
connect_timeout - 0(無限等待) 每個主機的秒數。PostgreSQL 16 及更早版本將 1 視為 2。
sslmode - prefer disable, allow, prefer, require, verify-ca, verify-full. require 僅當存在根憑證檔案時才驗證 CA;僅 verify-full 檢查主機名稱。
sslrootcert - ~/.postgresql/root.crt CA 檔案。 system (16+) 會使用作業系統信任的 CA,並使 verify-full 預設值。
sslcert / sslkey - ~/.postgresql/postgresql.crt / .key 客戶端憑證和金鑰。
sslnegotiation - postgres 17+. direct 立即啟動 TLS(需要 sslmode require 或更嚴格的設定)。
application_name - - 顯示於 pg_stat_activity 以及伺服器記錄中。
options - - 啟動時的伺服器設定,例如 -c statement_timeout=30000 -c search_path=app.
target_session_attrs - 任何 any, read-write, read-only, primary, standby, prefer-standby.
load_balance_hosts - 停用 16+. random 隨機排列主機清單。
keepalives - 1 TCP keepalive 開/關;用 keepalives_idle, keepalives_interval, keepalives_count.
channel_binding - prefer require 若沒有 SCRAM 通道繫結,則拒絕驗證。

Npgsql (ADO.NET) 參數

Npgsql 使用 ADO.NET Key=Value; 語法,有自己的一套關鍵字名稱。值若含有 ; 以雙引號括起。

關鍵字同義詞預設其作用
Host 伺服器 - (必填) 主機名稱、IP、逗號分隔清單,或通訊端目錄,其開頭為 /.
Port - 5432 TCP 連接埠。
Database 資料庫 使用者名稱 資料庫名稱。
Username 使用者名稱、使用者 ID、UID PGUSER,否則為作業系統使用者 角色名稱。
Password PSW,PWD PGPASSWORD 密碼。
SSL Mode SslMode 偏好 Disable, Allow, Prefer, Require, VerifyCA, VerifyFull。從 Npgsql 6 開始, Require 不驗證憑證。
Trust Server Certificate - 假 略過驗證。Npgsql 6 和 7 搭配 Require;Npgsql 8 則不需要。
Root Certificate - PGSSLROOTCERT VerifyCA / VerifyFull 使用的 CA 檔案。
Timeout - 15 等待連線的秒數。
Command Timeout - 30 預設命令逾時秒數;0 表示永久等待。
Application Name - PGAPPNAME application_name。
Search Path - - 結構描述搜尋路徑。
Target Session Attributes - 任何 any, primary, standby, prefer-primary, prefer-standby, read-write, read-only.
Pooling - 真 連線池機制。
Maximum Pool Size - 100 最大的連線池大小。
Minimum Pool Size - 0 最小的連線池。
Keepalive - 0(關閉) 保持連線查詢之間的秒數。
Include Error Detail - 假 將伺服器錯誤詳情(可能包含資料列資料)放進例外訊息中。

pgJDBC 屬性

URL 格式: jdbc:postgresql://host:port/database?property=value&...。pgJDBC 不會讀取 user:password@ 在 URL 中:傳入 user 和 password 作為參數或連線屬性。

關鍵字同義詞預設其作用
user / password - - 憑證。
sslmode - prefer 與 libpq 相同的值。 require, allow 和 prefer 不驗證憑證。
ssl - 假 true 未指定 sslmode 即表示 verify-full。
sslrootcert - ~/.postgresql/root.crt CA 檔案。
connectTimeout - 10 等待 socket 的秒數;0 表示不設限制。
socketTimeout - 0 讀取可封鎖的秒數;0 表示永遠等待。
loginTimeout - 0 等待整個登入過程的秒數。
ApplicationName - PostgreSQL JDBC 驅動程式 application_name。
currentSchema - - search_path,逗號分隔。
targetServerType - 任何 any, primary, secondary, preferPrimary, preferSecondary.
options - - 啟動選項,例如: -c statement_timeout=30000 (在 URL 中使用百分比編碼)。

常見的 PostgreSQL 連線錯誤

FATAL: no pg_hba.conf entry for host "10.0.0.7", user "app_user", database "sales", no encryption

原因: 已連上伺服器,但 pg_hba.conf 允許此用戶端、使用者與資料庫,或者符合的那一行是 hostssl 且你連線時未使用 TLS(「無加密」)。

修正此問題: 使用以下方式連線 sslmode=require 或更嚴格的,如果伺服器要求 TLS,或請管理員新增一條 host/hostssl 行,指定你的位址,然後重新載入伺服器。

connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused

原因: 該位址與連接埠上沒有任何服務在監聽:伺服器沒有啟動, listen_addresses 僅允許 localhost 存取、連接埠不同,或者防火牆拒絕了連線。

修正此問題: 檢查 listen_addresses 和 port 在 postgresql.conf 裡、防火牆或雲端安全群組,以及是否需要不同的連接埠(託管服務和連線集區常用 6432 或自訂連接埠)。

FATAL: password authentication failed for user "app_user"

原因: 密碼錯誤、角色沒有密碼,或密碼中的特殊字元未在 URI 中做百分比編碼,導致驅動程式讀到不同的密碼。

修正此問題: 檢查密碼;在 URI 中編碼 @ 作為 %40, : 作為 %3A, / 作為 %2F 和 % 作為 %25。把 URI 貼進解碼器,就能看到驅動程式實際會送出的密碼。

server does not support SSL, but SSL was required

原因: 這個連線字串要求 sslmode=require (或 verify-ca / verify-full),而伺服器 ssl = off.

修正此問題: 請在伺服器上啟用 TLS,或連到你的提供者文件所指定的 TLS 端點。不要退回 sslmode=disable ,特別是在你無法控制的網路上。

root certificate file "/home/app/.postgresql/root.crt" does not exist

原因: sslmode=verify-ca 或 verify-full 需要 CA 憑證來核對,但 libpq 在預設路徑找不到任何憑證。

修正此問題: 下載提供者的 CA 憑證組合,並設定 sslrootcert=/path/to/ca.pem,或在 PostgreSQL 16+ 的用戶端上則用 sslrootcert=system 當伺服器憑證由公開 CA 核發時。

FATAL: database "app_user" does not exist

原因: 否 dbname 指定,因此 libpq 會將使用者名稱當成資料庫名稱。

修正此問題: 將資料庫新增到 URI 路徑(/sales)或設定 dbname=sales.

invalid connection option "sslmod"

原因: 當關鍵字拼寫錯誤或屬於其他驅動程式時,libpq 會拒絕整個字串(例如 ApplicationName 來自 pgJDBC,而不是 application_name).

修正此問題: 修正拼字。解碼器會列出每個 libpq 參數,並標記不認得的參數。

PostgreSQL 連線字串常見問題

PostgreSQL 連線字串的格式是什麼?

以 libpq 為基礎的驅動程式可用兩種格式:URI postgresql://user:password@host:5432/dbname?sslmode=verify-full 以及關鍵字/值字串 host=host port=5432 dbname=dbname user=user sslmode=verify-full。Npgsql 使用 Host=...;Database=...;Username=... ,Java 使用 jdbc:postgresql://host:5432/dbname.

我應該使用哪種 sslmode?

verify-full 與 sslrootcert 指向你的 CA(或 system 於 PostgreSQL 16 以上版本)。 require 會加密但不驗證回應者的身分,而且 prefer,即預設值,可能悄悄退回純文字。請使用 disable 僅適用於通訊端或 localhost。

如何在 PostgreSQL URI 中逸出特殊字元?

在使用者名稱、密碼與資料庫中將它們做百分比編碼: @ 是 %40, : 是 %3A, / 是 %2F, # 是 %23, ? 是 %3F, % 是 %25 ,而空格是 %20。關鍵字/值的形式可以避開大部分這類問題:把值用單引號包起來,並跳脫 ' 和 \ 以反斜線。

如何在連線字串中設定陳述式逾時?

使用以 libpq 為基礎的驅動程式時,加上 options=-c statement_timeout=30000 (毫秒;放進 URI 時以百分比編碼為 options=-c%20statement_timeout%3D30000)。Npgsql 有 Command Timeout,以秒為單位的用戶端逾時。

我可以列出多個主機以進行容錯移轉嗎?

可以。寫成 postgresql://host1:5432,host2:5432/db 或 host=host1,host2 port=5432,5432。libpq 會按順序嘗試它們;新增 target_session_attrs=read-write 略過唯讀待命伺服器,或 load_balance_hosts=random (PostgreSQL 16+)來分散連線。

為什麼 node-postgres 使用 sslmode=require 驗證憑證?

pg-connection-string 目前將 sslmode=prefer, require 和 verify-ca 作為 verify-full ,並印出警告:未來的某個主要版本會改成 libpq 的語意。請新增 uselibpqcompat=true 以選擇使用 libpq 行為,或配置 ssl 改為在用戶端設定中。

// 完全跳過字串

連線一次。然後只需撰寫 SQL。

SQLly 是適用於 macOS、Windows 和 Linux 的原生 SQL 工作台。把連線字串貼進連線編輯器,密碼存在系統鑰匙圈裡,就能在 PostgreSQL 及更多引擎上獲得結構描述感知的 IntelliSense。