在终端中使用 psql

适用于 Visual Studio Code 的 PostgreSQL 扩展可让你打开psql会话，这些会话会自动连接到你的数据库，并可通过psql运行.sql文件。 无需离开编辑器，即可完整使用原生 psql 功能，包括反斜杠命令、COPY 工作流和交互式脚本。

该扩展会自动将连接信息（主机、端口、数据库、用户和密码）传递给 psql，因此您可以在打开会话后立即开始工作。

先决条件

• 已安装用于Visual Studio Code的 PostgreSQL 扩展。
• 与 PostgreSQL 服务器的活动连接。 有关设置步骤，请参阅 快速入门：连接和查询 PostgreSQL。
• 安装在系统上的 psql 命令行客户端。
• 在 Visual Studio Code 中打开工作区文件夹。

在 psql 和查询编辑器之间进行选择

大多数 PostgreSQL 工作流在不同时间都使用这两种工具：

打开连接的终端

psql打开自动连接到特定数据库的会话。 该扩展使用-h、-p、-d和-U标志启动psql，并设置PGPASSWORD环境变量，因此您无需手动输入连接详细信息。

1. 在 “连接 ”树中，右键单击数据库节点。
2. 选择 “使用 PSQL 进行连接”。

此时会打开一个Visual Studio Code任务终端，并psql连接到所选数据库。 终端选项卡名为 PSQL： <配置文件名称>。

你也可以从 命令面板（Ctrl+Shift+P / Cmd+Shift+P）中运行此命令：搜索 PGSQL：使用 PSQL 连接。

运行 SQL 文件

使用当前活动编辑器中的连接通过psql执行.sql文件。 输出显示在Visual Studio Code任务终端中。

1. 在编辑器中打开文件 .sql 。
2. 如果尚未连接编辑器，请将编辑器连接到数据库。
3. 在编辑器中右键单击并选择 “使用 PSQL 运行文件”。

该扩展保存文件，然后针对活动连接运行 psql -f <filepath> 。 此时会打开一个任务终端以显示执行输出。 工作目录设置为包含文件的文件夹，因此脚本中的相对路径可以正确解析。

配置 psql 二进制路径

扩展按以下顺序在三个位置搜索 psql ：

1. 捆绑的二进制文件：随扩展提供的 PostgreSQL 客户端工具，按版本分类。
2. 系统路径：操作系统 PATH 环境变量中列出的目录。
3. 自定义目录：添加到 pgsql.pgBinaryDirs 设置的路径。

找到多个版本的扩展 psql 时，该扩展选择最符合服务器的 PostgreSQL 版本的版本。 如果不存在完全匹配，则使用最接近的可用版本。

添加自定义二进制目录：

1. 打开 “设置” （Ctrl+, / Cmd+,）。
2. 搜索 pgsql.pgBinaryDirs。
3. 选择 “添加项 ”并输入包含二进制文件的目录的 psql 绝对路径。
4. 重启Visual Studio Code，使更改生效。

扩展如何启动 psql

选择 “使用 PSQL 连接 ”或 “使用 PSQL 运行文件”时，扩展将 psql 调用组合如下：

该扩展将 psql 作为 Visual Studio Code 任务运行，并在 终端 面板中打开。 在 psql 退出后，任务终端仍会保持打开状态，以便你查看输出。

用例

当需要内置查询编辑器以外的功能时，终端 psql 非常有用：

• 交互式 SQL 会话：在熟悉 psql 的环境中运行即席命令并检查结果。
• 批量数据导入/导出：使用 \copy 或 COPY 命令加载高性能数据。
• 管理任务：具有完全 psql 访问权限，可管理角色、权限和服务器配置。
• 脚本测试：在部署之前，先在原生 psql 中验证 .sql 脚本。
• 反斜杠命令：使用 \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。

打开工作区文件夹

该扩展需要先打开一个工作区文件夹，才能启动 psql。 如果邮件显示工作区文件夹必须打开，请打开包含 “文件>打开文件夹”的文件夹，然后重试。

身份验证或连接失败

如果 psql 打开，但连接失败：

• 确认连接配置文件中的主机、端口和数据库是否正确。 请参阅 连接和身份。
• 对于Microsoft Entra ID身份验证，请验证帐户是否仍在登录。 扩展会自动刷新令牌，但过期的会话可能需要重新身份验证。
• 如果使用 SSL 或 SSH 隧道，请先从连接对话框重新测试相同的连接，然后再重新打开 psql。

文件更改未运行

当你使用 Run file with PSQL 运行文件时，该扩展会在执行前先将文件保存到磁盘。 如果保存失败，扩展将取消该操作。 在查看输出之前，请成功保存文件。

相关内容

• 快速入门：连接和查询 PostgreSQL
• 查询编辑器和 IntelliSense
• 对象资源管理器
• 连接和标识