2024 年 9 月 26 日:PostgreSQL 17 发布!
支持的版本:当前 (17) / 16 / 15 / 14 / 13 / 12
开发版本:devel
不支持的版本:11 / 10 / 9.6 / 9.5 / 9.4 / 9.3

第 46 章 后台工作进程

PostgreSQL 可以扩展为在单独的进程中运行用户提供的代码。此类进程由 postgres 启动、停止和监控,这使得它们的生命周期与服务器的状态紧密相关。这些进程附加到 PostgreSQL 的共享内存区域,并可以选择内部连接到数据库;它们还可以像常规的客户端连接服务器进程一样,连续运行多个事务。此外,通过链接到 libpq,它们可以连接到服务器并表现得像一个常规的客户端应用程序。

警告

使用后台工作进程存在相当大的健壮性和安全风险,因为它们是用 C 语言编写的,可以无限制地访问数据。希望启用包含后台工作进程的模块的管理员应格外谨慎。只有经过仔细审计的模块才能允许运行后台工作进程。

后台工作进程可以在 PostgreSQL 启动时通过在 shared_preload_libraries 中包含模块名称来初始化。希望运行后台工作进程的模块可以通过从其 _PG_init() 函数调用 RegisterBackgroundWorker(BackgroundWorker *worker) 来注册它。后台工作进程也可以在系统启动并运行后通过调用 RegisterDynamicBackgroundWorker(BackgroundWorker *worker, BackgroundWorkerHandle **handle) 来启动。与只能从 postmaster 进程内部调用的 RegisterBackgroundWorker 不同,RegisterDynamicBackgroundWorker 必须从常规后端或其他后台工作进程中调用。

结构体 BackgroundWorker 定义如下

typedef void (*bgworker_main_type)(Datum main_arg);
typedef struct BackgroundWorker
{
    char        bgw_name[BGW_MAXLEN];
    char        bgw_type[BGW_MAXLEN];
    int         bgw_flags;
    BgWorkerStartTime bgw_start_time;
    int         bgw_restart_time;       /* in seconds, or BGW_NEVER_RESTART */
    char        bgw_library_name[MAXPGPATH];
    char        bgw_function_name[BGW_MAXLEN];
    Datum       bgw_main_arg;
    char        bgw_extra[BGW_EXTRALEN];
    pid_t       bgw_notify_pid;
} BackgroundWorker;

bgw_namebgw_type 是用于日志消息、进程列表和类似上下文的字符串。bgw_type 对于所有相同类型的后台工作进程都应相同,以便例如能够在进程列表中对这些工作进程进行分组。bgw_name 另一方面可以包含有关特定进程的其他信息。(通常,bgw_name 的字符串将以某种方式包含类型,但这并不是严格要求的。)

bgw_flags 是一个按位或的位掩码,指示模块所需的功能。可能的值为

BGWORKER_SHMEM_ACCESS

请求共享内存访问。此标志是必需的。

BGWORKER_BACKEND_DATABASE_CONNECTION

请求建立数据库连接的能力,通过该连接它以后可以运行事务和查询。使用 BGWORKER_BACKEND_DATABASE_CONNECTION 连接到数据库的后台工作进程还必须使用 BGWORKER_SHMEM_ACCESS 附加共享内存,否则工作进程启动将失败。

bgw_start_timepostgres 应该启动进程的服务器状态;它可以是 BgWorkerStart_PostmasterStart(一旦 postgres 本身完成自己的初始化就启动;请求此状态的进程不符合数据库连接的条件)、BgWorkerStart_ConsistentState(一旦在热备用中达到一致状态就启动,允许进程连接到数据库并运行只读查询)和 BgWorkerStart_RecoveryFinished(一旦系统进入正常的读写状态就启动)。请注意,最后两个值在不是热备用的服务器中是等效的。请注意,此设置仅指示何时启动进程;当达到不同的状态时,它们不会停止。

bgw_restart_timepostgres 在进程崩溃后应等待多长时间(以秒为单位)才能重新启动该进程。它可以是任何正值,或者 BGW_NEVER_RESTART,表示在发生崩溃时不重新启动进程。

bgw_library_name 是一个库的名称,在该库中应该搜索后台工作进程的初始入口点。命名库将由工作进程动态加载,并且 bgw_function_name 将用于识别要调用的函数。如果调用核心代码中的函数,则必须将其设置为 "postgres"

bgw_function_name 是用作新后台工作进程的初始入口点的函数的名称。如果此函数位于动态加载的库中,则必须将其标记为 PGDLLEXPORT(而不是 static)。

bgw_main_arg 是后台工作进程主函数的 Datum 参数。此主函数应接受一个 Datum 类型的参数并返回 voidbgw_main_arg 将作为参数传递。此外,全局变量 MyBgworkerEntry 指向注册时传递的 BackgroundWorker 结构体的副本;工作进程可能会发现检查此结构体很有用。

在 Windows(以及其他任何定义了 EXEC_BACKEND 的地方)或在动态后台工作进程中,通过引用传递 Datum 是不安全的,只能按值传递。如果需要参数,最安全的方法是传递一个 int32 或其他小值,并将其用作分配在共享内存中的数组的索引。如果传递了像 cstringtext 这样的值,则指针在新后台工作进程中将无效。

