PostgREST Schema Cache 完全指南元数据缓存、重载机制与自动刷新实践【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest导读PostgREST 通过读取 PostgreSQL 系统目录system catalog中的元数据把数据库表、视图、外键关系、函数等抽象成可直接通过 HTTP 访问的 REST 资源——例如 资源嵌入resource embedding 就依赖外键关系推断。这些元数据查询开销高昂PostgREST 因此引入了Schema Cache模式缓存来避免重复查询。本指南以 docs/references/schema_cache.rst 为骨架深入讲解 Schema Cache 的构成、何时会过期、四种重载方式Unix 信号、NOTIFY 通知、防抖合并、事件触发器自动刷新并结合当前仓库源码揭示其底层实现帮助你掌握让 Schema Cache 始终与数据库实际结构保持同步的完整运维方案。Schema Cache 是什么PostgREST 的数据库结构镜像PostgREST 无法凭空知道数据库里有哪些表、哪些列、哪些外键关系它必须在启动时以及之后每次重载时向 PostgreSQL 查询这些元数据并在内存中构建一份结构化快照供所有请求使用。从源码结构看这份快照定义在 src/library/PostgREST/SchemaCache.hs 的SchemaCache数据类型中包含五大部分字段含义用途示例dbTables表、视图、物化视图及其列、主键、可插入/可更新/可删除标记决定哪些资源可被GET/POST/PATCH/DELETEdbRelationships外键推断出的表间关系M2O、O2O、O2M、M2M支撑 资源嵌入 的selectchild(*)语法dbRoutines存储函数RPC及其参数、返回类型、易变性支撑/rpc/xxx端点dbRepresentations域domain类型到 JSON/Text 的隐式转换支撑 域表示dbMediaHandlers媒体类型处理器自定义聚合/函数支撑 媒体类型处理器每次加载完成后PostgREST 会输出一行统计摘要见 src/library/PostgREST/SchemaCache.hs 的showSummary形如Schema cache loaded 15 Relations, 8 Relationships, 8 RPCs, 0 Domain Representations, 4 Media Type Handlers这些缓存被存放在AppState的stateSchemaCache :: IORef (Maybe SchemaCache)中见 src/library/PostgREST/AppState/Types.hs所有 API 请求在处理时都会读取这份内存镜像而不再反复查询数据库。缓存查询为什么贵一组复杂的系统目录查询Schema Cache 并非一次简单查询而是一组针对pg_catalog的深度查询。从 src/library/PostgREST/SchemaCache.hs 的querySchemaCache可见它在一次事务内按序执行 7 个查询allTablestablesSqlQuery从pg_class/pg_attribute/pg_constraint等取表、列、默认值、可更新性、主键列allViewsKeyDependencies递归解析视图定义pg_rewrite提取视图的 PK/FK 依赖allM2OandO2ORels从pg_constraint提取多对一与一对一关系allFunctionsfuncsSqlQuery从pg_proc提取函数签名、参数、返回类型allComputedRels识别计算关系以表类型为参数并返回表类型的函数dataRepresentations从pg_cast提取域类型到 JSON/Text 的隐式转换mediaHandlers从pg_proc/pg_aggregate提取自定义媒体类型处理器。查询执行前会先执行set local schema 清空搜索路径以确保所有对象都以schema.name全限定名形式返回见 src/library/PostgREST/SchemaCache.hs。加载完成后还会冲刷连接池flushPool因为连接会缓存 PostgreSQL 目录信息不清空会导致新结构不可见见 src/library/PostgREST/AppState/Reload.hs。性能说明与诊断手段Schema Cache 查询经过了持续优化即使面对复杂数据库也保持较快在info级别日志中可看到汇总耗时例如Schema cache queried in 3.8 milliseconds示例见 docs/references/observability.rst。若这些查询变慢最可能的原因是系统目录膨胀system catalog bloat即大量 DDL 操作导致的目录碎片化可通过VACUUM相关手段缓解。把log-level设为debug后PostgREST 会输出每个 schema cache 查询的单独耗时。其实现位于 src/library/PostgREST/SchemaCache.hs在每个查询前后通过set_config写入clock_timestamp()计时事务结束时用extractTimings一次性提取 7 个查询各自的毫秒耗时。Schema Cache 为什么会过期何时需要重载Schema Cache 是数据库结构的内存快照。当你在数据库里执行 DDL建表、加列、改外键、建视图、创建函数等之后这份快照就与实际结构不一致了——例如新加了一个表API 上却看不到它新增了外键嵌入查询却报找不到关系。因此任何结构变更后都需要重载 Schema Cache。重载的三种途径Unix 信号手动触发适合单机/脚本运维PostgreSQL 通知NOTIFY从数据库内部或外部进程触发适合云托管容器、Windows 等无法发送信号的场景事件触发器Event Trigger自动刷新DDL 一旦提交自动通知做到无感同步。几点注意引自 docs/references/schema_cache.rst如果重载失败例如statement_timeout或连接池超时PostgREST 不会崩溃而是以尽力而为best effort的方式继续服务已有缓存下的请求若开启了 db-config数据库内配置一次 Schema Cache 重载会连带重载配置二者共享同一条加载链路。从 src/library/PostgREST/AppState/Reload.hs 的retryingSchemaCacheLoad可见加载流程会依次查询 PostgreSQL 版本、读取数据库内配置readInDbConfig、再查询 Schema Cache。手动重载使用 Unix 信号 SIGUSR1在不重启服务进程的前提下向 PostgREST 进程发送SIGUSR1即可触发一次 Schema Cache 重载killall -SIGUSR1 postgrest使用 Docker 时docker kill -s SIGUSR1 container # 或使用 docker-compose docker-compose kill -s SIGUSR1 service其中container/service分别替换为实际的容器名或 compose 服务名。从数据库内部重载NOTIFY pgrst 通知PostgREST 启动时会对 PostgreSQL 执行LISTEN监听一个通知频道默认名为pgrst可通过 db-channel 配置、用 db-channel-enabled 开关对应源码 src/library/PostgREST/Config.hs。在任意数据库会话中执行NOTIFY pgrst, reload schema;通知消息与动作的对应关系详见 docs/references/listener.rstNOTIFY 消息触发动作NOTIFY pgrst, reload schema;重载 Schema CacheNOTIFY pgrst, reload config;重载配置NOTIFY pgrst;空消息同时重载两者消息分发逻辑在 src/library/PostgREST/AppState/Reload.hs 的handleNotification中实现空消息与reload schema走缓存重载reload config走配置重载其他消息一律忽略。该方式特别适合无法发送 Unix 信号的场景如云托管容器、Windows 系统。注意LISTEN/NOTIFY在 PostgreSQL 只读副本read replica上不可用——在副本上执行LISTEN pgrst会得到ERROR: cannot execute LISTEN during recovery。解决思路是让LISTEN会话连主库、业务连接池仍用副本通过 libpq 多主机连接串 target_session_attrs实现PostgREST 会对LISTEN会话强制target_session_attrsread-write且read-only需要 libpq 14例如db-uri postgres://read_replica.host,primary.host/mydb?target_session_attrsread-only监听器的自动恢复如果LISTEN连接意外断开监听器会无限重试采用指数退避exponential backoff最大退避间隔 32 秒每次重试都会记录日志见 docs/references/listener.rst。对应实现是 src/library/PostgREST/AppState/Reload.hs 的retryingListennextDelay从 1 秒开始逐次翻倍直到 32 秒封顶。可通过 db-pool-automatic-recovery默认true关闭自动恢复关闭后连接丢失将直接终止进程。恢复连接后监听器会重新加载 Schema Cache 与配置确保不丢失断连期间的结构变更。防抖机制突发通知的合并处理当短时间内产生多个NOTIFY pgrst事件时PostgREST 不会为每条通知都触发一次重载而是采用**防抖debouncing**策略。分两种情况同一事务内多次NOTIFYPostgreSQL 自身会对同一事务内的相同NOTIFY事件去重——事务提交前即使执行多条NOTIFY pgrst提交后也只会投递一条通知给 PostgREST。跨事务的短时间突发通知PostgREST 将事件放入一个100 毫秒的时间窗口内合并窗口内第一条通知到达时立即执行一次重载突发结束后再执行一次一个窗口内最多执行两次。这一机制对应 src/library/PostgREST/Debounce.hs 的makeDebouncer内部常驻一个 worker 线程trigger通过向MVar写入标志唤醒 worker 执行动作由于MVar只能容纳一个标志突发期间多次触发会被合并为一次tryPutMVar在已有标志时直接丢弃。该防抖器作为debouncedSCacheLoader字段存入AppState见 src/library/PostgREST/AppState/Types.hs所有通知触发的重载都经由此路径。自动重载事件触发器 NOTIFY 的完整方案使用事件触发器Event Trigger可以让 Schema Cache 在每次 DDL 提交后自动刷新做到忘记缓存存在。基础版监控所有 ddl_command_end-- 创建事件触发器函数 CREATE OR REPLACE FUNCTION pgrst_watch() RETURNS event_trigger LANGUAGE plpgsql AS $$ BEGIN NOTIFY pgrst, reload schema; END; $$; -- 该事件触发器会在每次 ddl_command_end 事件后触发 CREATE EVENT TRIGGER pgrst_watch ON ddl_command_end EXECUTE PROCEDURE pgrst_watch();此后只要pgrst_watch被触发PostgREST 就会自动重载 Schema Cache。禁用自动刷新只需删除触发器DROP EVENT TRIGGER pgrst_watch精细化版只监听与 Schema Cache 相关的事件基础版会对所有DDL 事件包括函数内部创建临时表等无关操作触发通知造成无谓重载。更优的做法是通过pg_event_trigger_ddl_commands()与pg_event_trigger_dropped_objects()过滤出真正影响 Schema Cache 的对象类型完整代码引自 docs/references/schema_cache.rst-- 监控 CREATE 和 ALTER CREATE OR REPLACE FUNCTION pgrst_ddl_watch() RETURNS event_trigger AS $$ DECLARE cmd record; BEGIN FOR cmd IN SELECT * FROM pg_event_trigger_ddl_commands() LOOP IF cmd.command_tag IN ( CREATE SCHEMA, ALTER SCHEMA , CREATE TABLE, CREATE TABLE AS, SELECT INTO, ALTER TABLE , CREATE FOREIGN TABLE, ALTER FOREIGN TABLE , CREATE VIEW, ALTER VIEW , CREATE MATERIALIZED VIEW, ALTER MATERIALIZED VIEW , CREATE FUNCTION, ALTER FUNCTION , CREATE TRIGGER , CREATE TYPE, ALTER TYPE , CREATE RULE , COMMENT ) -- 忽略 pg_temp 临时 schema 中的对象避免函数内建临时表触发重载 AND cmd.schema_name is distinct from pg_temp THEN NOTIFY pgrst, reload schema; END IF; END LOOP; END; $$ LANGUAGE plpgsql; -- 监控 DROP CREATE OR REPLACE FUNCTION pgrst_drop_watch() RETURNS event_trigger AS $$ DECLARE obj record; BEGIN FOR obj IN SELECT * FROM pg_event_trigger_dropped_objects() LOOP IF obj.object_type IN ( schema , table , foreign table , view , materialized view , function , trigger , type , rule ) AND obj.is_temporary IS false -- 排除 pg_temp 临时对象 THEN NOTIFY pgrst, reload schema; END IF; END LOOP; END; $$ LANGUAGE plpgsql; CREATE EVENT TRIGGER pgrst_ddl_watch ON ddl_command_end EXECUTE PROCEDURE pgrst_ddl_watch(); CREATE EVENT TRIGGER pgrst_drop_watch ON sql_drop EXECUTE PROCEDURE pgrst_drop_watch();要点说明ddl_command_end事件在 DDL 命令完成后触发覆盖CREATE/ALTER类操作sql_drop事件专门覆盖DROP类操作精细版过滤掉pg_temp中的对象——函数执行时创建临时表是常见行为不应触发全局缓存重载COMMENT也被纳入监控因为对象注释会出现在 Schema Cache 的列描述/表描述中影响 OpenAPI 输出与Prefer相关行为。重载链路与失败恢复底层如何工作从源码层面看一次成功的重载会经历完整链路src/library/PostgREST/AppState/Reload.hs查询 PostgreSQL 版本并校验是否受支持同时初始化连接池若启用 db-config读取数据库内配置在单事务内执行 7 个 schema cache 查询querySchemaCache将新快照写入stateSchemaCache并把缓存状态标记为pending恢复中再置为loaded冲刷连接池清除连接上缓存的旧目录信息通过观察者Observation机制记录SchemaCacheQueriedObs查询耗时与SchemaCacheLoadedObs加载耗时 统计摘要最终进入日志与指标见 src/library/PostgREST/Observation.hs。值得注意的细节启动时 PostgREST 会等待首次Schema Cache 加载完成或进入重试状态后才开始监听 API 端口——SchemaCacheStatus的注释明确指出空值表示启动初始加载见 src/library/PostgREST/AppState/Types.hs加载失败时进入重试循环retryPolicy使用capDelay 32s $ exponentialBackoff 1s即 1 秒起步、翻倍递增、32 秒封顶的指数退避重载期间的请求在pending状态下继续以旧缓存服务属于文档所述的best effort语义。观察与验证日志、指标与测试日志info级别下stderr 会输出Schema cache queried in ... milliseconds、Schema cache loaded ... Relations, ...以及监听器消息如Listening for database notifications on the pgrst channel、Received a ... message on the pgrst channel示例见 docs/references/observability.rst指标Schema Cache 查询/加载耗时也通过 Metrics 暴露可在 Prometheus 端点观测调试log-level debug时可看到 7 个查询各自的耗时明细测试佐证仓库中 test/spec/Feature/ConcurrentSpec.hs 等并发/重载相关测试覆盖了 Schema Cache 在请求并发下的加载与重载行为test/io/test_reloading.py则从 IO 层验证了配置与 Schema Cache 的重载流程。想深入了解缓存数据结构与查询细节可直接阅读 src/library/PostgREST/SchemaCache.hs 的注释与 SQL。小结选择适合你的重载策略场景推荐方式单机/脚本运维想立即生效killall -SIGUSR1 postgrestDocker / docker-composedocker kill -s SIGUSR1 container云托管容器、Windows、无法发信号的环境NOTIFY pgrst, reload schema;结构变更频繁、希望完全自动事件触发器 NOTIFY建议使用精细版过滤pg_temp多租户/大量 DDL 突发依赖内置 100ms 防抖窗口自动合并理解 Schema Cache 的构成与刷新机制是安全运维 PostgREST 的关键一环它决定了 API 暴露的结构是否与数据库一致也决定了你在执行 DDL 之后何时才能看到新表、新列、新关系。借助信号、NOTIFY 或事件触发器你可以把这层缓存完全纳入自动化体系。【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 22:53:12 · 阅读 1.2k PostgREST Schema Cache 完全指南：元数据缓存、重载机制与自动刷新实践
PostgREST Schema Cache 完全指南元数据缓存、重载机制与自动刷新实践【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest导读PostgREST 通过读取 PostgreSQL 系统目录system catalog中的元数据把数据库表、视图、外键关系、函数等抽象成可直接通过 HTTP 访问的 REST 资源——例如 资源嵌入resource embedding 就依赖外键关系推断。这些元数据查询开销高昂PostgREST 因此引入了Schema Cache模式缓存来避免重复查询。本指南以 docs/references/schema_cache.rst 为骨架深入讲解 Schema Cache 的构成、何时会过期、四种重载方式Unix 信号、NOTIFY 通知、防抖合并、事件触发器自动刷新并结合当前仓库源码揭示其底层实现帮助你掌握让 Schema Cache 始终与数据库实际结构保持同步的完整运维方案。Schema Cache 是什么PostgREST 的数据库结构镜像PostgREST 无法凭空知道数据库里有哪些表、哪些列、哪些外键关系它必须在启动时以及之后每次重载时向 PostgreSQL 查询这些元数据并在内存中构建一份结构化快照供所有请求使用。从源码结构看这份快照定义在 src/library/PostgREST/SchemaCache.hs 的SchemaCache数据类型中包含五大部分字段含义用途示例dbTables表、视图、物化视图及其列、主键、可插入/可更新/可删除标记决定哪些资源可被GET/POST/PATCH/DELETEdbRelationships外键推断出的表间关系M2O、O2O、O2M、M2M支撑 资源嵌入 的selectchild(*)语法dbRoutines存储函数RPC及其参数、返回类型、易变性支撑/rpc/xxx端点dbRepresentations域domain类型到 JSON/Text 的隐式转换支撑 域表示dbMediaHandlers媒体类型处理器自定义聚合/函数支撑 媒体类型处理器每次加载完成后PostgREST 会输出一行统计摘要见 src/library/PostgREST/SchemaCache.hs 的showSummary形如Schema cache loaded 15 Relations, 8 Relationships, 8 RPCs, 0 Domain Representations, 4 Media Type Handlers这些缓存被存放在AppState的stateSchemaCache :: IORef (Maybe SchemaCache)中见 src/library/PostgREST/AppState/Types.hs所有 API 请求在处理时都会读取这份内存镜像而不再反复查询数据库。缓存查询为什么贵一组复杂的系统目录查询Schema Cache 并非一次简单查询而是一组针对pg_catalog的深度查询。从 src/library/PostgREST/SchemaCache.hs 的querySchemaCache可见它在一次事务内按序执行 7 个查询allTablestablesSqlQuery从pg_class/pg_attribute/pg_constraint等取表、列、默认值、可更新性、主键列allViewsKeyDependencies递归解析视图定义pg_rewrite提取视图的 PK/FK 依赖allM2OandO2ORels从pg_constraint提取多对一与一对一关系allFunctionsfuncsSqlQuery从pg_proc提取函数签名、参数、返回类型allComputedRels识别计算关系以表类型为参数并返回表类型的函数dataRepresentations从pg_cast提取域类型到 JSON/Text 的隐式转换mediaHandlers从pg_proc/pg_aggregate提取自定义媒体类型处理器。查询执行前会先执行set local schema 清空搜索路径以确保所有对象都以schema.name全限定名形式返回见 src/library/PostgREST/SchemaCache.hs。加载完成后还会冲刷连接池flushPool因为连接会缓存 PostgreSQL 目录信息不清空会导致新结构不可见见 src/library/PostgREST/AppState/Reload.hs。性能说明与诊断手段Schema Cache 查询经过了持续优化即使面对复杂数据库也保持较快在info级别日志中可看到汇总耗时例如Schema cache queried in 3.8 milliseconds示例见 docs/references/observability.rst。若这些查询变慢最可能的原因是系统目录膨胀system catalog bloat即大量 DDL 操作导致的目录碎片化可通过VACUUM相关手段缓解。把log-level设为debug后PostgREST 会输出每个 schema cache 查询的单独耗时。其实现位于 src/library/PostgREST/SchemaCache.hs在每个查询前后通过set_config写入clock_timestamp()计时事务结束时用extractTimings一次性提取 7 个查询各自的毫秒耗时。Schema Cache 为什么会过期何时需要重载Schema Cache 是数据库结构的内存快照。当你在数据库里执行 DDL建表、加列、改外键、建视图、创建函数等之后这份快照就与实际结构不一致了——例如新加了一个表API 上却看不到它新增了外键嵌入查询却报找不到关系。因此任何结构变更后都需要重载 Schema Cache。重载的三种途径Unix 信号手动触发适合单机/脚本运维PostgreSQL 通知NOTIFY从数据库内部或外部进程触发适合云托管容器、Windows 等无法发送信号的场景事件触发器Event Trigger自动刷新DDL 一旦提交自动通知做到无感同步。几点注意引自 docs/references/schema_cache.rst如果重载失败例如statement_timeout或连接池超时PostgREST 不会崩溃而是以尽力而为best effort的方式继续服务已有缓存下的请求若开启了 db-config数据库内配置一次 Schema Cache 重载会连带重载配置二者共享同一条加载链路。从 src/library/PostgREST/AppState/Reload.hs 的retryingSchemaCacheLoad可见加载流程会依次查询 PostgreSQL 版本、读取数据库内配置readInDbConfig、再查询 Schema Cache。手动重载使用 Unix 信号 SIGUSR1在不重启服务进程的前提下向 PostgREST 进程发送SIGUSR1即可触发一次 Schema Cache 重载killall -SIGUSR1 postgrest使用 Docker 时docker kill -s SIGUSR1 container # 或使用 docker-compose docker-compose kill -s SIGUSR1 service其中container/service分别替换为实际的容器名或 compose 服务名。从数据库内部重载NOTIFY pgrst 通知PostgREST 启动时会对 PostgreSQL 执行LISTEN监听一个通知频道默认名为pgrst可通过 db-channel 配置、用 db-channel-enabled 开关对应源码 src/library/PostgREST/Config.hs。在任意数据库会话中执行NOTIFY pgrst, reload schema;通知消息与动作的对应关系详见 docs/references/listener.rstNOTIFY 消息触发动作NOTIFY pgrst, reload schema;重载 Schema CacheNOTIFY pgrst, reload config;重载配置NOTIFY pgrst;空消息同时重载两者消息分发逻辑在 src/library/PostgREST/AppState/Reload.hs 的handleNotification中实现空消息与reload schema走缓存重载reload config走配置重载其他消息一律忽略。该方式特别适合无法发送 Unix 信号的场景如云托管容器、Windows 系统。注意LISTEN/NOTIFY在 PostgreSQL 只读副本read replica上不可用——在副本上执行LISTEN pgrst会得到ERROR: cannot execute LISTEN during recovery。解决思路是让LISTEN会话连主库、业务连接池仍用副本通过 libpq 多主机连接串 target_session_attrs实现PostgREST 会对LISTEN会话强制target_session_attrsread-write且read-only需要 libpq 14例如db-uri postgres://read_replica.host,primary.host/mydb?target_session_attrsread-only监听器的自动恢复如果LISTEN连接意外断开监听器会无限重试采用指数退避exponential backoff最大退避间隔 32 秒每次重试都会记录日志见 docs/references/listener.rst。对应实现是 src/library/PostgREST/AppState/Reload.hs 的retryingListennextDelay从 1 秒开始逐次翻倍直到 32 秒封顶。可通过 db-pool-automatic-recovery默认true关闭自动恢复关闭后连接丢失将直接终止进程。恢复连接后监听器会重新加载 Schema Cache 与配置确保不丢失断连期间的结构变更。防抖机制突发通知的合并处理当短时间内产生多个NOTIFY pgrst事件时PostgREST 不会为每条通知都触发一次重载而是采用**防抖debouncing**策略。分两种情况同一事务内多次NOTIFYPostgreSQL 自身会对同一事务内的相同NOTIFY事件去重——事务提交前即使执行多条NOTIFY pgrst提交后也只会投递一条通知给 PostgREST。跨事务的短时间突发通知PostgREST 将事件放入一个100 毫秒的时间窗口内合并窗口内第一条通知到达时立即执行一次重载突发结束后再执行一次一个窗口内最多执行两次。这一机制对应 src/library/PostgREST/Debounce.hs 的makeDebouncer内部常驻一个 worker 线程trigger通过向MVar写入标志唤醒 worker 执行动作由于MVar只能容纳一个标志突发期间多次触发会被合并为一次tryPutMVar在已有标志时直接丢弃。该防抖器作为debouncedSCacheLoader字段存入AppState见 src/library/PostgREST/AppState/Types.hs所有通知触发的重载都经由此路径。自动重载事件触发器 NOTIFY 的完整方案使用事件触发器Event Trigger可以让 Schema Cache 在每次 DDL 提交后自动刷新做到忘记缓存存在。基础版监控所有 ddl_command_end-- 创建事件触发器函数 CREATE OR REPLACE FUNCTION pgrst_watch() RETURNS event_trigger LANGUAGE plpgsql AS $$ BEGIN NOTIFY pgrst, reload schema; END; $$; -- 该事件触发器会在每次 ddl_command_end 事件后触发 CREATE EVENT TRIGGER pgrst_watch ON ddl_command_end EXECUTE PROCEDURE pgrst_watch();此后只要pgrst_watch被触发PostgREST 就会自动重载 Schema Cache。禁用自动刷新只需删除触发器DROP EVENT TRIGGER pgrst_watch精细化版只监听与 Schema Cache 相关的事件基础版会对所有DDL 事件包括函数内部创建临时表等无关操作触发通知造成无谓重载。更优的做法是通过pg_event_trigger_ddl_commands()与pg_event_trigger_dropped_objects()过滤出真正影响 Schema Cache 的对象类型完整代码引自 docs/references/schema_cache.rst-- 监控 CREATE 和 ALTER CREATE OR REPLACE FUNCTION pgrst_ddl_watch() RETURNS event_trigger AS $$ DECLARE cmd record; BEGIN FOR cmd IN SELECT * FROM pg_event_trigger_ddl_commands() LOOP IF cmd.command_tag IN ( CREATE SCHEMA, ALTER SCHEMA , CREATE TABLE, CREATE TABLE AS, SELECT INTO, ALTER TABLE , CREATE FOREIGN TABLE, ALTER FOREIGN TABLE , CREATE VIEW, ALTER VIEW , CREATE MATERIALIZED VIEW, ALTER MATERIALIZED VIEW , CREATE FUNCTION, ALTER FUNCTION , CREATE TRIGGER , CREATE TYPE, ALTER TYPE , CREATE RULE , COMMENT ) -- 忽略 pg_temp 临时 schema 中的对象避免函数内建临时表触发重载 AND cmd.schema_name is distinct from pg_temp THEN NOTIFY pgrst, reload schema; END IF; END LOOP; END; $$ LANGUAGE plpgsql; -- 监控 DROP CREATE OR REPLACE FUNCTION pgrst_drop_watch() RETURNS event_trigger AS $$ DECLARE obj record; BEGIN FOR obj IN SELECT * FROM pg_event_trigger_dropped_objects() LOOP IF obj.object_type IN ( schema , table , foreign table , view , materialized view , function , trigger , type , rule ) AND obj.is_temporary IS false -- 排除 pg_temp 临时对象 THEN NOTIFY pgrst, reload schema; END IF; END LOOP; END; $$ LANGUAGE plpgsql; CREATE EVENT TRIGGER pgrst_ddl_watch ON ddl_command_end EXECUTE PROCEDURE pgrst_ddl_watch(); CREATE EVENT TRIGGER pgrst_drop_watch ON sql_drop EXECUTE PROCEDURE pgrst_drop_watch();要点说明ddl_command_end事件在 DDL 命令完成后触发覆盖CREATE/ALTER类操作sql_drop事件专门覆盖DROP类操作精细版过滤掉pg_temp中的对象——函数执行时创建临时表是常见行为不应触发全局缓存重载COMMENT也被纳入监控因为对象注释会出现在 Schema Cache 的列描述/表描述中影响 OpenAPI 输出与Prefer相关行为。重载链路与失败恢复底层如何工作从源码层面看一次成功的重载会经历完整链路src/library/PostgREST/AppState/Reload.hs查询 PostgreSQL 版本并校验是否受支持同时初始化连接池若启用 db-config读取数据库内配置在单事务内执行 7 个 schema cache 查询querySchemaCache将新快照写入stateSchemaCache并把缓存状态标记为pending恢复中再置为loaded冲刷连接池清除连接上缓存的旧目录信息通过观察者Observation机制记录SchemaCacheQueriedObs查询耗时与SchemaCacheLoadedObs加载耗时 统计摘要最终进入日志与指标见 src/library/PostgREST/Observation.hs。值得注意的细节启动时 PostgREST 会等待首次Schema Cache 加载完成或进入重试状态后才开始监听 API 端口——SchemaCacheStatus的注释明确指出空值表示启动初始加载见 src/library/PostgREST/AppState/Types.hs加载失败时进入重试循环retryPolicy使用capDelay 32s $ exponentialBackoff 1s即 1 秒起步、翻倍递增、32 秒封顶的指数退避重载期间的请求在pending状态下继续以旧缓存服务属于文档所述的best effort语义。观察与验证日志、指标与测试日志info级别下stderr 会输出Schema cache queried in ... milliseconds、Schema cache loaded ... Relations, ...以及监听器消息如Listening for database notifications on the pgrst channel、Received a ... message on the pgrst channel示例见 docs/references/observability.rst指标Schema Cache 查询/加载耗时也通过 Metrics 暴露可在 Prometheus 端点观测调试log-level debug时可看到 7 个查询各自的耗时明细测试佐证仓库中 test/spec/Feature/ConcurrentSpec.hs 等并发/重载相关测试覆盖了 Schema Cache 在请求并发下的加载与重载行为test/io/test_reloading.py则从 IO 层验证了配置与 Schema Cache 的重载流程。想深入了解缓存数据结构与查询细节可直接阅读 src/library/PostgREST/SchemaCache.hs 的注释与 SQL。小结选择适合你的重载策略场景推荐方式单机/脚本运维想立即生效killall -SIGUSR1 postgrestDocker / docker-composedocker kill -s SIGUSR1 container云托管容器、Windows、无法发信号的环境NOTIFY pgrst, reload schema;结构变更频繁、希望完全自动事件触发器 NOTIFY建议使用精细版过滤pg_temp多租户/大量 DDL 突发依赖内置 100ms 防抖窗口自动合并理解 Schema Cache 的构成与刷新机制是安全运维 PostgREST 的关键一环它决定了 API 暴露的结构是否与数据库一致也决定了你在执行 DDL 之后何时才能看到新表、新列、新关系。借助信号、NOTIFY 或事件触发器你可以把这层缓存完全纳入自动化体系。【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考