Visual Studio Code 的 PostgreSQL 擴充功能提供連線對話框，支援多種認證方法、SSL/TLS 加密，以及伺服器群組與儲存連線等組織工具。 本文涵蓋核心連線任務：開啟對話框、選擇驗證方法、儲存與重用連線，以及組織伺服器。
Tip
關於 SSH 隧道、連接字串 解析或憑證檔案設定，請參見進階連線選項。
開啟連線對話框
你可以用幾種方式開啟連線對話框：
- 連線：將滑鼠移到連接區塊的標頭上，選擇新增連線（圖示）。+
- 指令調色盤：執行 PGSQL：新增連線。
- 已儲存或最近連線：從側邊面板的 已儲存連線 或 最近連線 清單中選擇一張連線卡，將設定載入對話框。
當你開啟新對話框時，標頭顯示為 「新連線 」，標題則顯示「 連接至 PostgreSQL 伺服器」。 當你編輯現有連線時，標頭會變成 「編輯連線」。
選擇輸入模式
對話框頂端的 「透過：連線 」分頁讓你選擇如何提供連線資訊：
| Tab | Description |
|---|---|
| 參數 | 填寫個別欄位，如 伺服器名稱、 認證類型、 使用者名稱、 密碼、 資料庫名稱及 連線名稱。 這是預設模式。 |
| 連接字串 | 貼上任何支援的格式的連線字串。 擴充功能解析字串，並在唯讀的連線細節面板中顯示解壓後的伺服器名稱、使用者名稱和資料庫名稱。 |
| Browse Azure | 瀏覽你的 Azure 訂閱、資源群組和伺服器，直接選擇 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器或 Azure HorizonDB （Preview） 叢集。 需要登入 Visual Studio Code 的 Azure 帳號。 |
這三種模式在對話框底部共用相同的「儲存與連線測試」按鈕。 進階按鈕會在任何模式下開啟進階連線設定抽屜面板。
填充連接參數
使用 參數 標籤時，對話框會顯示以下主要欄位：
| Field | Description |
|---|---|
| 伺服器名稱 | PostgreSQL 伺服器的主機名稱或 IP 位址。 |
| 驗證類型 | 驗證的方法。 請參見 認證類型。 |
| 使用者名稱 | PostgreSQL 資料庫使用者或角色。 當 認證類型 為 密碼 或 AWS IAM（RDS/AURORA）時可見。 |
| 密碼 | 使用者帳戶的密碼。 當 認證類型 為 密碼時可見。 |
| 儲存密碼 | 勾選此方框以安全儲存密碼。 請參見 密碼儲存。 |
| 資料庫名稱 | 要連接的資料庫名稱。 留空以連接預設資料庫。 |
| 連線名稱 | 此連線的選用易記名稱。 擴充功能會在 連線 樹和 已儲存連線 清單中顯示這個名稱。 |
根據認證類型，會顯示額外的欄位。 對於 Entra 認證，對話框會顯示 Entra 帳號、 Entra 使用者名稱和 租戶。 對於 AWS IAM（RDS/AURORA），對話框會顯示 AWS 個人資料 和 AWS 區域。
Note
埠口欄位位於進階連線設定抽屜的頂層選項下方。 預設連接埠為 5432。
驗證類型
認證類型下拉選單提供四個選項。
密碼
密碼 驗證是 PostgreSQL 的標準方法。 你提供一個使用者名稱和密碼，伺服器會根據其認證設定驗證（通常是 pg_hba.conf）。
- 將 驗證類型 設為 密碼。
- 輸入 使用者名稱 和 密碼。
- 可選擇 儲存密碼 以安全儲存密碼。
- 選取 [儲存並連線]。
密碼儲存
當你選擇「儲存密碼」時，擴充功能會透過 Visual Studio Code SecretStorage API 儲存密碼，該 API 會委派給作業系統的憑證管理器：
- macOS：鑰匙圈
- Windows：憑證管理器
-
Linux：
libsecret（GNOME 鑰匙圈或 KWallet）
儲存的密碼會與特定連線綁定，且不會儲存在明文設定檔案中。
Microsoft Entra 認證
Microsoft Entra 認證（前稱 Azure Active Directory）為 適用於 PostgreSQL 的 Azure 資料庫 靈活伺服器提供基於令牌的無密碼認證。 對話框標示此選項為 Entra Auth。
Note
Entra 認證需要一台啟用 Entra 認證的 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器。 請參閱 Microsoft Entra 與 適用於 PostgreSQL 的 Azure 資料庫 的認證以了解設定細節。
要連結 Entra 認證：
- 新增你的 Entra 帳號。 打開指令面板並執行 PGSQL：新增 Microsoft Entra 帳號。 在瀏覽器開啟的視窗中，用你的 Entra 帳號登入。
- 打開連線對話框。 將 認證類型 設為 Entra Auth。
- 選取您的帳戶。 從 Entra 帳戶 下拉選單選擇你新增的帳號。
- 選擇租戶。 如果您的帳戶屬於多個租戶，請從 租戶 下拉選單中選擇合適的租戶。
- 輸入 Entra 用戶名。 輸入對應到您身分的 PostgreSQL 角色之 Entra 使用者名稱。
- 連接。 選取 [儲存並連線]。 擴充功能會取得存取權杖，並代表你向 PostgreSQL 伺服器進行認證。
已儲存的 Entra 連線設定檔仍會使用舊版的 AzureMFA 值。 標準的 bearer-token:entra-id 值保留供由伺服器驅動的分派及未來的設定檔遷移使用。
要移除 Entra 帳號，請執行 PGSQL：從指令面板中移除 Microsoft Entra 帳號，並選擇要移除的帳號。 若要清除快取的權杖而不移除帳戶，請執行 PGSQL：清除 Microsoft Entra 帳戶權杖快取。
雙重帳戶模型
該擴充套件支援 Azure 情境的雙重帳號模式。 你可以用一個 Entra 帳號來進行資料庫認證，另一個帳號用來瀏覽 Azure 資源（訂閱、資源群組和伺服器）。
- 連線對話框中的 Entra 帳戶 欄位控制哪個身份要向資料庫進行認證。
- 瀏覽 Azure 標籤使用登入 Visual Studio Code 的 Azure 帳號（透過 Azure Resources 擴充功能）來進行訂閱與資源列舉。
Tip
當你的資料庫管理員帳號與管理 Azure 訂閱的帳號不同時，這種分離非常有用。 分別獨立設定各項目，以便為每項任務使用正確的權限。
AWS IAM（RDS/Aurora）
AWS IAM 認證使用 AWS 簽署的資料庫認證憑證，而非儲存的密碼。 此選項僅適用於 Amazon RDS for PostgreSQL 或啟用 IAM 資料庫認證的 Amazon Aurora PostgreSQL 資料庫端點。 手動輸入 的 AWS 區域 可以補充區域推論，但不代表支援自訂的 PostgreSQL 主機、非 RDS 主機或 CNAME 別名。 對話框標示此選項為 AWS IAM（RDS/Aurora）。
Note
你的 PostgreSQL 資料庫角色必須存在於伺服器上，並且必須允許使用 IAM 資料庫認證。 對於 RDS 和 Aurora PostgreSQL，請授予角色 rds_iam。 欲了解更多資訊，請參閱 MariaDB、MySQL 與 PostgreSQL 的 IAM 資料庫認證。
要連接 AWS IAM 認證：
- 準備 AWS 憑證。 配置你組織所需的 AWS CLI 流程。 範例包括
aws configure、aws sso login --profile <profile>或 組織特定的credential_process架構。 - 打開連線對話框。 將認證類型設為 AWS IAM（RDS/Aurora）。
- 輸入伺服器端點。 在 伺服器名稱中使用 Amazon RDS 或 Aurora PostgreSQL 端點。
- 輸入資料庫角色。 在 使用者名稱中輸入 PostgreSQL 資料庫的使用者或角色。 這不是 AWS 個人檔案、IAM 使用者、IAM 角色或 ARN。
- 選擇 AWS 憑證來源。 選擇或輸入 AWS 個人檔案。 保持 AWS 設定檔 空白，以便使用預設的 AWS 憑證鏈。
- 如果需要，設定 AWS 區域。 此延伸模組會在可能的情況下，從標準的 RDS 和 Aurora 主機名稱判斷區域。 如果主機名稱沒有包含區域，請輸入 AWS 區域。
- 連接。 選取 [儲存並連線]。 擴充功能會簽發一個短效驗證權杖，並將其用作新連線的 PostgreSQL 密碼。
AWS 憑證鏈支援環境變數、共享的 AWS 設定與憑證檔案、AWS SSO 設定檔，以及 credential_process 設定檔。 它不使用 EC2 或 ECS 執行個體/容器的中繼資料憑證，也不使用中繼資料支援的 credential_source 設定檔鏈結。
AWS IAM 資料庫認證憑證有效期為 15 分鐘。 擴充功能會根據需要取得新的憑證，而底層的 AWS 憑證則保持有效。 不需要手動更新權杖。
None
沒有人 完全跳過驗證。 擴充功能連線時不會傳送憑證。 此選項適用於設定為使用 trust 驗證或類似不需認證設定的 PostgreSQL 伺服器。
連接、測試與斷開
填寫連線細節後，請使用連線對話框和 連線 樹中的操作來儲存設定檔、連線、編輯或移除伺服器。
儲存與連結
填寫連結細節後，選擇 「儲存並連接 」來建立連線。 此按鈕執行兩個動作：
- 在你的 VS Code 設定中，將連線存為個人檔案。
- 連接到伺服器。
若連線成功，伺服器會出現在 連線 樹中。 該連線也會出現在 已儲存 連線與 最近連線 的連線對話框中。
測試連接
選擇 「測試連線 」以驗證連線參數，無需儲存設定檔或將伺服器加入 連線 樹。 測試執行時按鈕會顯示旋轉器，成功時會顯示勾選，失敗時則顯示警告圖示。
中斷連線
要從伺服器斷開連線：
- 連線：右鍵點擊伺服器節點並選擇 斷線。
- 指令調色盤：執行 PGSQL：斷開連線。
編輯現有連線
要編輯已儲存的連線，請在 連線 樹中右鍵點擊伺服器，然後選擇 編輯連線。 連線對話框以編輯模式開啟，標頭為 「編輯連線 」，標題為目前的設定檔名稱。 請先做修改，然後選擇 儲存與連線 ，重新連接到更新後的設定。
進階連線設定
請選擇主欄位下方的 進階 按鈕，開啟 進階連線設定 抽屜。 抽屜內有：
- 頂層選項： 範圍 （使用者或工作區）、 埠號、 應用程式名稱、 連線逾時，以及 多子網路故障轉移。
- 分組區段：適用於 來源、安全性、伺服器、用戶端、SSL、Copilot 和 SSH 通道 的可摺疊手風琴式區段。
範圍選項控制連線設定檔的儲存位置：
| Scope | 設定檔儲存在何處 |
|---|---|
| User | VS Code 使用者設定（全域，任何工作空間皆可使用） |
| Workspace | VS Code 工作區設定（透過 .vscode/settings.json） 與協作者分享 |
關於 SSL 與 SSH 隧道設定細節，請參閱 進階連線選項。
每個連線的 Copilot 存取模式
進階抽屜中的 Copilot 區塊包含一個 Copilot 存取模式下拉選單，包含三個選項：
| Option | 影響 |
|---|---|
| 使用全域設定 | 繼承全域 pgsql.copilot.accessMode 值。 |
| 唯讀 | 限制 Copilot 在此連線上只能執行唯讀作業。 |
| 讀寫 | 允許 Copilot 對此連線執行讀寫操作。 |
SSL 和 TLS
SSL/TLS 會加密 Visual Studio Code 與 PostgreSQL 伺服器之間的連線。 請在進階連線設定抽屜的 SSL 區塊或你的 連接字串 裡設定 SSL 模式。
SSL 模式
| Mode | Description |
|---|---|
| 禁用 | 沒有 SSL 加密。 連線未加密。 |
| 允許 | 先嘗試未加密連線;如果伺服器需要，會回退到 SSL。 |
| 偏好 | 先嘗試 SSL;如果 SSL 協商失敗，則會退回到未加密的連線。 這是許多 PostgreSQL 用戶端的預設配置。 |
| 必須 | 需要 SSL 加密，但不會驗證伺服器憑證。 防止被動竊聽。 |
| Verify-CA | 需要 SSL，並驗證伺服器憑證是否由受信任的憑證授權機構（CA）簽署。 |
| 完整驗證 | 需要 SSL，驗證 CA，並檢查伺服器主機名稱是否與憑證的通用名稱或主體替代名稱相符。 提供最強的保護。 |
Note
適用於 PostgreSQL 的 Azure 資料庫 預設需要 SSL。 大多數情況請使用 Require，或搭配 DigiCert Global Root G2 憑證 使用 Verify-Full，以獲得最高安全性。
Tip
關於憑證檔案的設定與互惠 TLS 情境，請參見 進階連線選項。
管理已儲存及近期連線
連線對話框包含一個側面板，裡面有兩個清單：
- 已儲存的連線：你之前用 Save & Connect 儲存過的連結。 每張卡片顯示伺服器的顯示名稱。 將滑鼠移到卡片上即可顯示刪除按鈕。 選擇一張卡片將其設定載入對話框。
- 最近連線：你最近使用的連線，不論你是否用 連線名稱儲存。 將游標懸停其上即可顯示移除按鈕。
最近連線清單的上限由 pgsql.maxRecentConnections 設定決定。 每個設定檔與資料庫可同時開啟的連線數上限由 pgsql.maxConnections 設定控制 (預設值為 10)。
伺服器群組
伺服器群組幫助你在 連接 樹中組織連線。 你可以為每個群組設定自訂名稱和顏色，讓你更容易一眼辨識開發、暫定和生產等環境。
建立伺服器群組
- 在 連線 樹中右鍵點擊，選擇 建立伺服器群組。
- 在對話框中輸入 名稱、可選 描述，並選擇群組的 顏色 。
編輯或移除伺服器群組
- 編輯：在 連線 樹中右鍵點選伺服器群組，選擇 編輯伺服器群組 以更改其名稱、描述或顏色。
- 移除：右鍵點擊伺服器群組並選擇 移除。 群組中的連結不會被刪除;他們會移到預設群組。
將連線指派給群組
當你建立或編輯連線時，連線對話框的主欄位會有一個 伺服器群組 下拉選單。 從列表中選擇一個群組，將連線分配到該群組。
群組顏色會在 連結 樹中以彩色條狀顯示在群組名稱旁，方便快速視覺識別。
Azure metadata
當你連接到 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器時，連線對話框可以顯示表單旁邊的 Azure 元資料面板。 這個面板會顯示伺服器的訂閱與資源群組，當你選擇取得 Azure 元資料後。 包含 Azure 元資料可啟用管理功能，如伺服器儀表板與 Azure 監視器 指標。
排除常見連線問題
當連線嘗試失敗時，通常是網路、認證或 SSL 設定造成的。 以下章節涵蓋最常見的案例。
連線遭拒或逾時
如果連線在開始驗證前失敗，請先驗證 伺服器名稱 和 埠 口。 確保 PostgreSQL 正在執行，埠口可從你的機器連通，且任何網路防火牆規則允許連線。 你可以在進階連線設定面板中調整連線逾時時間，讓較慢的網路有更多連線時間。
SSL 或憑證驗證錯誤
如果伺服器需要加密，請確認進階抽屜中 SSL 區塊中所選的 SSL 模式是否與伺服器設定相符。 對於 Verify-CA 和 Verify-Full，請確保已設定正確的 CA 憑證。 關於憑證檔案的詳細資訊，請參閱 進階連線選項。
Microsoft Entra 登入或令牌問題
如果 Entra 認證失敗，請確認目標 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器是否啟用了 Entra 認證，然後確認你在連線對話框中選擇了正確的帳號和租戶。 如有需要，執行 PGSQL：移除 Microsoft Entra 帳號並重新新增帳號。 若要重設快取的權杖，請執行 PGSQL：清除 Microsoft Entra 帳戶權杖快取。
AWS IAM 設定檔或權杖問題
如果 AWS IAM 認證失敗，請確認 伺服器名稱 是 Amazon RDS 或 Aurora PostgreSQL 端點，而非自訂主機名稱或 CNAME 別名。 確認 使用者名稱 是 PostgreSQL 資料庫角色，且該角色伺服器上已啟用 IAM 資料庫認證。 確認所選 AWS 設定檔 能取得支援的 AWS 憑證;例如，執行 aws sts get-caller-identity --profile <profile> 命名設定檔，或在使用預設憑證鏈時省略 --profile 。 如果支援的端點推論區域失敗，請手動輸入 AWS 區域 。
連接字串解析無法填入正確的欄位
如果貼上的 連接字串 沒有填入預期值，請在進階連線選項中檢視支援的輸入模式。 若原始格式不尋常，請切換至 參數 標籤並手動輸入數值。