排查线上数据库问题的时候，最怕什么？最怕你连上去之后只能盯着postgres=#这个提示符发呆。psql 是 PostgreSQL 官方自带的命令行交互客户端，也是所有 PostgreSQL 使用者绕不开的基础工具。它没有花哨的图形界面，但正因为它是命令行工具，服务器上、容器里、故障现场，任何时候你都有办法用它连上数据库把问题理清楚。

我见过不少人装了 pgAdmin、DataGrip，平时点鼠标看数据很顺手，一到了要写脚本跑批、排查生产环境问题的时候，反而不知道该怎么办。这篇文章我想把 psql 从连接到日常操作、从格式输出到脚本自动化，完整过一遍。后端开发、DBA、数据分析师，甚至刚准备学 PostgreSQL 的新手，都能从这里找到可以直接抄走的用法。

1. 为什么psql值得系统掌握

1.1 它不是“过时的老古董”，而是最后一道防线

很多人第一次打开 psql，界面又黑又朴素，第一反应是“这年头谁还用这玩意儿”。但请你想一个场景：凌晨两点，应用报数据库连接数打满，你 SSH 到服务器上，没有图形界面，不能打开浏览器，你手里有什么？只有终端。这时候 psql 就是你和数据库之间最短的那条路。

PostgreSQL 在 Linux 上安装后，psql 一定是跟着装好的。它不需要额外部署、不需要图形依赖、不需要授权文件，一条命令就能连上实例。和其他 GUI 工具相比，psql 启动速度几乎为零延迟，占用的内存可以忽略不计。对经常要处理的这种“临时冒出来一个问题”的场景，这种可靠性比任何花哨功能都重要。

而且 psql 并不仅仅是一个“能敲 SQL 的黑框”，它内置了几十条元命令，从查看表结构、列出索引、切换数据库，到导出 CSV、定时重跑查询，全都能覆盖。用得好了，你完全可以把 psql 当成一个轻量级的数据库运维控制台。

1.2 GUI工具和psql的边界在哪里

GUI 工具的优势是“看得见”：数据结果用表格呈现，表结构用图形化方式展示，适合临时查数据、编辑数据。但它的缺点也很明显：难以自动化、难以批量处理、难以在无人值守场景下运行。你没法在 crontab 里写一条“打开 pgAdmin 点击导出”的任务，但你可以写一行 psql 命令，把它挂进定时任务，每天自动跑。

psql 的定位恰恰是“无人值守、可重复、轻量”。它既可以交互式使用，也可以非交互式执行 SQL 文件，还可以配合 shell 脚本完成复杂的自动化流水线。两者不是替代关系，而是互补关系：日常开发用 GUI 提高效率，到了部署、巡检、故障恢复这些场景，psql 才是真正的主力。

另外一个常被忽略的点：掌握 psql，你会被迫去理解 PostgreSQL 本身的运作逻辑，比如权限体系、模式（schema）结构、客户端认证方式。这些恰恰是 GUI 工具帮你“藏起来”的部分，而它们往往正是线上问题真正的根源。

2. 连接PostgreSQL：参数、URI连接串与认证细节

2.1 最常用的连接参数解析

psql 的连接参数非常直观，但很多新手第一次用反而会被一堆参数搞晕。其实核心就四个：目标地址、端口、用户名、数据库名。

psql -h 127.0.0.1 -p 5432 -U postgres -d mydb

• -h指定数据库服务器地址，本地连接时可以写127.0.0.1，也可以写/var/run/postgresql这种 Unix socket 目录，后者在某些本地场景下反而更快。
• -p指定端口，PostgreSQL 默认是 5432，如果你在本机装了多个实例，这里就要注意区分。
• -U指定登录用户，最常用的就是超级用户postgres。
• -d指定要连接的数据库名，注意 PostgreSQL 里“数据库”和“模式”是两个层级，这里连接的是数据库层级。

如果省略-h，psql 默认走 Unix socket；如果省略-p，默认 5432；如果省略-U，默认使用当前操作系统用户名；如果省略-d，默认连接与当前用户名同名的数据库。这些默认值看起来方便，但也容易踩坑——比如你本机系统用户名是john，而数据库里根本没有叫john的用户，直接敲psql就会报角色不存在。

