企业官网建设流程全解析

每天连 psql 都要先敲\timing on、\pset null 'NULL'、\x auto这几行命令的开发者，估计不在少数。这些重复动作完全可以交给 psqlrc 文件自动处理。psqlrc 是 psql 启动时自动加载的配置文件，相当于给 psql 塞了一份“开机启动项”，把常用的元命令、格式偏好、变量、按键习惯写进去之后，每次进交互终端都能自动生效。这篇文章我会从文件存放位置、基础配置项、进阶技巧、多环境适配、踩坑排查几个维度，把 psqlrc 的用法彻底讲透。适合所有用 psql 跑 SQL、做数据库运维、写数据分析脚本的人，不管你是刚接触 PostgreSQL 的新手，还是已经用了很多年的老手，都能在配置里翻出点新东西。

1. psqlrc 到底是什么：先搞清楚加载机制

1.1 一个配置文件解决“重复手敲元命令”的痛点

psql 本身有一套非常强大的元命令体系，比如\pset控制输出格式、\set设置变量、\timing开关执行耗时统计。但这些设置在每次新建连接后都会恢复默认值。如果每次都得重新敲一遍，不仅烦，还容易漏。psqlrc 解决的正是这个问题：它把一系列\set、\pset、\echo、\if等指令集中到一个文件里，psql 进程启动时自动按顺序执行，相当于给交互终端做了个性化初始化。

这里有个容易被忽略的点：psqlrc 不仅影响 psql 的交互式会话，也会影响通过psql -f执行 SQL 脚本的行为。因为启动加载配置是非交互模式同样存在的逻辑。所以很多人在脚本里被 psqlrc 里的\timing on或者自定义 PROMPT 干扰，还以为脚本写错了。后面会专门讲怎么避免这个问题。

1.2 文件位置与加载顺序：用户级和全局级怎么选

psqlrc 的查找路径分两类：

• 用户级：Unix 类系统默认读取$HOME/.psqlrc，也就是~/.psqlrc。
• 全局级：PostgreSQL 安装时通常会配一个全局文件，比如/etc/psqlrc或者/usr/local/etc/psqlrc，具体位置跟发行版和安装方式有关。

用户级和全局级同时存在时，不同版本的 PostgreSQL 对先后顺序的处理有差异。有的版本先读全局再读用户文件，有的反过来。为了不在这上面踩坑，最稳妥的做法是：在用户级文件里显式设置一遍你所有需要定制的配置项，不要把最终结果寄托在加载顺序上。比如全局配置里开了\pset null 'NULL'，你不想用，就在~/.psqlrc里写\pset null ''覆盖掉，确保最终生效的是你要的值。

另外，还有一个环境变量可以完全自定义配置文件路径：PSQLRC。例如PSQLRC=/opt/dba/mypsqlrc psql启动 psql 时，就会只读取/opt/dba/mypsqlrc这个文件。这个特性在区分不同环境配置时非常有用，后面专门讲。psql 还提供了一个选项让配置完全失效：psql -X。调试问题的时候，-X参数能帮你判断异常到底是不是 psqlrc 里的配置引起的。

2. 从零开始配：这些基础配置项值得写进去

2.1 让查询结果变整齐的输出三件套

我用 psqlrc 配置的第一优先级，永远是格式化输出。默认情况下 psql 的空值显示是一对引号，区分不出到底是空字符串还是 NULL，列太长还要手动调整。我一般会在~/.psqlrc里放这几行：

\pset null 'NULL' \pset pager off \x auto \pset border 2

每一个都有讲究。\pset null 'NULL'把 SQL 结果集中的空值统一显示成NULL四个字母，排查数据问题的时候一眼就能看出哪个字段是空的。\pset pager off是让结果不分页，直接输出，适合终端滚动缓冲区足够大的场景。如果你的终端缓冲很小，也可以改成\pset pager on。

\x auto是 PostgreSQL 11 之后特别好用的一个选项：结果集列数过多、宽度超过终端时自动切换为扩展显示模式，每行字段变成“键值对”竖排。这个配置对排查多列明细数据尤其有用，清晰度比人工调整列宽高得多。\pset border 2则让表格带上完整边框，视觉上更整齐。

提示：\x auto在你明确想要固定竖排或横排结果时会有干扰。比如脚本导出表格数据，我一般会在脚本里追加\x off或者直接psql -X绕过用户配置。

2.2 让历史命令更顺手：HISTSIZE、HISTFILE 与去重

psql 的交互式终端自带命令历史，但默认的存档位置和记录条数不一定适合你的习惯。我推荐在配置里显式设置：

\set HISTSIZE 5000 \set HISTFILE ~/.psql_history \set HISTCONTROL ignoredups

