企业官网建设流程全解析

• 文档
• 教程
• 知识库

导读

本文聚焦本仓库 postgres 主题下的pg_sleep函数，讲解如何让 SQL 语句在执行过程中主动暂停指定的秒数。文中不仅完整复现了原文档中"延时 5 秒"的实测过程，还结合仓库内statement_timeout、连接管理、慢查询监控等相关笔记，帮助你掌握调试阶段模拟耗时查询、验证超时阈值与监控长时间运行语句的完整实战方案。

一、为什么要让查询"故意变慢"：pg_sleep 的适用场景

正常情况下，我们都希望 SQL 语句以最快的速度在数据库上执行完毕。但在两类场景下，你反而需要让查询"故意"慢下来：

1. 调试与排查阶段：当你在排查连接池占用、锁等待、会话隔离等问题时，需要一个确定会长时间运行的语句来复现现象；
2. 验证超时与监控机制：想确认statement_timeout、连接终止、慢查询监控等机制是否按预期工作，就需要一条"看起来非常耗时"的查询来做试验。

PostgreSQL 为此提供了内置函数pg_sleep。本仓库的 sleeping.md 正是围绕这一函数展开的记录。

二、pg_sleep 基础用法：延时 5 秒的完整实测

pg_sleep接收一个以秒为单位的数值参数，使当前会话的语句执行暂停相应时间。仓库原文档给出了一个非常直观的验证方法——在pg_sleep前后各取一次当前时间now()，观察时间差：

> select now(); select pg_sleep(5); select now(); now ------------------------------- 2016-01-08 16:30:21.251081-06 (1 row) Time: 0.274 ms pg_sleep ---------- (1 row) Time: 5001.459 ms now ------------------------------- 2016-01-08 16:30:26.252953-06 (1 row) Time: 0.260 ms

从输出可以看到三个关键信息：

• pg_sleep(5)这条语句的执行耗时约为5001 毫秒，即整整 5 秒；
• 前后两次now()的结果相差约 5 秒（16:30:21→16:30:26），证明会话确实暂停了执行；
• pg_sleep的返回值为空（pg_sleep列下没有返回任何内容），说明它不返回数据，仅起到延时作用。

参数说明与使用前提

• 参数类型：pg_sleep接受的参数以秒为单位，支持整数也支持小数（如pg_sleep(0.5)表示暂停 500 毫秒），便于更精细地控制延时。
• 生效范围：延时发生在当前后端会话（backend process）内部，暂停的是这条语句所属的连接会话，不影响其他会话的正常执行。
• 适用版本：pg_sleep自 PostgreSQL 早期版本起即为内置函数，可直接使用。

三、延时粒度进阶：面向 interval 与 timestamp 的变体

对于需要按"时长区间"或"指定时刻"延时的场景，PostgreSQL 在后续版本（14 及以上）中提供了两个与pg_sleep配套的变体函数：

• pg_sleep_for(interval)：按一个时间区间延时，例如pg_sleep_for('5 seconds')，语义比裸数字更清晰；
• pg_sleep_until(timestamp with time zone)：一直暂停到指定的时间点再继续执行。

这两个变体与pg_sleep一样都用于测试与调试场景，返回值同样为空。日常若只需"暂停 N 秒"，使用基础版pg_sleep即可；需要表达更明确的时长语义或等待到特定时刻时，可考虑变体函数。

四、与 statement_timeout 联动：让超时机制现出原形

pg_sleep最常见的生产级用途之一，就是配合会话级statement_timeout验证超时保护是否生效。仓库中的 set-a-statement-timeout-threshold-for-a-session.md 记录了完整过程：

先给当前会话设置 30 秒超时阈值（既可用整数毫秒，也可用带单位的字符串）：

> set statement_timeout = '30s'; SET > show statement_timeout; statement_timeout ------------------- 30s (1 row)

随后执行一个必然超时的pg_sleep：

> select pg_sleep(31); ERROR: canceling statement due to statement timeout Time: 30001.997 ms (00:30.002)