另一种非常实用的方式是 Docker 容器。现在的开发环境里 PostgreSQL 多半跑在容器里，进容器操作同样靠 psql：

docker exec -it my-postgres psql -U postgres -d mydb

如果你不想到处查参数，建议把这句存成 alias 或者写进本地脚本，能省不少事。

2.2 URI连接串与密码处理

除了拆开写参数，psql 也支持通过 URI 格式连接串一次性指定所有信息。这种格式在云数据库、配置中心、自动化脚本里非常常见：

psql "postgresql://postgres:your_password@127.0.0.1:5432/mydb"

如果你嫌密码里有特殊字符会出问题，还可以在 URI 后面追加参数：postgresql://postgres@127.0.0.1:5432/mydb?sslmode=require。很多时候云数据库强制要求 SSL，加上sslmode=require就够了。

不过我强烈不建议把密码明文写在命令行里，因为ps -ef能看到所有进程的完整参数，密码等于直接暴露在内网里。更安全的做法是用PGPASSWORD环境变量，或者把连接信息写进~/.pgpass文件：

host:port:database:username:password

psql会自动读取这个文件完成认证，文件权限必须设为0600，否则 psql 会直接忽略它。这些细节平时没人讲，但真正排查认证问题时，它们往往就是关键。

2.3 客户端认证与常见连接错误

连接失败的报错信息五花八门，但绝大多数都离不开三类原因：网络不通、认证失败、目标不存在。先说网络：报错could not connect to server: Connection refused，先确认端口是否真的在监听，再看防火墙有没有放行。PostgreSQL 默认只监听本机回环地址，远程访问必须在postgresql.conf里把listen_addresses改成'*'。

认证失败最常见的是：

FATAL: password authentication failed for user "postgres"

这个报错来自pg_hba.conf的认证规则。PostgreSQL 对每条连接请求按“IP地址 + 用户名 + 数据库名”逐行匹配认证方式，匹配不到就会拒绝。你改了密码却不生效，多半是改完没有 reload 配置。注意pg_hba.conf修改后不需要重启，执行SELECT pg_reload_conf();或pg_ctl reload即可。

还有一类报错是database "mydb" does not exist，这种情况下要先用psql -d postgres连到默认数据库，再确认库名拼写是否准确。另外，密码中含有特殊字符时 URI 需要对特殊字符做百分号编码，比如密码是a@b，连接串里要写成a%40b，不然解析连接串时会把@当作分隔符。

2.4 连上之后先确认环境

进入 psql 交互界面后，最容易被忽略的是提示符本身。提示符结尾如果是=#，说明你是超级用户；如果是=>，则是普通用户。=#表示当前用户是超级用户，别在普通环境里顶着超级用户乱跑。

确认当前连接信息，最直接的是\conninfo，它会返回当前连接的数据库、用户、主机、端口，排查“我到底连的是哪个实例”时特别管用。再配合SELECT current_database(), current_user;确认上下文。很多误操作都发生在“以为自己连的是测试库，实际上在生产库上执行了 DDL”这种情况，所以连上之后先养成分辨环境的习惯。

3. psql交互式元命令全解

3.1 信息查看类元命令：看懂数据库结构

psql 最强大的地方是它的元命令，也就是以反斜杠开头的那一串指令。和 SQL 不同，元命令是在客户端本地解析的，不需要以分号结尾，敲回车就立即执行。

最常用的一批：

• \l：列出所有数据库。
• \c mydb：切换到指定数据库。
• \dt：列出当前模式下的所有表。
• \d table_name：查看表结构、列类型、索引、约束等。想看到更详细的信息，用\d+ table_name。
• \di：列出索引；\ds列出序列；\dv列出视图；\df列出函数；\dn列出模式；\du列出角色（用户）。

我自己用得最多的就是\d+。它比 GUI 工具还直观，能看到列的默认值、表空间、统计信息。排查表结构变更有没有生效时，我基本都是先跑一句\d+看当前实际结构，再对比迁移脚本里的定义。

这里有一个新手常见的错误：在元命令后面加了一个分号，比如\dt;。psql 会把这个分号当成元命令参数的一部分，结果就是提示“没有找到匹配的关系”。记住，元命令结尾不需要分号，SQL 语句才需要分号。

