在終端機裡使用 psql

Visual Studio Code 的 PostgreSQL 擴充功能可讓你開啟psql工作階段，這些工作階段會自動連線到你的資料庫，並透過psql執行.sql檔案。 你可以完全使用原生 psql 功能，包括反斜線指令、 COPY 工作流程和互動腳本，無需離開編輯器。

擴充功能會自動將連線詳細資料（主機、連接埠、資料庫、使用者和密碼）傳遞給 psql，因此你只要開啟工作階段後即可立即開始工作。

先決條件

• 已安裝 Visual Studio Code 的 PostgreSQL 擴充功能。
• 一個主動連接 PostgreSQL 伺服器的連線。 關於設定步驟，請參見 快速入門：連接並查詢 PostgreSQL。
• 安裝在你系統上的 psql 命令列客戶端。
• 在 Visual Studio Code 中開啟一個工作區資料夾。

請在 psql 和查詢編輯器之間選擇

大多數 PostgreSQL 工作流程會在不同時間使用這兩種工具：

打開連接的端子

開啟一個會自動連線到特定資料庫的 psql 工作階段。 擴充套件啟動時 psql 會標記 -h、 -p、 -d，並 -U 設定 PGPASSWORD 環境變數，所以你不需要手動輸入連線細節。

1. 在 Connections 樹中，右鍵點擊資料庫節點。
2. 選擇 「與 PSQL 連線」。

Visual Studio Code 任務終端機開啟時，會以psql連線到所選資料庫。 終端機分頁名為 PSQL： <設定檔名稱>。

你也可以從 指令面板 執行此指令 （Ctrl+Shift+P / Cmd+Shift+P）： 搜尋 PGSQL： Connect with PSQL。

執行一個 SQL 檔案

使用作用中編輯器中的連線，透過 psql 執行 .sql 檔案。 輸出會出現在 Visual Studio Code 的任務終端機中。

1. 在編輯器裡開啟一個 .sql 檔案。
2. 如果編輯器還沒連接，請把它連接到資料庫。
3. 在編輯器中右鍵點擊，選擇 「以 PSQL 執行檔案」。

擴充功能會先儲存檔案，然後針對目前使用中的連線執行 psql -f <filepath>。 任務終端會打開以顯示執行結果。 工作目錄會設定為包含該檔案的資料夾，這樣腳本中的相對路徑才能正確解析。

配置 psql 二進位路徑

擴充功能會依照下列順序，在三個位置中搜尋 psql：

1. 隨附的二進位檔：隨擴充功能提供的 PostgreSQL 用戶端工具，依版本整理。
2. System PATH：在作業系統 PATH 環境變數中列出的目錄。
3. 自訂目錄：你加入 pgsql.pgBinaryDirs 設定的路徑。

當找到多個 psql 版本時，擴充功能會選擇最符合你伺服器的 PostgreSQL 版本的版本。 若無完全匹配，則使用最接近的版本。

要新增自訂二進位目錄：

1. 開啟 設定 （Ctrl+, / Cmd+,）。
2. 搜尋 pgsql.pgBinaryDirs。
3. 選擇 新增項目 ，並輸入包含該 psql 二進位檔目錄的絕對路徑。
4. 重新啟動 Visual Studio Code 才能生效。

擴充功能如何啟動 psql

當你選擇 Connect with PSQL 或 Run file with PSQL 時，擴充功能會如下組成 psql 的叫用命令：

該擴充功能以 Visual Studio Code 任務形式執行psql，會在終端機面板開啟。 任務終端機在退出後 psql 會保持開啟，方便你檢視輸出。

應用案例

當你需要內建查詢編輯器以外的功能時，終端 psql 機非常有用：

• 互動式 SQL 會話：在熟悉 psql 的環境中執行臨時指令並檢查結果。
• 批量資料匯入/匯出：使用 \copy 或 COPY 指令進行高效能資料載入。
• 管理任務：管理角色、權限及伺服器設定，擁有完整 psql 存取權。
• 腳本測試：部署前先以原生.sql方式驗證psql腳本。
• 反斜線指令：使用\dt\d+\timing\x、 及其他圖形查詢編輯器中無法使用的其他指令。

常見 psql 任務

檢查資料庫物件

使用 psql 反斜線指令以快速進行結構檢查：

\dt
\d+ public.orders
\dn

這些指令會列出表格、顯示詳細的物件定義，以及列出結構。

開啟定時與擴展輸出

\timing on
\x on
SELECT * FROM public.orders LIMIT 5;

\timing 每句話後顯示查詢時間。 擴充輸出（\x）可讓較寬的資料列更容易閱讀。

使用 \copy 載入或匯出資料

\copy public.customers FROM '/Users/example/customers.csv' WITH (FORMAT csv, HEADER true)

使用 \copy 來進行面向終端機的大量匯入或匯出，同時重複使用由擴充套件管理的連線內容。

Troubleshoot

psql 未找到

如果擴充功能顯示「找不到 psql 可執行檔」的錯誤，請嘗試以下步驟：

1. 請從 PostgreSQL 下載頁面安裝適用於你作業系統的 PostgreSQL 用戶端工具。
2. 請在系統終端機中執行 psql --version，以確認 psql 是否可用。
3. 如果 psql 安裝在非標準位置，請將該目錄加入設定 pgsql.pgBinaryDirs 。 請參見 配置 psql 二進位路徑。
4. 重新啟動 Visual Studio Code。

打開一個工作區資料夾

擴充功能需要開啟 workspace 資料夾才能啟動 psql。 如果有訊息說工作區資料夾必須開啟，請打開一個有 檔案>開啟資料夾的資料夾，然後再試一次。

認證或連線失敗

如果 psql 開啟了但連線失敗：

• 確認你的連線設定檔中主機、埠口和資料庫是否正確。 參見「連結與身份」。
• 關於 Microsoft Entra ID 驗證，請確認你的帳號仍然登入狀態。 擴充功能會自動刷新令牌，但過期的會話可能需要重新認證。
• 如果你使用 SSL 或 SSH 隧道，請在重新開啟 psql連線對話框前重新測試同一連線。

檔案變更無法執行

當您使用 Run file with PSQL 執行檔案時，延伸模組會在執行前先將檔案儲存至磁碟。 若存檔失敗，擴充功能會取消該操作。 在你檢視輸出之前，先成功儲存檔案。

相關內容

• 快速入門：連接並查詢 PostgreSQL
• 查詢編輯器與 IntelliSense
• 物件探測器
• 連結與身份認同