begriffs open source - ai-pg/blob - full-docs/txt/bgworker.txt

   1
   2 Chapter 46. Background Worker Processes
   3
   4    PostgreSQL can be extended to run user-supplied code in separate
   5    processes. Such processes are started, stopped and monitored by
   6    postgres, which permits them to have a lifetime closely linked to the
   7    server's status. These processes are attached to PostgreSQL's shared
   8    memory area and have the option to connect to databases internally;
   9    they can also run multiple transactions serially, just like a regular
  10    client-connected server process. Also, by linking to libpq they can
  11    connect to the server and behave like a regular client application.
  12
  13 Warning
  14
  15    There are considerable robustness and security risks in using
  16    background worker processes because, being written in the C language,
  17    they have unrestricted access to data. Administrators wishing to enable
  18    modules that include background worker processes should exercise
  19    extreme caution. Only carefully audited modules should be permitted to
  20    run background worker processes.
  21
  22    Background workers can be initialized at the time that PostgreSQL is
  23    started by including the module name in shared_preload_libraries. A
  24    module wishing to run a background worker can register it by calling
  25    RegisterBackgroundWorker(BackgroundWorker *worker) from its _PG_init()
  26    function. Background workers can also be started after the system is up
  27    and running by calling RegisterDynamicBackgroundWorker(BackgroundWorker
  28    *worker, BackgroundWorkerHandle **handle). Unlike
  29    RegisterBackgroundWorker, which can only be called from within the
  30    postmaster process, RegisterDynamicBackgroundWorker must be called from
  31    a regular backend or another background worker.
  32
  33    The structure BackgroundWorker is defined thus:
  34 typedef void (*bgworker_main_type)(Datum main_arg);
  35 typedef struct BackgroundWorker
  36 {
  37     char        bgw_name[BGW_MAXLEN];
  38     char        bgw_type[BGW_MAXLEN];
  39     int         bgw_flags;
  40     BgWorkerStartTime bgw_start_time;
  41     int         bgw_restart_time;       /* in seconds, or BGW_NEVER_RESTART */
  42     char        bgw_library_name[MAXPGPATH];
  43     char        bgw_function_name[BGW_MAXLEN];
  44     Datum       bgw_main_arg;
  45     char        bgw_extra[BGW_EXTRALEN];
  46     pid_t       bgw_notify_pid;
  47 } BackgroundWorker;
  48
  49    bgw_name and bgw_type are strings to be used in log messages, process
  50    listings and similar contexts. bgw_type should be the same for all
  51    background workers of the same type, so that it is possible to group
  52    such workers in a process listing, for example. bgw_name on the other
  53    hand can contain additional information about the specific process.
  54    (Typically, the string for bgw_name will contain the type somehow, but
  55    that is not strictly required.)
  56
  57    bgw_flags is a bitwise-or'd bit mask indicating the capabilities that
  58    the module wants. Possible values are:
  59
  60    BGWORKER_SHMEM_ACCESS
  61           Requests shared memory access. This flag is required.
  62
  63    BGWORKER_BACKEND_DATABASE_CONNECTION
  64           Requests the ability to establish a database connection through
  65           which it can later run transactions and queries. A background
  66           worker using BGWORKER_BACKEND_DATABASE_CONNECTION to connect to
  67           a database must also attach shared memory using
  68           BGWORKER_SHMEM_ACCESS, or worker start-up will fail.
  69
  70    bgw_start_time is the server state during which postgres should start
  71    the process; it can be one of BgWorkerStart_PostmasterStart (start as
  72    soon as postgres itself has finished its own initialization; processes
  73    requesting this are not eligible for database connections),
  74    BgWorkerStart_ConsistentState (start as soon as a consistent state has
  75    been reached in a hot standby, allowing processes to connect to
  76    databases and run read-only queries), and
  77    BgWorkerStart_RecoveryFinished (start as soon as the system has entered
  78    normal read-write state). Note the last two values are equivalent in a
  79    server that's not a hot standby. Note that this setting only indicates
  80    when the processes are to be started; they do not stop when a different
  81    state is reached.
  82
  83    bgw_restart_time is the interval, in seconds, that postgres should wait
  84    before restarting the process in the event that it crashes. It can be
  85    any positive value, or BGW_NEVER_RESTART, indicating not to restart the
  86    process in case of a crash.
  87
  88    bgw_library_name is the name of a library in which the initial entry
  89    point for the background worker should be sought. The named library
  90    will be dynamically loaded by the worker process and bgw_function_name
  91    will be used to identify the function to be called. If calling a
  92    function in the core code, this must be set to "postgres".
  93
  94    bgw_function_name is the name of the function to use as the initial
  95    entry point for the new background worker. If this function is in a
  96    dynamically loaded library, it must be marked PGDLLEXPORT (and not
  97    static).
  98
  99    bgw_main_arg is the Datum argument to the background worker main
 100    function. This main function should take a single argument of type
 101    Datum and return void. bgw_main_arg will be passed as the argument. In
 102    addition, the global variable MyBgworkerEntry points to a copy of the
 103    BackgroundWorker structure passed at registration time; the worker may
 104    find it helpful to examine this structure.
 105
 106    On Windows (and anywhere else where EXEC_BACKEND is defined) or in
 107    dynamic background workers it is not safe to pass a Datum by reference,
 108    only by value. If an argument is required, it is safest to pass an
 109    int32 or other small value and use that as an index into an array
 110    allocated in shared memory. If a value like a cstring or text is passed
 111    then the pointer won't be valid from the new background worker process.
 112
 113    bgw_extra can contain extra data to be passed to the background worker.
 114    Unlike bgw_main_arg, this data is not passed as an argument to the
 115    worker's main function, but it can be accessed via MyBgworkerEntry, as
 116    discussed above.
 117
 118    bgw_notify_pid is the PID of a PostgreSQL backend process to which the
 119    postmaster should send SIGUSR1 when the process is started or exits. It
 120    should be 0 for workers registered at postmaster startup time, or when
 121    the backend registering the worker does not wish to wait for the worker
 122    to start up. Otherwise, it should be initialized to MyProcPid.
 123
 124    Once running, the process can connect to a database by calling
 125    BackgroundWorkerInitializeConnection(char *dbname, char *username,
 126    uint32 flags) or BackgroundWorkerInitializeConnectionByOid(Oid dboid,
 127    Oid useroid, uint32 flags). This allows the process to run transactions
 128    and queries using the SPI interface. If dbname is NULL or dboid is
 129    InvalidOid, the session is not connected to any particular database,
 130    but shared catalogs can be accessed. If username is NULL or useroid is
 131    InvalidOid, the process will run as the superuser created during
 132    initdb. If BGWORKER_BYPASS_ALLOWCONN is specified as flags it is
 133    possible to bypass the restriction to connect to databases not allowing
 134    user connections. If BGWORKER_BYPASS_ROLELOGINCHECK is specified as
 135    flags it is possible to bypass the login check for the role used to
 136    connect to databases. A background worker can only call one of these
 137    two functions, and only once. It is not possible to switch databases.
 138
 139    Signals are initially blocked when control reaches the background
 140    worker's main function, and must be unblocked by it; this is to allow
 141    the process to customize its signal handlers, if necessary. Signals can
 142    be unblocked in the new process by calling
 143    BackgroundWorkerUnblockSignals and blocked by calling
 144    BackgroundWorkerBlockSignals.
 145
 146    If bgw_restart_time for a background worker is configured as
 147    BGW_NEVER_RESTART, or if it exits with an exit code of 0 or is
 148    terminated by TerminateBackgroundWorker, it will be automatically
 149    unregistered by the postmaster on exit. Otherwise, it will be restarted
 150    after the time period configured via bgw_restart_time, or immediately
 151    if the postmaster reinitializes the cluster due to a backend failure.
 152    Backends which need to suspend execution only temporarily should use an
 153    interruptible sleep rather than exiting; this can be achieved by
 154    calling WaitLatch(). Make sure the WL_POSTMASTER_DEATH flag is set when
 155    calling that function, and verify the return code for a prompt exit in
 156    the emergency case that postgres itself has terminated.
 157
 158    When a background worker is registered using the
 159    RegisterDynamicBackgroundWorker function, it is possible for the
 160    backend performing the registration to obtain information regarding the
 161    status of the worker. Backends wishing to do this should pass the
 162    address of a BackgroundWorkerHandle * as the second argument to
 163    RegisterDynamicBackgroundWorker. If the worker is successfully
 164    registered, this pointer will be initialized with an opaque handle that
 165    can subsequently be passed to
 166    GetBackgroundWorkerPid(BackgroundWorkerHandle *, pid_t *) or
 167    TerminateBackgroundWorker(BackgroundWorkerHandle *).
 168    GetBackgroundWorkerPid can be used to poll the status of the worker: a
 169    return value of BGWH_NOT_YET_STARTED indicates that the worker has not
 170    yet been started by the postmaster; BGWH_STOPPED indicates that it has
 171    been started but is no longer running; and BGWH_STARTED indicates that
 172    it is currently running. In this last case, the PID will also be
 173    returned via the second argument. TerminateBackgroundWorker causes the
 174    postmaster to send SIGTERM to the worker if it is running, and to
 175    unregister it as soon as it is not.
 176
 177    In some cases, a process which registers a background worker may wish
 178    to wait for the worker to start up. This can be accomplished by
 179    initializing bgw_notify_pid to MyProcPid and then passing the
 180    BackgroundWorkerHandle * obtained at registration time to
 181    WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *)
 182    function. This function will block until the postmaster has attempted
 183    to start the background worker, or until the postmaster dies. If the
 184    background worker is running, the return value will be BGWH_STARTED,
 185    and the PID will be written to the provided address. Otherwise, the
 186    return value will be BGWH_STOPPED or BGWH_POSTMASTER_DIED.
 187
 188    A process can also wait for a background worker to shut down, by using
 189    the WaitForBackgroundWorkerShutdown(BackgroundWorkerHandle *handle)
 190    function and passing the BackgroundWorkerHandle * obtained at
 191    registration. This function will block until the background worker
 192    exits, or postmaster dies. When the background worker exits, the return
 193    value is BGWH_STOPPED, if postmaster dies it will return
 194    BGWH_POSTMASTER_DIED.
 195
 196    Background workers can send asynchronous notification messages, either
 197    by using the NOTIFY command via SPI, or directly via Async_Notify().
 198    Such notifications will be sent at transaction commit. Background
 199    workers should not register to receive asynchronous notifications with
 200    the LISTEN command, as there is no infrastructure for a worker to
 201    consume such notifications.
 202
 203    The src/test/modules/worker_spi module contains a working example,
 204    which demonstrates some useful techniques.
 205
 206    The maximum number of registered background workers is limited by
 207    max_worker_processes.