3.2 查询与执行类：不只是SELECT

在 psql 里你当然可以正常写 SQL，但有些执行层面的细节值得单独说。

\timing是一个开关，打开之后每次执行 SQL 都会在底部显示耗时。排查慢查询、对比索引优化前后的性能时，\timing是必备工具。注意它统计的是客户端从发送请求到收到结果的全过程，包含网络开销，本地调试时基本等于服务端执行时间。

\x是扩展显示模式。当一行数据列太多、在屏幕上挤成一团时，\x auto会在列数过多时自动切换成竖排展示，每一列单独占一行。查看用户表里的字段或 JSON 内容时，竖排显示能救命。

\watch 3可以每隔 3 秒重复执行最近一次查询。这个命令在监控任务、观察写入进度时很好用。比如你正在跑一批数据迁移，想知道某个计数是否在持续上涨，写一句SELECT count(*) FROM target_table;然后敲\watch 5，让它每 5 秒刷一次。

\gexec和\gset是两个高级执行命令。\gexec会把当前查询结果当作新的 SQL 逐条执行，适合批量生成 SQL 的场景。\gset则把查询结果存到 psql 变量里，后续可以在同一个会话里引用这些变量。

3.3 输出格式化：从对齐表格到CSV

psql 默认输出是对齐的 ASCII 表格，适合人眼看。但脚本处理时，我们通常需要更干净的数据，这时候就要动\pset：

\pset format unaligned \pset tuples_only on \pset null '[NULL]'

也可以一条命令走完：

\pset format csv SELECT id, name FROM users LIMIT 10;

把格式切到 csv 之后，输出就是标准的 CSV，配合管道重定向就能直接生成文件。不过要注意当前format只对后续查询有效，切回去可以用\pset format aligned。

更进一步，\a和\t是unaligned和tuples_only的快捷开关。\t关闭后结果不再显示列名，只剩数据行，这在脚本中特别常见：psql -At -c "SELECT count(*) FROM users"的输出就是一个纯数字，方便直接赋值给 shell 变量。

另外，\o filename可以把后续查询结果全部写入文件，直到执行\o恢复屏幕输出。在 psql 里做简单报表时，这比每次重新定向终端输出要可控得多。

3.4 环境与脚本类：不只是查询界面

\i filename.sql用于执行一个 SQL 脚本文件，这是非交互式执行之外最常用的执行方式之一。它可以嵌套，也就是说脚本里还能再包含\i调用其他脚本。

\echo和\!会让人感觉 psql 像是 shell 和 SQL 之间的桥梁。\echo输出提示文字，\! ls -l可以直接执行操作系统命令，这在写复杂脚本时非常实用。

\set用来定义 psql 变量：

\set myvar 'hello' SELECT :'myvar';

这里:'myvar'会把它替换成带引号的字符串'hello'，而:myvar不带引号。这是 psql 变量替换中非常重要的细节，直接决定 SQL 语法是否正确、是否安全。关于这一点，第 4 章我会展开讲。

\?会列出所有元命令的帮助，\h SELECT会显示 SELECT 语句的语法帮助。即使你记不住命令细节，靠这两个内置帮助也能摸出路来，比打开网页去查还要快。

4. 脚本化与自动化：psql不是只能手动敲

4.1 非交互执行：-c 与 -f

交互式操作之外，psql 的价值更多体现在自动化场景。通过-c参数可以执行单条 SQL，执行完就退出：

psql -U postgres -d mydb -c "SELECT count(*) FROM users;"

把输出重定向到文件即可生成报表：

psql -U postgres -d mydb -At -c "SELECT id, name FROM users;" > users.txt

执行 SQL 文件用-f：

psql -U postgres -d mydb -f /path/to/script.sql

这里有一个极其重要的选项：ON_ERROR_STOP。psql 在默认情况下，如果脚本中间某条 SQL 报错，会打印错误信息但继续执行后面的语句。对自动化任务来说，这可能会导致“看似跑完、实际部分失败”的隐蔽问题。加上-v ON_ERROR_STOP=1之后，一旦遇到错误就立即退出，并返回非零退出码，方便外层脚本感知失败。