HISTSIZE控制当前会话里保留多少条已执行命令，默认值通常只有 500，对于长期在 psql 里摸爬滚打的人来说太少了。设成 5000 之后翻历史基本不会踩到“命令怎么不在了”的边界。HISTFILE把历史记录写到独立文件，方便备份和迁移。HISTCONTROL ignoredups是个很实用的逃生口：连续执行同一条重复 SQL 时，历史里只保留一条，向上翻方向键时不会被一串重复命令刷屏。

有一点需要提醒：psql 的历史记录文件默认权限可能是 0600，如果你在多台机器同步，复制粘贴历史文件后注意检查权限，否则 psql 可能因为权限拒绝写入或读取历史。

2.3 让交互反馈更明确：执行耗时、错误输出、事务控制

\timing on是大多数人都会开的配置，但很多人不知道它有一个坑：它会统计服务端执行时间和客户端传输时间的总和，对于超大结果集，耗时会明显偏高。我仍然建议默认打开，因为它对感知慢查询的价值远大于那点偏差。

错误输出方面，\set VERBOSITY verbose能显示更详细的错误位置信息。配合 PostgreSQL 的错误上下文，调试复杂存储过程时，直接告诉你错误发生在函数的第几行，这比默认的简短错误信息好用太多。

事务控制这块，默认情况下 psql 是每条语句自动提交。如果你经常在一个事务里做多步操作，可以加\set AUTOCOMMIT off。但我个人不建议全局开启，因为它会影响很多正常脚本的执行逻辑，容易忘了commit导致事务一直挂着。折中方案是只在特定业务库的连接配置里通过条件判断开启，具体方法在后面的多环境适配部分讲。

下面给一份开箱即用的基础配置块，可以直接抄进~/.psqlrc：

\set HISTSIZE 5000 \set HISTCONTROL ignoredups \timing on \pset null 'NULL' \pset border 2 \x auto \set VERBOSITY verbose

3. 再进一步：psqlrc 里的进阶玩法

3.1 自定义提示符：一眼看清“我在哪台机器的哪个库”

psql 的提示符由PROMPT1、PROMPT2、PROMPT3这几个变量控制。默认提示符"postgres=#"信息量有限，尤其是在多环境切换频繁的时候，很容易出现“我以为我在生产库执行，结果连的是测试库”这种事故。用 psqlrc 做自定义提示符，等于给命令终端加了个“环境识别外套”。

常用占位符我列一下：%n表示用户名，%m是数据库服务端主机名（在客户端显示的主机名），%M是全限定的主机名，%d是当前数据库名，%#根据你是否有超级用户权限显示#或>，%/是当前工作目录。把这些组合起来：

\set PROMPT1 '%n@%m:%d> ' \set PROMPT2 '%n@%m:%d(%R)> '

效果类似：

dba@pg-prod:appdb>

这样一眼就能看到当前用户、服务器、库名。多环境对比时，我还会把测试库提示符加上不同颜色，减少误操作概率。颜色用 ANSI 转义序列就能实现，但需要终端支持，且建议不要用太复杂的颜色，否则远程 SSH 场景下容易出乱码。简单做法例如：

\set PROMPT1 '%[%033[1;31m%]%n@%m:%d%[%033[0m%]%[%033[1;36m%]> %[%033[0m%]'

这行配置我实际用过一段时间，红色提示符确实让我在测试环境和生产环境之间切换时多了一道心理防线。不过要提醒的是，部分终端和 Windows 自带的控制台对 ANSI 颜色兼容性不一，一旦发现乱码，建议优先把它简化成纯文本格式。

3.2 用变量和别名把长 SQL 变成短命令

psql 的\set不只能存数值，还能把一段 SQL 文本存进变量，配合:变量名做替换。比如我经常要查一个订单表的最晚更新时间：

\set last_order_time "select max(updated_at) from app.orders;"

之后在 psql 里输入:last_order_time再回车，就会展开成完整的 SQL 执行。配合\g还能做更多花活：

\set sess 'select pid, usename, state, query from pg_stat_activity where pid = pg_backend_pid();'

这些变量本质上就是宏。psql 15 及更新版本还提供了正式的\alias元命令，可以把一组命令打包成一个别名，支持参数。如果 PG 版本足够新，我建议优先尝试\alias，因为它更规范，也更容易维护。老版本环境下就老老实实用变量替换，语法上虽然没有参数能力，但应付短 SQL 和固定查询已经足够。

注意：变量值里的分号要格外小心，尤其是存储多条 SQL 的时候。psql 是逐条发送给服务端执行的，如果变量值里带了;，展开后的行为可能和预期不一致。不确定时先用单条 SQL 验证再放进配置里。

3.3 在 psqlrc 里执行 SQL？可以，但要克制

