src/bin/pg_basebackup/walmethods.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * walmethods.h
   4  *
   5  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
   6  *
   7  * IDENTIFICATION
   8  *                src/bin/pg_basebackup/walmethods.h
   9  *-------------------------------------------------------------------------
  10  */
  11
  12 #include "common/compression.h"
  13
  14 struct WalWriteMethod;
  15 typedef struct WalWriteMethod WalWriteMethod;
  16
  17 typedef struct
  18 {
  19         WalWriteMethod *wwmethod;
  20         pgoff_t         currpos;
  21         char       *pathname;
  22
  23         /*
  24          * MORE DATA FOLLOWS AT END OF STRUCT
  25          *
  26          * Each WalWriteMethod is expected to embed this as the first member of a
  27          * larger struct with method-specific fields following.
  28          */
  29 } Walfile;
  30
  31 typedef enum
  32 {
  33         CLOSE_NORMAL,
  34         CLOSE_UNLINK,
  35         CLOSE_NO_RENAME,
  36 } WalCloseMethod;
  37
  38 /*
  39  * Table of callbacks for a WalWriteMethod.
  40  */
  41 typedef struct WalWriteMethodOps
  42 {
  43         /*
  44          * Open a target file. Returns Walfile, or NULL if open failed. If a temp
  45          * suffix is specified, a file with that name will be opened, and then
  46          * automatically renamed in close(). If pad_to_size is specified, the file
  47          * will be padded with NUL up to that size, if supported by the Walmethod.
  48          */
  49         Walfile    *(*open_for_write) (WalWriteMethod *wwmethod, const char *pathname, const char *temp_suffix, size_t pad_to_size);
  50
  51         /*
  52          * Close an open Walfile, using one or more methods for handling automatic
  53          * unlinking etc. Returns 0 on success, other values for error.
  54          */
  55         int                     (*close) (Walfile *f, WalCloseMethod method);
  56
  57         /* Check if a file exist */
  58         bool            (*existsfile) (WalWriteMethod *wwmethod, const char *pathname);
  59
  60         /* Return the size of a file, or -1 on failure. */
  61         ssize_t         (*get_file_size) (WalWriteMethod *wwmethod, const char *pathname);
  62
  63         /*
  64          * Return the name of the current file to work on in pg_malloc()'d string,
  65          * without the base directory.  This is useful for logging.
  66          */
  67         char       *(*get_file_name) (WalWriteMethod *wwmethod, const char *pathname, const char *temp_suffix);
  68
  69         /*
  70          * Write count number of bytes to the file, and return the number of bytes
  71          * actually written or -1 for error.
  72          */
  73         ssize_t         (*write) (Walfile *f, const void *buf, size_t count);
  74
  75         /*
  76          * fsync the contents of the specified file. Returns 0 on success.
  77          */
  78         int                     (*sync) (Walfile *f);
  79
  80         /*
  81          * Clean up the Walmethod, closing any shared resources. For methods like
  82          * tar, this includes writing updated headers. Returns true if the
  83          * close/write/sync of shared resources succeeded, otherwise returns false
  84          * (but the resources are still closed).
  85          */
  86         bool            (*finish) (WalWriteMethod *wwmethod);
  87
  88         /*
  89          * Free subsidiary data associated with the WalWriteMethod, and the
  90          * WalWriteMethod itself.
  91          */
  92         void            (*free) (WalWriteMethod *wwmethod);
  93 } WalWriteMethodOps;
  94
  95 /*
  96  * A WalWriteMethod structure represents a way of writing streaming WAL as
  97  * it's received.
  98  *
  99  * All methods that have a failure return indicator will set lasterrstring
 100  * or lasterrno (the former takes precedence) so that the caller can signal
 101  * a suitable error.
 102  */
 103 struct WalWriteMethod
 104 {
 105         const WalWriteMethodOps *ops;
 106         pg_compress_algorithm compression_algorithm;
 107         int                     compression_level;
 108         bool            sync;
 109         const char *lasterrstring;      /* if set, takes precedence over lasterrno */
 110         int                     lasterrno;
 111
 112         /*
 113          * MORE DATA FOLLOWS AT END OF STRUCT
 114          *
 115          * Each WalWriteMethod is expected to embed this as the first member of a
 116          * larger struct with method-specific fields following.
 117          */
 118 };
 119
 120 /*
 121  * Available WAL methods:
 122  *      - WalDirectoryMethod - write WAL to regular files in a standard pg_wal
 123  *      - WalTarMethod       - write WAL to a tarfile corresponding to pg_wal
 124  *                                                 (only implements the methods required for pg_basebackup,
 125  *                                                 not all those required for pg_receivewal)
 126  */
 127 WalWriteMethod *CreateWalDirectoryMethod(const char *basedir,
 128                                                                                  pg_compress_algorithm compression_algorithm,
 129                                                                                  int compression_level, bool sync);
 130 WalWriteMethod *CreateWalTarMethod(const char *tarbase,
 131                                                                    pg_compress_algorithm compression_algorithm,
 132                                                                    int compression_level, bool sync);
 133
 134 const char *GetLastWalMethodError(WalWriteMethod *wwmethod);