Home • Explore • Blog • CI
☰



postgresql
4th chunk of `doc/src/sgml/bgworker.sgml`
130594c535312c83cbaf4e77c52930233a3cf3b9816c6c680000000100000bfc
 allows the process to run transactions and queries using the
   <literal>SPI</literal> interface.  If <varname>dbname</varname> is NULL or
   <varname>dboid</varname> is <literal>InvalidOid</literal>, the session is not connected
   to any particular database, but shared catalogs can be accessed.
   If <varname>username</varname> is NULL or <varname>useroid</varname> is
   <literal>InvalidOid</literal>, the process will run as the superuser created
   during <command>initdb</command>. If <literal>BGWORKER_BYPASS_ALLOWCONN</literal>
   is specified as <varname>flags</varname> it is possible to bypass the restriction
   to connect to databases not allowing user connections.
   If <literal>BGWORKER_BYPASS_ROLELOGINCHECK</literal> is specified as
   <varname>flags</varname> it is possible to bypass the login check for the
   role used to connect to databases.
   A background worker can only call one of these two functions, and only
   once.  It is not possible to switch databases.
  </para>

  <para>
   Signals are initially blocked when control reaches the
   background worker's main function, and must be unblocked by it; this is to
   allow the process to customize its signal handlers, if necessary.
   Signals can be unblocked in the new process by calling
   <function>BackgroundWorkerUnblockSignals</function> and blocked by calling
   <function>BackgroundWorkerBlockSignals</function>.
  </para>

  <para>
   If <structfield>bgw_restart_time</structfield> for a background worker is
   configured as <literal>BGW_NEVER_RESTART</literal>, or if it exits with an exit
   code of 0 or is terminated by <function>TerminateBackgroundWorker</function>,
   it will be automatically unregistered by the postmaster on exit.
   Otherwise, it will be restarted after the time period configured via
   <structfield>bgw_restart_time</structfield>, or immediately if the postmaster
   reinitializes the cluster due to a backend failure.  Backends which need
   to suspend execution only temporarily should use an interruptible sleep
   rather than exiting; this can be achieved by calling
   <function>WaitLatch()</function>. Make sure the
   <literal>WL_POSTMASTER_DEATH</literal> flag is set when calling that function, and
   verify the return code for a prompt exit in the emergency case that
   <command>postgres</command> itself has terminated.
  </para>

  <para>
   When a background worker is registered using the
   <function>RegisterDynamicBackgroundWorker</function> function, it is
   possible for the backend performing the registration to obtain information
   regarding the status of the worker.  Backends wishing to do this should
   pass the address of a <type>BackgroundWorkerHandle *</type> as the second
   argument to <function>RegisterDynamicBackgroundWorker</function>.  If the
   worker is successfully registered, this pointer will be initialized with an
   opaque handle that can subsequently be passed to
   <function>GetBackgroundWorkerPid(<parameter>BackgroundWorkerHandle *</parameter>, <parameter>pid_t *</parameter>)</function>
Title: Background Worker SPI Access, Signal Handling, Restart Behavior, and Registration Status
Summary
Background workers can run transactions and queries using the SPI interface. If dbname/dboid or username/useroid are null/invalid, the session uses shared catalogs or runs as the superuser. Flags like BGWORKER_BYPASS_ALLOWCONN and BGWORKER_BYPASS_ROLELOGINCHECK bypass connection restrictions and role login checks. Workers can only call one initialization function once and cannot switch databases. Signals are initially blocked and can be managed with BackgroundWorkerUnblockSignals and BackgroundWorkerBlockSignals. Workers with BGW_NEVER_RESTART or exit code 0 are unregistered, otherwise, they restart after bgw_restart_time. Use interruptible sleep via WaitLatch() for temporary suspension, checking for WL_POSTMASTER_DEATH. RegisterDynamicBackgroundWorker allows obtaining a BackgroundWorkerHandle to track worker status.