psqlrc 本质上是一个被 psql 逐行执行的脚本，所以它里面完全可以写普通 SQL 语句，比如连接后自动查询当前数据库版本：

select version();

这么做的结果是每次启动 psql 都会在界面上输出一段查询结果。好处是连接信息一目了然，坏处是如果配置里塞了很多这种“启动查询”，交互体验会变得很啰嗦，而且每次连接多消耗一次往返。我的建议是：启动时只做必要的环境标注，比如输出一个简短提示，用\echo就够了，复杂动态检测交给后面的条件判断逻辑。

4. 多环境、多版本适配：让一套配置在不同机器上都能用

4.1 按数据库版本做条件加载

PostgreSQL 的 psql 老版本不支持某些新元命令，比如\x auto在旧版本上就不认识。如果直接把整套配置同步到一台装了老版本 PG 的机器上，启动时会报错。这时候\if就有用了。psql 支持在脚本里写条件判断，语法类似：

\if :VERSION >= 11 \x auto \endif

但这里有个细节坑：VERSION变量是字符串格式的，比如"15.4"，直接拿字符串和数字比较，结果是按字符串规则比较的，"9.6" >= "11"会返回真，因为字符'9'大于'1'。所以这种简单写法不可靠。

更稳的做法是在已建立连接后，执行一个 SQL 表达式来判断服务端版本：

\if (SELECT current_setting('server_version_num')::int >= 110000) \x auto \endif

server_version_num是类似150004这样的整数，直接和数字比较不会踩字符串排序的坑。但要注意，这种方式要求 psqlrc 在数据库连接建立之后才执行，psql 读取 psqlrc 的时机本来就是连接建立后，所以这个方法是可行的。如果涉及没有数据库连接的场景，psql -X绕过全配置文件即可。

4.2 按用户和数据库做差异化配置

很多时候我希望在同一个~/.psqlrc里，用不同角色连接不同数据库时加载不同的行为。比如我是数据库管理员时提示符用红色，用普通账号查询时提示符用绿色。psql 的条件判断可以直接基于 SQL 表达式，所以可以这样写：

\if (SELECT current_setting('is_superuser') = 'on') \set PROMPT1 '%n@%m:%d# ' \else \set PROMPT1 '%n@%m:%d> ' \endif

current_setting('is_superuser')返回"on"或"off"，再加一个布尔表达式，就能实现不同权限角色显示不同提示符。这个方法很实用，误操作高危环境的概率能降不少。类似的思路还能用在只读连接的业务账号上：先判断current_user，匹配到运维账号时自动打开\timing on，匹配到报表账号就关闭。

4.3 利用 PSQLRC 环境变量拆分多个配置

如果一台机器上有多个业务线，每个业务线的查询风格差异很大，那就没必要所有东西挤在一个~/.psqlrc里。利用$PSQLRC环境变量，可以按场景拆成多份配置。比如在 shell 的配置里加几个别名：

alias dev-psql='PSQLRC=$HOME/.psqlrc-dev psql -d appdb' alias prod-psql='PSQLRC=$HOME/.psqlrc-prod psql -d appdb'

这样开发库连接就加载.psqlrc-dev，生产库连接加载.psqlrc-prod，互不干扰。生产环境配置里可以加\set ON_ERROR_STOP on、提示符用红色、默认关闭分页；开发环境则可以宽松一些，打开分页和耗时统计。这个模式对 DBA 和经常跨环境操作的开发者来说，几乎是最实用的一招。

5. 实战排查：我踩过的 psqlrc 坑和解决方案

5.1 启动时突然报错：多半是语法或权限问题

psqlrc 里的内容不是 SQL，而是 psql 元命令。元命令写错参数、变量加了中文引号、或者某个配置项在低版本 psql 里不存在，启动连接时就会抛出一堆错误信息，然后继续进入会话。很多人遇到这种情况会以为是数据库故障，实际上一行psql -X postgres就能确认问题范围。-X会跳过所有 psqlrc 配置，启动干净了，那问题基本就锁定在配置文件里。

如果配置文件本身权限不对，比如全局 psqlrc 被改成了 777，有些安全策略较严格的系统也会在读取时报错。解决办法是让配置文件和 psql 二进制文件的属主匹配，权限保持在 0644 或者更严格。

我自己的排查流程是：先psql -X确认基础连接正常，再psql -v VERBOSITY=verbose加载配置看详细报错，最后根据报错里的行号和元命令名去编辑器里定位。为了快速定位问题行，我还会用\set ECHO all临时放到 psqlrc 开头，这样加载过程会把每条配置命令都输出到屏幕。

5.2 执行 SQL 脚本时输出被“污染”