可以看到：pg_sleep(31)本应运行 31 秒，但在第 30 秒整时被服务器主动取消，报错canceling statement due to statement timeout。这正是"用一条确定耗时的语句，验证超时阈值是否按预期生效"的典型手法——pg_sleep在这里充当了最可靠的"定时炸弹"。

五、生产实践：用 statement_timeout 守护生产数据库

既然pg_sleep可以用于验证超时机制，那么在生产环境中为所有连接统一设置statement_timeout，就是防止查询"失控"的第一道防线。仓库中的 rails/set-statement-timeout-for-all-postgres-connections.md 展示了如何在 Rails 应用中为所有 PostgreSQL 连接统一配置：

default: &default adapter: postgresql encoding: unicode pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %> variables: statement_timeout: 60000

上述配置将超时设为 60000 毫秒（60 秒）；同样地，也可以用带单位的字符串写法：

variables: statement_timeout: '60s'

该笔记还给出了验证手段——执行一条注定超时的查询：

ActiveRecord::Base.connection.execute('select pg_sleep(62)')

由于超时阈值为 60 秒，这条pg_sleep(62)会在执行到第 60 秒时被提前终止。注意这里的核心逻辑：statement_timeout的取值决定了超时保护的强度，而pg_sleep则是验证这个阈值是否生效的最便捷工具，两者常搭配使用。

六、调试辅助：观察、终止与监控长时间运行的查询

当pg_sleep被用在调试场景时，往往还需要配套的"观察与干预"手段。仓库中与之相关的几篇笔记形成了完整闭环：

1. 查看当前连接与语句状态

通过 list-connections-to-a-database.md 记录的pg_stat_activity视图，可以看到每个连接的进程号、用户与所在数据库：

> select pid, usename, datname from pg_stat_activity; pid | usename | datname -------+------------+----------- 57174 | jbranchaud | hr_hotels 83420 | jbranchaud | pgbyex

2. 终止占用中的连接

当需要强制释放被占用的会话（例如要dropdb但存在活跃连接）时，可借助 terminating-a-connection.md 中的pg_terminate_backend()：

select pg_terminate_backend(pg_stat_activity.pid) from pg_stat_activity where pg_stat_activity.datname = 'sample_db' and pid <> pg_backend_pid();

注意该查询排除了当前会话自身，因此若目标是删除该数据库，还需先退出psql。

3. 监控长耗时操作的真实进度

如果真正的长耗时操作不是人为的pg_sleep，而是生产环境中的大表create index，可以查询pg_stat_progress_create_index视图观察其阶段与进度，详见 inspect-progress-of-long-running-create-index.md。这让你在"查询变慢"时能区分"卡死"与"正常推进"。

七、注意事项与最佳实践

1. pg_sleep只应用于调试与测试：它会让后端进程空转占用连接，在生产环境随意使用会浪费连接资源甚至触发锁等待；
2. 配合statement_timeout使用更安全：无论调试还是验证，都应先设置合理的超时阈值，避免调试语句意外失控（参考第四节做法）；
3. 小数秒参数可精确控制延时粒度：pg_sleep(0.5)即可产生 500 毫秒级的暂停，适合精细复现场景；
4. 观察系统视图佐证效果：pg_stat_activity中处于active状态、wait_event_type为Timeout类的会话正是pg_sleep生效的直接证据；
5. 使用前提：pg_sleep为 PostgreSQL 内置函数，无需安装扩展；其变体pg_sleep_for/pg_sleep_until需要 PostgreSQL 14 及以上版本。

总而言之，pg_sleep是 PostgreSQL 调试工具箱中一个简单却不可或缺的函数：它让你能精确制造"慢查询"，从而验证超时阈值、观察会话状态、测试监控告警链路。本仓库 postgres 目录下的相关笔记，恰好组成了"制造慢查询 → 验证超时 → 观察会话 → 终止连接"的完整调试链条，值得在遇到连接与超时类问题时按序查阅。

• 文档
• 教程
• 知识库