Description
Native, bounded-memory BASE_BACKUP commands and response streaming for PostgreSQL 14 through 18. A Receiver returns at most one PostgreSQL CopyData payload per call and never accumulates archive or manifest contents.
Abort_Manifest_Upload
procedure Abort_Manifest_Upload
(Connection : in out Client.Session;
Reason : String;
Timeout : Duration := 30.0)
Abort manifest COPY IN with a client error message.
Parameters
- Connection
Session with an active manifest upload.
- Reason
Nonempty diagnostic sent in CopyFail.
- Timeout
Per-message transport timeout. Manifest upload uses the existing bounded COPY IN path. After finish or abort, consume Client.Receive_Copy_Event and Receive_Query_Event until Client.Is_Ready before issuing BASE_BACKUP.
Archive_Location
function Archive_Location (Item : Event) return String
Return the tablespace location announced for an archive.
Parameters
- Item
Archive_Start event.
Return value
Tablespace location associated with the archive.
Archive_Name
function Archive_Name (Item : Event) return String
Return the name announced for an archive.
Parameters
- Item
Archive_Start event.
Return value
Server-selected archive file name.
Backup_Target
type Backup_Target is (Client_Target, Server_Target, Blackhole_Target);
Destination selected by PostgreSQL 15+ TARGET.
Enumeration literals
- Client_Target
Stream archive and manifest bytes to this client.
- Server_Target
Write beneath a database-host path.
- Blackhole_Target
Generate and discard the backup server-side.
Begin_Manifest_Upload
procedure Begin_Manifest_Upload
(Connection : in out Client.Session;
Major : Server_Major;
Timeout : Duration := 30.0)
Send UPLOAD_MANIFEST and consume responses through CopyInResponse.
Parameters
- Connection
Authenticated physical-replication session.
- Major
Actual PostgreSQL server major.
- Timeout
Per-message transport timeout.
Bytes_Completed
function Bytes_Completed (Item : Event) return UInt64
Return the latest current-archive progress count.
Parameters
- Item
Progress event.
Return value
Bytes completed in the current archive/tablespace.
Cancel
procedure Cancel
(Item : Receiver;
Cancellation_Channel : in out Transports.Transport'Class;
Timeout : Duration := 30.0)
Send a PostgreSQL CancelRequest on a distinct caller-owned transport.
Parameters
- Item
Receiver whose session supplies backend key data.
- Cancellation_Channel
Fresh transport to the same PostgreSQL.
- Timeout
Cancellation transport timeout.
Checkpoint_Mode
type Checkpoint_Mode is (Spread_Checkpoint, Fast_Checkpoint);
Checkpoint pacing at backup start.
Enumeration literals
- Spread_Checkpoint
Spread I/O over checkpoint_completion_target.
- Fast_Checkpoint
Complete the checkpoint as quickly as possible.
Command
function Command (Item : Options) return Protocol.Message
Construct the version-correct BASE_BACKUP simple Query command.
Parameters
- Item
Validated options to encode.
Return value
Owned Query message ready for Client.Send.
Compression_Method
type Compression_Method is
(No_Compression, Gzip_Compression, LZ4_Compression, Zstandard_Compression);
PostgreSQL 15+ server-side archive compression.
Enumeration literals
- No_Compression
Produce uncompressed tar streams.
- Gzip_Compression
Compress archives with gzip.
- LZ4_Compression
Compress archives with LZ4.
- Zstandard_Compression
Compress archives with Zstandard.
Data
function Data (Item : Event) return Byte_Array
Return one bounded archive or manifest fragment.
Parameters
- Item
Archive_Data or Manifest_Data event.
Return value
One owned bounded COPY payload.
Defaults
function Defaults (Major : Server_Major) return Options
Construct default options for one known server major.
Parameters
- Major
Actual PostgreSQL server major.
Return value
Client-target options matching PostgreSQL defaults.
Diagnostic
function Diagnostic (Item : Event) return Protocol.Diagnostic
Return a notice or error diagnostic.
Parameters
- Item
Notice or Error event.
Return value
Structured server diagnostic.
End_LSN
function End_LSN (Item : Event) return LSN
Return the consistent backup stop position.
Parameters
- Item
Backup_End event.
Return value
Server-selected consistent stop LSN.
Event
type Event is private;
Owned semantic backup event; payload data remains valid after Receive.
Event_Kind
type Event_Kind is
(Backup_Start,
Tablespace,
Archive_Start,
Archive_Data,
Manifest_Start,
Manifest_Data,
Progress,
Backup_End,
…,
Complete);
Semantic event returned while receiving one base backup.
Enumeration literals
- Backup_Start
Consistent start LSN and timeline are available.
- Tablespace
One row of tablespace metadata is available.
- Archive_Start
A named archive stream is beginning.
- Archive_Data
One bounded archive fragment is available.
- Manifest_Start
The requested manifest stream is beginning.
- Manifest_Data
One bounded manifest fragment is available.
- Progress
Current archive's completed byte count is available.
- Backup_End
Consistent stop LSN and timeline are available.
- Notice
An asynchronous server notice is available.
- Parameter_Status
A changed server parameter is available.
- Error
The server rejected or aborted the backup.
- Complete
ReadyForQuery has completed the exchange.
Finish_Manifest_Upload
procedure Finish_Manifest_Upload
(Connection : in out Client.Session;
Timeout : Duration := 30.0)
Finish manifest COPY IN successfully.
Parameters
- Connection
Session with an active manifest upload.
- Timeout
Per-message transport timeout.
Has_Tablespace_Location
function Has_Tablespace_Location (Item : Event) return Boolean
Test whether a tablespace row contains an external location.
Parameters
- Item
Tablespace event.
Return value
Whether PostgreSQL supplied an external location.
Has_Tablespace_Oid
function Has_Tablespace_Oid (Item : Event) return Boolean
Test whether a tablespace row contains an OID.
Parameters
- Item
Tablespace event.
Return value
Whether PostgreSQL supplied a tablespace OID.
Has_Tablespace_Size
function Has_Tablespace_Size (Item : Event) return Boolean
Test whether a tablespace row contains a size estimate.
Parameters
- Item
Tablespace event.
Return value
Whether progress mode supplied a size estimate.
Include_Tablespace_Map
procedure Include_Tablespace_Map
(Item : in out Options; Enabled : Boolean := True)
Include symbolic-link mappings in tablespace_map.
Parameters
- Item
Options to update.
- Enabled
Whether to include the map file.
Include_WAL
procedure Include_WAL (Item : in out Options; Enabled : Boolean := True)
Include WAL needed to make the archive self-contained.
Parameters
- Item
Options to update.
- Enabled
Whether required WAL is included.
Kind
function Kind (Item : Event) return Event_Kind
Return the event variant.
Parameters
- Item
Event to inspect.
Return value
Discriminating semantic event kind.
Major
function Major (Item : Options) return Server_Major
Return the server major bound to an option set.
Parameters
- Item
Options to inspect.
Return value
Major passed to Defaults.
Manifest_Checksum
type Manifest_Checksum is
(No_Checksum, CRC32C_Checksum, SHA224_Checksum, SHA256_Checksum,
SHA384_Checksum, SHA512_Checksum);
Per-file checksum stored in a requested manifest.
Enumeration literals
- No_Checksum
Do not checksum individual files.
- CRC32C_Checksum
Use the fast default CRC32C checksum.
- SHA224_Checksum
Use SHA-224.
- SHA256_Checksum
Use SHA-256.
- SHA384_Checksum
Use SHA-384.
- SHA512_Checksum
Use SHA-512.
Manifest_Mode
type Manifest_Mode is (No_Manifest, Include_Manifest, Force_Encode_Manifest);
Backup-manifest generation and filename encoding.
Enumeration literals
- No_Manifest
Do not request a manifest.
- Include_Manifest
Request conditional filename encoding.
- Force_Encode_Manifest
Hex-encode every filename for testing.
Options
type Options is private;
Owned BASE_BACKUP options tied to one target server major.
Original_Message
function Original_Message (Item : Event) return Protocol.Message
Return the owned backend message underlying an event.
Parameters
- Item
Any event.
Return value
Original owned backend message when one exists. Accessors reject inapplicable event variants with Protocol_Error.
Receive
function Receive
(Item : in out Receiver; Timeout : Duration := 30.0) return Event
Receive the next semantic event, internally skipping only bounded RowDescription, CommandComplete, and CopyDone framing. Call until Complete, including after Error, so ReadyForQuery is consumed.
Parameters
- Item
Active receiver.
- Timeout
Per-message transport timeout.
Return value
Next owned semantic event.
Receiver
type Receiver
(Connection : not null access Client.Session) is limited private;
Stateful bounded BASE_BACKUP response decoder.
Record fields
- Connection
Authenticated physical-replication session.
Send_Manifest_Chunk
procedure Send_Manifest_Chunk
(Connection : in out Client.Session;
Data : Byte_Array;
Timeout : Duration := 30.0)
Send one bounded manifest fragment through COPY IN.
Parameters
- Connection
Session prepared by Begin_Manifest_Upload.
- Data
Caller-owned fragment copied into one protocol message.
- Timeout
Per-message transport timeout.
Server_Major
subtype Server_Major is Positive range 14 .. 18;
PostgreSQL major whose BASE_BACKUP grammar and wire format are used.
Set_Checkpoint
procedure Set_Checkpoint
(Item : in out Options; Mode : Checkpoint_Mode)
Select spread or fast checkpoint behavior.
Parameters
- Item
Options to update.
- Mode
Desired checkpoint pacing.
Set_Compression
procedure Set_Compression
(Item : in out Options;
Method : Compression_Method;
Detail : String := "")
Select PostgreSQL 15+ server-side archive compression.
Parameters
- Item
Options to update.
- Method
Compression codec, or No_Compression.
- Detail
Server codec options such as level/workers.
Set_Incremental
procedure Set_Incremental
(Item : in out Options; Enabled : Boolean := True)
Request PostgreSQL 17+ incremental backup after manifest upload.
Parameters
- Item
Options to update.
- Enabled
Whether to request an incremental backup. Setters reject options unavailable on Item's server major, invalid target/detail combinations, embedded NUL bytes, and invalid rate limits. PostgreSQL 14 accepts 0 or 32..1_048_576 KiB/s.
Set_Label
procedure Set_Label (Item : in out Options; Label : String)
Set the exact label, including an explicitly empty label.
Parameters
- Item
Options to update.
- Label
Label encoded as a PostgreSQL string constant.
Set_Manifest
procedure Set_Manifest
(Item : in out Options;
Mode : Manifest_Mode;
Checksums : Manifest_Checksum := CRC32C_Checksum)
Configure manifest generation and per-file checksums.
Parameters
- Item
Options to update.
- Mode
Whether and how to generate a manifest.
- Checksums
Per-file checksum for an enabled manifest.
Set_Maximum_Rate
procedure Set_Maximum_Rate
(Item : in out Options; Kilobytes_Per_Second : UInt32)
Throttle the server-to-client transfer rate.
Parameters
- Item
Options to update.
- Kilobytes_Per_Second
Zero or 32 through 1_048_576 KiB/s.
Set_Progress
procedure Set_Progress (Item : in out Options; Enabled : Boolean := True)
Request or suppress tablespace sizes/progress frames.
Parameters
- Item
Options to update.
- Enabled
Whether PostgreSQL should calculate progress.
Set_Target
procedure Set_Target
(Item : in out Options;
Target : Backup_Target;
Detail : String := "")
Select a PostgreSQL 15+ backup target.
Parameters
- Item
Options to update.
- Target
Client, server, or blackhole destination.
- Detail
Required server path, otherwise empty.
Start
procedure Start
(Item : in out Receiver;
Options : Base_Backups.Options;
Timeout : Duration := 30.0)
Send BASE_BACKUP and prepare to receive its semantic event stream.
Parameters
- Item
Idle receiver to start.
- Options
Version-bound command options.
- Timeout
Per-message transport timeout.
Start_LSN
function Start_LSN (Item : Event) return LSN
Return the consistent backup start position.
Parameters
- Item
Backup_Start event.
Return value
Server-selected consistent start LSN.
Status
function Status (Item : Event) return Protocol.Parameter_Status
Return a server parameter update.
Parameters
- Item
Parameter_Status event.
Return value
Owned server parameter update.
Stream_Index
function Stream_Index (Item : Event) return Positive
Return the one-based stream/archive ordinal.
Parameters
- Item
Archive_Start, Archive_Data, or manifest event.
Return value
One-based stream/archive ordinal.
Tablespace_Location
function Tablespace_Location (Item : Event) return String
Return a tablespace row's external location.
Parameters
- Item
Tablespace event with a location.
Return value
Owned external tablespace path.
Tablespace_Oid
function Tablespace_Oid (Item : Event) return UInt32
Return a tablespace row's OID.
Parameters
- Item
Tablespace event with an OID.
Return value
Tablespace OID.
Tablespace_Size_KiB
function Tablespace_Size_KiB (Item : Event) return UInt64
Return a tablespace row's size estimate.
Parameters
- Item
Tablespace event with a size.
Return value
Estimated tablespace size in kibibytes.
Timeline
function Timeline (Item : Event) return UInt32
Return the timeline associated with a backup boundary.
Parameters
- Item
Backup_Start or Backup_End event.
Return value
Timeline associated with the event LSN.
Upload_Manifest_Command
function Upload_Manifest_Command
(Major : Server_Major) return Protocol.Message
Construct PostgreSQL 17+ UPLOAD_MANIFEST.
Parameters
- Major
Actual PostgreSQL server major.
Return value
Owned Query message ready for Client.Send.
Verify_Checksums
procedure Verify_Checksums
(Item : in out Options; Enabled : Boolean := True)
Enable or disable server-side data-checksum verification.
Parameters
- Item
Options to update.
- Enabled
Whether enabled page checksums are verified.
Wait_For_Archive
procedure Wait_For_Archive
(Item : in out Options; Enabled : Boolean := True)
Control waiting for the final WAL segment to be archived.
Parameters
- Item
Options to update.
- Enabled
True to retain PostgreSQL's default wait.