如果需要整份脚本要么全成功、要么全回滚，psql 还提供-1（或--single-transaction）参数，把所有脚本内容包在一个事务里执行。这个参数配合-f使用，是发布数据库变更脚本时的标准做法。

4.2 变量与参数传递：让脚本复用起来

写死的 SQL 脚本没有灵魂。psql 支持变量替换，让同一份脚本在不同环境下复用。

第一种方式是通过-v传参：

psql -v v_table=users -v v_id=1001 -f query.sql

脚本里这样引用：

SELECT * FROM :"v_table" WHERE id = :'v_id';

这里用:"v_table"把变量作为标识符替换，加上双引号防止 SQL 语法问题；用:'v_id'把变量作为字符串字面量替换，自动加上单引号。区分这两个引用方式非常重要，否则很容易拼出语法错误的 SQL，甚至留下 SQL 注入风险。

第二种方式是通过\set在脚本内部定义变量，也可以读取 shell 环境变量：

\set env `echo $PGDATABASE` SELECT :'env';

psql 变量替换在生成动态 SQL、批量迁移、多环境部署中都很好用。我自己经常把“按表名导出数据”“按日期范围清理数据”这类重复操作写成带变量的 SQL 文件，每次执行时只改参数，避免一遍遍手写。

4.3 三种常见自动化模式

第一种是循环批量执行。假设要对一批表做同样的操作，可以用 shell 循环配合 psql：

for tbl in users orders items; do psql -U postgres -d mydb -c "SELECT count(*) FROM $tbl;" done

第二种是定时任务。把巡检语句写进 SQL 文件，配合 crontab 每天执行，并把结果邮件发出去：

0 2 * * * psql -U postgres -d mydb -v ON_ERROR_STOP=1 -f /opt/scripts/daily_check.sql > /var/log/db_check.log 2>&1

定时任务是 psql 自动化最典型的落地场景，稳定可靠，不需要额外的调度依赖。

第三种是生成数据文件。比如每天把前一天的增量数据导出成 CSV：

psql -U postgres -d mydb -c "\copy (SELECT * FROM orders WHERE created_at >= now() - interval '1 day') TO STDOUT WITH CSV HEADER" > orders_$(date +%F).csv

这里用的是\copy而不是COPY。\copy是 psql 客户端的命令，读写的是客户端本地的文件；COPY是服务端命令，读写的是数据库服务器上的文件，后者通常需要超级用户权限。日常导数据到本地文件，基本都用\copy，这也是 psql 元命令比裸 SQL 更灵活的地方。

5. 日常排错与性能检查实战

5.1 连接问题排查思路

连接报错是最常见的求助话题。真到了现场，不要瞎试，按这个顺序排查：

首先确认网络层：ping 目标IP，如果通不了，那是网络问题。再看端口：telnet 目标IP 5432或nc -vz 目标IP 5432，确认数据库端口是否可达。有时候业务方说“数据库连不上”，实际上是把端口写错了。

然后看数据库本身有没有在监听：在服务器上执行pg_isready，这个 PostgreSQL 自带的工具会明确告诉你数据库是否接受连接。

接下来看认证层：翻/var/log/postgresql/下的日志，实际报错原因会写得清清楚楚，例如password authentication failed。根据报错去检查pg_hba.conf中相关条目，注意该文件的匹配规则是从上到下逐条匹配、第一条命中即生效，所以不要在一个host all all all scram-sha-256下面再堆一堆特殊规则，那不会生效。

最后要留意 SSL 相关配置。不少云数据库要求强制 SSL，连接串里不加sslmode=require就会直接报no pg_hba.conf entry for host甚至超时。这个问题排查起来很容易绕弯路，看到连接串先看一眼要不要加 sslmode。

5.2 性能核查的psql日常

psql 配合 PostgreSQL 的系统视图，可以做很多基本性能排查，不需要额外装工具。

先看活跃查询：

SELECT pid, usename, state, now() - query_start AS running_time, query FROM pg_stat_activity WHERE state = 'active' ORDER BY query_start;

这一句能看到当前正在跑哪些查询、跑了多久、是哪条 SQL。配合CARP ALERT或者直接通知业务方处理，能迅速定位到拖垮数据库的大查询。

再看有没有阻塞：