bgw_extra 可以包含要传递给后台工作进程的额外数据。与 bgw_main_arg 不同,此数据不会作为参数传递给工作进程的主函数,但可以通过前面讨论的 MyBgworkerEntry 进行访问。

bgw_notify_pid 是 PostgreSQL 后端进程的 PID,postmaster 应在进程启动或退出时向其发送 SIGUSR1。对于在 postmaster 启动时注册的工作进程,或者当注册工作进程的后端不想等待工作进程启动时,它应为 0。否则,它应初始化为 MyProcPid

运行后,进程可以通过调用 BackgroundWorkerInitializeConnection(char *dbname, char *username, uint32 flags)BackgroundWorkerInitializeConnectionByOid(Oid dboid, Oid useroid, uint32 flags) 连接到数据库。这允许进程使用 SPI 接口运行事务和查询。如果 dbname 为 NULL 或 dboidInvalidOid,则会话未连接到任何特定数据库,但可以访问共享目录。如果 username 为 NULL 或 useroidInvalidOid,则进程将作为在 initdb 期间创建的超级用户运行。如果 BGWORKER_BYPASS_ALLOWCONN 指定为 flags,则可以绕过连接到不允许用户连接的数据库的限制。如果 BGWORKER_BYPASS_ROLELOGINCHECK 指定为 flags,则可以绕过用于连接到数据库的角色的登录检查。后台工作进程只能调用这两个函数中的一个,并且只能调用一次。无法切换数据库。

当控制权到达后台工作进程的主函数时,信号最初会被阻塞,并且必须由它解除阻塞;这是为了允许进程根据需要自定义其信号处理程序。可以通过调用 BackgroundWorkerUnblockSignals 在新进程中解除阻塞信号,并通过调用 BackgroundWorkerBlockSignals 阻塞信号。

如果后台工作进程的 bgw_restart_time 配置为 BGW_NEVER_RESTART,或者如果它以退出代码 0 退出或被 TerminateBackgroundWorker 终止,则它将在退出时由 postmaster 自动取消注册。否则,它将在通过 bgw_restart_time 配置的时间段后重新启动,或者如果 postmaster 由于后端故障而重新初始化集群,则立即重新启动。需要暂时挂起执行的后端应使用可中断的睡眠而不是退出;这可以通过调用 WaitLatch() 来实现。确保在调用该函数时设置了 WL_POSTMASTER_DEATH 标志,并在紧急情况下验证返回代码,以防 postgres 本身已终止。

当使用 RegisterDynamicBackgroundWorker 函数注册后台工作进程时,执行注册的后端可以获取有关工作进程状态的信息。希望执行此操作的后端应将 BackgroundWorkerHandle * 的地址作为第二个参数传递给 RegisterDynamicBackgroundWorker。如果工作进程成功注册,则此指针将初始化为一个不透明句柄,该句柄随后可以传递给 GetBackgroundWorkerPid(BackgroundWorkerHandle *, pid_t *)TerminateBackgroundWorker(BackgroundWorkerHandle *)。可以使用 GetBackgroundWorkerPid 轮询工作进程的状态:返回值 BGWH_NOT_YET_STARTED 表示工作进程尚未由 postmaster 启动;BGWH_STOPPED 表示它已启动但不再运行;BGWH_STARTED 表示它当前正在运行。在最后一种情况下,PID 也将通过第二个参数返回。TerminateBackgroundWorker 会导致 postmaster 向工作进程发送 SIGTERM(如果它正在运行),并在它停止运行后立即取消注册。

在某些情况下,注册后台工作进程的进程可能希望等待工作进程启动。这可以通过将 bgw_notify_pid 初始化为 MyProcPid,然后将注册时获得的 BackgroundWorkerHandle * 传递给 WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *) 函数来实现。此函数将阻塞,直到 postmaster 尝试启动后台工作进程,或直到 postmaster 退出。如果后台工作进程正在运行,则返回值将为 BGWH_STARTED,并且 PID 将写入提供的地址。否则,返回值将为 BGWH_STOPPEDBGWH_POSTMASTER_DIED

进程还可以通过使用 WaitForBackgroundWorkerShutdown(BackgroundWorkerHandle *handle) 函数并传递注册时获得的 BackgroundWorkerHandle * 来等待后台工作进程关闭。此函数将阻塞,直到后台工作进程退出或 postmaster 退出。当后台工作进程退出时,返回值为 BGWH_STOPPED,如果 postmaster 退出,则返回 BGWH_POSTMASTER_DIED

后台工作进程可以通过使用 NOTIFY 命令(通过SPI),或直接通过 Async_Notify() 发送异步通知消息。此类通知将在事务提交时发送。后台工作进程不应使用 LISTEN 命令注册接收异步通知,因为没有基础设施供工作进程使用此类通知。

src/test/modules/worker_spi 模块包含一个工作示例,演示了一些有用的技术。

已注册的后台工作进程的最大数量受 max_worker_processes 限制。

提交更正

如果您在文档中发现任何不正确的内容,与您对特定功能的体验不符,或者需要进一步澄清,请使用 此表单 报告文档问题。