1/*-------------------------------------------------------------------------
4 * API for filtering or sending to a final destination the archives
5 * produced by the base backup process
7 * Taking a base backup produces one archive per tablespace directory,
8 * plus a backup manifest unless that feature has been disabled. The
9 * goal of the backup process is to put those archives and that manifest
10 * someplace, possibly after postprocessing them in some way. A 'bbsink'
11 * is an object to which those archives, and the manifest if present,
14 * In practice, there will be a chain of 'bbsink' objects rather than
15 * just one, with callbacks being forwarded from one to the next,
16 * possibly with modification. Each object is responsible for a
17 * single task e.g. command progress reporting, throttling, or
18 * communication with the client.
20 * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
22 * src/include/backup/basebackup_sink.h
24 *-------------------------------------------------------------------------
26#ifndef BASEBACKUP_SINK_H
27#define BASEBACKUP_SINK_H
33/* Forward declarations. */
40 * Overall backup state shared by all bbsink objects for a backup.
42 * Before calling bbstate_begin_backup, caller must initiate a bbsink_state
43 * object which will last for the lifetime of the backup, and must thereafter
44 * update it as required before each new call to a bbsink method. The bbsink
45 * will retain a pointer to the state object and will consult it to understand
46 * the progress of the backup.
48 * 'tablespaces' is a list of tablespaceinfo objects. It must be set before
49 * calling bbstate_begin_backup() and must not be modified thereafter.
51 * 'tablespace_num' is the index of the current tablespace within the list
52 * stored in 'tablespaces'.
54 * 'bytes_done' is the number of bytes read so far from $PGDATA.
56 * 'bytes_total' is the total number of bytes estimated to be present in
57 * $PGDATA, if we have estimated this.
59 * 'bytes_total_is_valid' is true if and only if a proper estimate has been
60 * stored into 'bytes_total'.
62 * 'startptr' and 'starttli' identify the point in the WAL stream at which
63 * the backup began. They must be set before calling bbstate_begin_backup()
64 * and must not be modified thereafter.
78 * Common data for any type of basebackup sink.
80 * 'bbs_ops' is the relevant callback table.
82 * 'bbs_buffer' is the buffer into which data destined for the bbsink
83 * should be stored. It must be a multiple of BLCKSZ.
85 * 'bbs_buffer_length' is the allocated length of the buffer.
87 * 'bbs_next' is a pointer to another bbsink to which this bbsink is
88 * forwarding some or all operations.
90 * 'bbs_state' is a pointer to the bbsink_state object for this backup.
91 * Every bbsink associated with this backup should point to the same
92 * underlying state object.
94 * In general it is expected that the values of these fields are set when
95 * a bbsink is created and that they do not change thereafter. It's OK
96 * to modify the data to which bbs_buffer or bbs_state point, but no changes
97 * should be made to the contents of this struct.
109 * Callbacks for a base backup sink.
111 * All of these callbacks are required. If a particular callback just needs to
112 * forward the call to sink->bbs_next, use bbsink_forward_<callback_name> as
115 * Callers should always invoke these callbacks via the bbsink_* inline
116 * functions rather than calling them directly.
121 * This callback is invoked just once, at the very start of the backup. It
122 * must set bbs_buffer to point to a chunk of storage where at least
123 * bbs_buffer_length bytes of data can be written.
128 * For each archive transmitted to a bbsink, there will be one call to the
129 * begin_archive() callback, some number of calls to the
130 * archive_contents() callback, and then one call to the end_archive()
133 * Before invoking the archive_contents() callback, the caller should copy
134 * a number of bytes equal to what will be passed as len into bbs_buffer,
135 * but not more than bbs_buffer_length.
137 * It's generally good if the buffer is as full as possible before the
138 * archive_contents() callback is invoked, but it's not worth expending
139 * extra cycles to make sure it's absolutely 100% full.
146 * If a backup manifest is to be transmitted to a bbsink, there will be
147 * one call to the begin_manifest() callback, some number of calls to the
148 * manifest_contents() callback, and then one call to the end_manifest()
149 * callback. These calls will occur after all archives are transmitted.
151 * The rules for invoking the manifest_contents() callback are the same as
152 * for the archive_contents() callback above.
159 * This callback is invoked just once, after all archives and the manifest
165 * If a backup is aborted by an error, this callback is invoked before the
166 * bbsink object is destroyed, so that it can release any resources that
167 * would not be released automatically. If no error occurs, this callback
168 * is invoked after the end_backup callback.
179 Assert(buffer_length > 0);
189/* Begin an archive. */
198/* Process some of the contents of an archive. */
205 * The caller should make a reasonable attempt to fill the buffer before
206 * calling this function, so it shouldn't be completely empty. Nor should
207 * it be filled beyond capacity.
209 Assert(
len > 0 && len <= sink->bbs_buffer_length);
214/* Finish an archive. */
223/* Begin the backup manifest. */
232/* Process some of the manifest contents. */
238 /* See comments in bbsink_archive_contents. */
239 Assert(
len > 0 && len <= sink->bbs_buffer_length);
244/* Finish the backup manifest. */
253/* Finish a backup. */
263/* Release resources before destruction. */
272/* Forwarding callbacks. Use these to pass operations through to next sink. */
275 const char *archive_name);
285/* Constructors for various types of sinks. */
295/* Extra interface functions for progress reporting. */
static void bbsink_begin_backup(bbsink *sink, bbsink_state *state, int buffer_length)
bbsink * bbsink_zstd_new(bbsink *next, pg_compress_specification *)
void basebackup_progress_wait_checkpoint(void)
bbsink * bbsink_gzip_new(bbsink *next, pg_compress_specification *)
void bbsink_forward_begin_backup(bbsink *sink)
void bbsink_forward_begin_manifest(bbsink *sink)
bbsink * bbsink_copystream_new(bool send_to_client)
void bbsink_forward_end_backup(bbsink *sink, XLogRecPtr endptr, TimeLineID endtli)
bbsink * bbsink_throttle_new(bbsink *next, uint32 maxrate)
bbsink * bbsink_lz4_new(bbsink *next, pg_compress_specification *)
static void bbsink_begin_archive(bbsink *sink, const char *archive_name)
void bbsink_forward_cleanup(bbsink *sink)
void bbsink_forward_manifest_contents(bbsink *sink, size_t len)
static void bbsink_end_archive(bbsink *sink)
static void bbsink_begin_manifest(bbsink *sink)
bbsink * bbsink_progress_new(bbsink *next, bool estimate_backup_size, bool incremental)
struct bbsink_state bbsink_state
static void bbsink_end_backup(bbsink *sink, XLogRecPtr endptr, TimeLineID endtli)
void bbsink_forward_end_archive(bbsink *sink)
void bbsink_forward_archive_contents(bbsink *sink, size_t len)
static void bbsink_cleanup(bbsink *sink)
void basebackup_progress_wait_wal_archive(bbsink_state *)
void bbsink_forward_begin_archive(bbsink *sink, const char *archive_name)
static void bbsink_end_manifest(bbsink *sink)
void bbsink_forward_end_manifest(bbsink *sink)
static void bbsink_archive_contents(bbsink *sink, size_t len)
static void bbsink_manifest_contents(bbsink *sink, size_t len)
void basebackup_progress_done(void)
void basebackup_progress_transfer_wal(void)
void basebackup_progress_estimate_backup_size(void)
bbsink * bbsink_server_new(bbsink *next, char *pathname)
Assert(PointerIsAligned(start, uint64))
static int list_length(const List *l)
void(* begin_manifest)(bbsink *sink)
void(* cleanup)(bbsink *sink)
void(* end_manifest)(bbsink *sink)
void(* end_archive)(bbsink *sink)
void(* manifest_contents)(bbsink *sink, size_t len)
void(* begin_backup)(bbsink *sink)
void(* end_backup)(bbsink *sink, XLogRecPtr endptr, TimeLineID endtli)
void(* archive_contents)(bbsink *sink, size_t len)
void(* begin_archive)(bbsink *sink, const char *archive_name)
bool bytes_total_is_valid
const bbsink_ops * bbs_ops