SELECT a.pid AS blocked_pid, b.pid AS blocking_pid, a.query AS blocked_query FROM pg_stat_activity a JOIN pg_stat_activity b ON a.wait_event_type = 'Lock' AND a.pid <> b.pid

锁等待问题在生产环境很常见，一条未提交事务能拖住后面所有相关操作。找到阻塞源头后，再决定是等待还是主动终止它。

分析单条 SQL 性能最直接的是EXPLAIN ANALYZE：

EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 12345;

注意EXPLAIN ANALYZE会真实执行这条 SQL，所以线上大表谨慎使用，可以先加EXPLAIN只看执行计划，不带ANALYZE。

还有表大小检查：

SELECT pg_size_pretty(pg_total_relation_size('users'));

以及数据库大小：

SELECT pg_size_pretty(pg_database_size('mydb'));

这些命令写进巡检脚本，每天跑一遍，磁盘增长趋势一目了然。

5.3 那些容易踩的坑

我用 psql 这么多年，遇到过不少匪夷所思的问题，帮大家排掉几个高频坑。

第一个是编码问题。终端显示正常不代表数据真的没问题。如果出现中文乱码，先确认服务端编码和客户端编码是否一致：

SHOW server_encoding; SHOW client_encoding;

客户端编码可以通过\encoding UTF8切换，也可以通过环境变量PGCLIENTENCODING设置。Windows 的 cmd 下尤其容易出乱码，建议先执行chcp 65001切到 UTF-8。

第二个是历史记录问题。psql 会把每条执行过的 SQL 写进~/.psql_history，如果你不小心在生产库上执行了什么危险的 SQL，这个文件会留下证据。注意保护和定期清理，同时在生产环境慎用交互式 psql 执行敏感操作。

第三个是分页器问题。psql 默认使用less作为分页器，查询结果多时会先进入分页界面，导致脚本化场景下“卡住”的错觉。脚本里可以加上\pset pager off关闭分页，或者设置环境变量PAGER=cat。

第四个是断句问题。SQL 语句里的分号是必需的，但要注意 heredoc 场景下的分号不会自动补齐。用psql <<'SQL'的方法执行语句时，每条 SQL 结尾必须自己加分号，否则它会一直等待输入。

第五个是\copy与COPY的权限差异。在导入导出数据时，COPY是从服务端读写文件，通常只有超级用户能用，而且要求文件在数据库服务器本地；\copy没有这个限制，读的是你本地的文件。分清楚这两者，能免掉很多“明明文件路径没错却说找不到文件”的问题。

6. 我平时最依赖的几组psql组合

最后分享几个我在实际工作中离不开的用法，不算什么高深技巧，但确实帮我省了很多事。

第一组是快速巡检。登录任何一台 PostgreSQL 服务器，我通常会用这几条命令快速判断“这个实例现在健康吗”：\l看库是否正常列出，SELECT count(*) FROM pg_stat_activity;看连接数，再配合\timing跑一条简单的SELECT 1;看延迟是否正常。三十秒之内就能对实例状态有个基本判断。

第二组是统一入口脚本。我习惯把常用的连接串存在~/.pgpass里，再在 shell 里定义好对应的 psql alias。比如alias devdb='psql "postgresql://dev_user@127.0.0.1:5432/dev_db?sslmode=require"'，平时敲devdb直接进入开发库。这样既不用每次输入密码，也不会因为连接参数太长而手忙脚乱。

第三组是.psqlrc个性化配置。psql 启动时会自动读取~/.psqlrc，我在里面配置了统一风格：

\pset null '[NULL]' \pset pager off \set PROMPT1 '%n@%/%R%x=# ' \timing

这样每次进入 psql，会显示用户@库名的提示符，空值显示[NULL]，分页关闭，自动开启耗时统计。这些配置看起来简单，但能极大改善日常使用体验，尤其当你在多个环境之间切换时，提示符会随时提醒你现在到底在哪个库。

总而言之——不，我应该说，实际用下来唯一的心得就是：psql 不需要你背下所有命令，但你需要知道它有这些能力。把最常用的十几条元命令用熟，再加上变量、脚本和格式化的配合，它完全可以替代你手上一半的图形化数据库工具。尤其是当你面对一台没有图形界面的服务器时，psql 就是你最值得信任的伙伴。