PostgreSQL 可以扩展为在单独的进程中运行用户提供的代码。此类进程由 postgres
启动、停止和监控,这使得它们的生命周期与服务器的状态紧密相关。这些进程附加到 PostgreSQL 的共享内存区域,并可以选择内部连接到数据库;它们还可以像常规的客户端连接服务器进程一样,连续运行多个事务。此外,通过链接到 libpq,它们可以连接到服务器并表现得像一个常规的客户端应用程序。
使用后台工作进程存在相当大的健壮性和安全风险,因为它们是用 C
语言编写的,可以无限制地访问数据。希望启用包含后台工作进程的模块的管理员应格外谨慎。只有经过仔细审计的模块才能允许运行后台工作进程。
后台工作进程可以在 PostgreSQL 启动时通过在 shared_preload_libraries
中包含模块名称来初始化。希望运行后台工作进程的模块可以通过从其 _PG_init()
函数调用 RegisterBackgroundWorker(
来注册它。后台工作进程也可以在系统启动并运行后通过调用 BackgroundWorker
*worker
)RegisterDynamicBackgroundWorker(
来启动。与只能从 postmaster 进程内部调用的 BackgroundWorker
*worker
, BackgroundWorkerHandle
**handle
)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_name
和 bgw_type
是用于日志消息、进程列表和类似上下文的字符串。bgw_type
对于所有相同类型的后台工作进程都应相同,以便例如能够在进程列表中对这些工作进程进行分组。bgw_name
另一方面可以包含有关特定进程的其他信息。(通常,bgw_name
的字符串将以某种方式包含类型,但这并不是严格要求的。)
bgw_flags
是一个按位或的位掩码,指示模块所需的功能。可能的值为
bgw_start_time
是 postgres
应该启动进程的服务器状态;它可以是 BgWorkerStart_PostmasterStart
(一旦 postgres
本身完成自己的初始化就启动;请求此状态的进程不符合数据库连接的条件)、BgWorkerStart_ConsistentState
(一旦在热备用中达到一致状态就启动,允许进程连接到数据库并运行只读查询)和 BgWorkerStart_RecoveryFinished
(一旦系统进入正常的读写状态就启动)。请注意,最后两个值在不是热备用的服务器中是等效的。请注意,此设置仅指示何时启动进程;当达到不同的状态时,它们不会停止。
bgw_restart_time
是 postgres
在进程崩溃后应等待多长时间(以秒为单位)才能重新启动该进程。它可以是任何正值,或者 BGW_NEVER_RESTART
,表示在发生崩溃时不重新启动进程。
bgw_library_name
是一个库的名称,在该库中应该搜索后台工作进程的初始入口点。命名库将由工作进程动态加载,并且 bgw_function_name
将用于识别要调用的函数。如果调用核心代码中的函数,则必须将其设置为 "postgres"
。
bgw_function_name
是用作新后台工作进程的初始入口点的函数的名称。如果此函数位于动态加载的库中,则必须将其标记为 PGDLLEXPORT
(而不是 static
)。
bgw_main_arg
是后台工作进程主函数的 Datum
参数。此主函数应接受一个 Datum
类型的参数并返回 void
。bgw_main_arg
将作为参数传递。此外,全局变量 MyBgworkerEntry
指向注册时传递的 BackgroundWorker
结构体的副本;工作进程可能会发现检查此结构体很有用。
在 Windows(以及其他任何定义了 EXEC_BACKEND
的地方)或在动态后台工作进程中,通过引用传递 Datum
是不安全的,只能按值传递。如果需要参数,最安全的方法是传递一个 int32 或其他小值,并将其用作分配在共享内存中的数组的索引。如果传递了像 cstring
或 text
这样的值,则指针在新后台工作进程中将无效。
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 或 dboid
为 InvalidOid
,则会话未连接到任何特定数据库,但可以访问共享目录。如果 username
为 NULL 或 useroid
为 InvalidOid
,则进程将作为在 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(
函数来实现。此函数将阻塞,直到 postmaster 尝试启动后台工作进程,或直到 postmaster 退出。如果后台工作进程正在运行,则返回值将为 BackgroundWorkerHandle *handle
, pid_t *
)BGWH_STARTED
,并且 PID 将写入提供的地址。否则,返回值将为 BGWH_STOPPED
或 BGWH_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 限制。
如果您在文档中发现任何不正确的内容,与您对特定功能的体验不符,或者需要进一步澄清,请使用 此表单 报告文档问题。