这是最常见的隐形坑。很多人写好了一个.sql文件，在命令行里用psql -f script.sql执行，结果发现输出里多了一堆耗时统计、空值显示、分页提示，甚至脚本结果格式完全和自己预期不符。原因就是 psql 启动时加载了你~/.psqlrc里的配置。

解决方式主要有三种：

• 脚本执行时用psql -X -f script.sql，禁用用户和系统配置。
• 如果想保留一部分变量但禁用格式配置，可以在脚本开头写\pset pager off、\timing off等反向覆盖。
• 自动化、定时任务里的 psql 调用，一律在脚本参数里显式加-X，不要依赖环境。

我负责的某个数据导出任务就是因为 psqlrc 里开了\x auto，导出的结果被自动切成竖排，下游解析程序完全读不了。后来把所有自动化脚本全部换成-X或-tA组合，这种“配置污染”就再也没出现。

5.3 配置明明写了却不生效？先检查这几个位置

这类问题通常有四种可能。

第一，psqlrc 文件位置不对。你改了/etc/psqlrc但当前用户用的是用户级配置，全局文件改得再多都不生效。可以用psql -E调试模式，或者直接在配置里加一行\echo 'load ok'，确认到底加载的是哪个文件。

第二，配置项被后面的内容覆盖。psqlrc 是顺序执行的，后出现的\pset、\set会覆盖前面的同项配置。比如你文件末尾写了一个\pset border 0，那之前设置的border 2自然就没了，排查时从下往上找，看看有没有反向设置。

第三，环境变量$PSQLRC被设置成别的文件路径，导致~/.psqlrc根本没被读取。直接在 shell 里echo $PSQLRC就能判断。

第四，修改配置后用的是已经存在的会话。psqlrc 只在 psql 进程启动时加载，你改完文件后，让老会话继续待在交互终端，它当然不会重新读文件。重新连一次即可。

5.4 一张表解决常见问题

6. 一份可以直接参考的完整配置模板

下面是我个人常用的配置模板，去掉了一些太重口味的花活，保留了稳定性和可维护性，拿给读者做参照。可以直接保存为~/.psqlrc使用，但建议逐行理解后再动手改，别无脑复制：

-- 历史与交互体验 \set HISTSIZE 5000 \set HISTFILE ~/.psql_history \set HISTCONTROL ignoredups -- 事务与错误控制 \set VERBOSITY verbose \set ON_ERROR_STOP off -- 输出格式 \pset border 2 \pset null 'NULL' \x auto \timing on -- 提示符：用户名@主机名:数据库名> \set PROMPT1 '%n@%m:%d> ' \set PROMPT2 '%n@%m:%d(%R)> ' -- 常用查询快捷变量 \set active "select pid, usename, application_name, client_addr, state, query from pg_stat_activity where pid <> pg_backend_pid() order by pid;" \set locks "select pid, locktype, mode, granted, relation::regclass as rel from pg_locks where not granted order by pid;"

模板里没有加入AUTOCOMMIT off，也没有塞大量颜色控制，原因很简单：工作流越简单越不容易出错。颜色这种花活放多了，换终端、换系统、换 SSH 客户端都会成为新问题的来源。

有一点要特别说：\set ON_ERROR_STOP off是交互模式的合理选择。但如果你这段配置同时用于脚本执行，可能反而希望它是on。这时候同样建议脚本调用显式加-v ON_ERROR_STOP=1参数，而不是去改全局配置。脚本是脚本，交互是交互，两者的容错策略本来就不一样。

7. 个人体会：psqlrc 配置要会“做减法”

基于我几年的实操经验，最后想多说一点：psqlrc 是拿来解决重复劳动的，不是一个“什么都塞进去”的玩具。刚开始接触的时候，很容易把它越配越厚，今天加个颜色，明天加个动态查询，后天再塞一堆别名，最后维护成本和切换负担反而超过了收益。我见过同事的配置文件几百行，大量内容他自己都记不住，换了环境还得费劲删减。

我自己的原则是：配置只放三类东西——稳定的格式偏好、影响安全的提示符区分、常用的查询快捷方式。其它临时性、实验性的东西用完就删。另外，不同机器之间同步 psqlrc 时，务必检查 PostgreSQL 版本差异，用上\if条件判断来兼容老版本功能，否则同步过去的第一天就会在启动时收到一堆报错。

如果你之前从没碰过 psqlrc，建议按这个顺序开始：先配一个只有三行内容的文件，比如\timing on、\pset null 'NULL'和自定义提示符，用上一周，再用第 2 节的基础配置做增量，最后再考虑进阶技巧。慢慢加上去，你的 psql 交互体验会稳定变好，而且你也会慢慢摸清楚每一条配置在真实工作里到底解决了什么问题。