Description
PostgreSQL physical and logical replication command and streaming-frame encoding, decoding, and accessors.
Applied_LSN
function Applied_LSN (Item : Stream_Message) return LSN
Return the standby's last applied WAL position.
Parameters
- Item
Standby_Status_Update message.
Return value
Last WAL byte applied by the standby.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Byte
subtype Byte is Ada.Streams.Stream_Element;
One protocol payload octet.
Byte_Array
subtype Byte_Array is Ada.Streams.Stream_Element_Array;
Contiguous protocol payload octets.
Command
type Command is private;
Validated decoded replication-mode command with owned source message.
Command_Kind
type Command_Kind is
(Identify_System_Command,
Show_Command,
Timeline_History_Command,
Create_Logical_Slot_Command,
Drop_Replication_Slot_Command,
Upload_Manifest_Command,
Base_Backup_Command,
Start_Physical_Command,
Start_Logical_Command);
Replication-mode simple-query command classification.
Enumeration literals
- Identify_System_Command
IDENTIFY_SYSTEM.
- Show_Command
SHOW parameter.
- Timeline_History_Command
TIMELINE_HISTORY timeline.
- Create_Logical_Slot_Command
CREATE_REPLICATION_SLOT LOGICAL.
- Drop_Replication_Slot_Command
DROP_REPLICATION_SLOT.
- Upload_Manifest_Command
PostgreSQL 17+ UPLOAD_MANIFEST.
- Base_Backup_Command
BASE_BACKUP.
- Start_Physical_Command
Physical START_REPLICATION.
- Start_Logical_Command
Logical START_REPLICATION SLOT.
Create_Logical_Slot
function Create_Logical_Slot
(Slot_Name : String;
Plugin : String := "pgoutput";
Snapshot : Snapshot_Action := Export_Snapshot;
Server_Major : Positive := 18;
Two_Phase : Boolean := False) return Protocol.Message
Construct version-appropriate logical slot creation syntax.
Parameters
- Slot_Name
Valid lowercase replication slot identifier.
- Plugin
Logical output plugin name.
- Snapshot
Snapshot policy for slot consistency.
- Server_Major
PostgreSQL major version, 14 or newer.
- Two_Phase
Decode prepared transactions on PostgreSQL 15 or newer.
Return value
Simple Query message containing CREATE_REPLICATION_SLOT.
Raised exceptions
- Protocol_Error
A name is invalid.
Data
function Data (Item : Stream_Message) return Byte_Array
Copy the WAL or logical payload carried by XLogData.
Parameters
- Item
XLog_Data message.
Return value
WAL or logical-output bytes.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Decode
function Decode (Item : Protocol.Message) return Stream_Message
Decode the payload of a CopyData message used by physical or logical streaming replication.
Parameters
- Item
CopyData protocol message.
Return value
Classified replication stream message.
Raised exceptions
- Protocol
.Protocol_Error The payload is malformed or unknown.
Decode_Command
function Decode_Command (Item : Protocol.Message) return Command
Decode the command grammar emitted by PostgreSQL and the constructors in this package.
Parameters
- Item
Simple Query message containing one replication command.
Return value
Validated decoded command.
Raised exceptions
- Protocol
.Protocol_Error The message or command is malformed.
Drop_Replication_Slot
function Drop_Replication_Slot
(Slot_Name : String; Wait : Boolean := False) return Protocol.Message
Construct a replication slot drop command.
Parameters
- Slot_Name
Valid lowercase replication slot identifier.
- Wait
Include WAIT when an active owner should be awaited.
Return value
Simple Query message containing DROP_REPLICATION_SLOT.
Raised exceptions
- Protocol_Error
Slot_Name is invalid.
Feedback_Catalog_Xmin
function Feedback_Catalog_Xmin
(Item : Stream_Message) return Transaction_Id
Return the standby's oldest required catalog transaction ID.
Parameters
- Item
Hot_Standby_Feedback message.
Return value
Oldest catalog transaction still needed by the standby.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Feedback_Catalog_Xmin_Epoch
function Feedback_Catalog_Xmin_Epoch
(Item : Stream_Message) return UInt32
Return the epoch associated with feedback catalog Xmin.
Parameters
- Item
Hot_Standby_Feedback message.
Return value
Epoch disambiguating catalog-Xmin wraparound.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Feedback_Xmin
function Feedback_Xmin (Item : Stream_Message) return Transaction_Id
Return the standby's oldest required regular transaction ID.
Parameters
- Item
Hot_Standby_Feedback message.
Return value
Oldest regular transaction still needed by the standby.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Feedback_Xmin_Epoch
function Feedback_Xmin_Epoch (Item : Stream_Message) return UInt32
Return the epoch associated with feedback Xmin.
Parameters
- Item
Hot_Standby_Feedback message.
Return value
Epoch disambiguating Feedback_Xmin wraparound.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Flushed_LSN
function Flushed_LSN (Item : Stream_Message) return LSN
Return the standby's last durably flushed WAL position.
Parameters
- Item
Standby_Status_Update message.
Return value
Last WAL byte flushed durably by the standby.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Has_Timeline
function Has_Timeline (Item : Command) return Boolean
Test whether a command includes a timeline value.
Parameters
- Item
TIMELINE_HISTORY or physical START_REPLICATION command.
Return value
True when a timeline value is present.
Raised exceptions
- Protocol
.Protocol_Error Item cannot contain a timeline.
Identify_System
function Identify_System return Protocol.Message
Construct an IDENTIFY_SYSTEM command.
Return value
Simple Query message containing IDENTIFY_SYSTEM.
Image
function Image (Value : LSN) return String
Render an LSN in canonical hexadecimal X/Y notation.
Parameters
- Value
Log sequence number to render.
Return value
Uppercase PostgreSQL LSN text.
Int64
subtype Int64 is Interfaces.Integer_64;
Signed 64-bit wire integer.
Kind
function Kind (Item : Command) return Command_Kind
Return a decoded replication command's variant.
Parameters
- Item
Decoded command.
Return value
Its command variant.
Kind
function Kind (Item : Stream_Message) return Stream_Message_Kind
Return a decoded replication stream message's variant.
Parameters
- Item
Decoded stream message.
Return value
Its payload variant.
Logical_Option
type Logical_Option is private;
One START_REPLICATION logical plugin option, with optional value.
Logical_Option_Array
type Logical_Option_Array is array (Positive range <>) of Logical_Option;
Ordered logical plugin options.
LSN
subtype LSN is UInt64;
PostgreSQL log sequence number represented as a 64-bit byte position.
Make_Hot_Standby_Feedback
function Make_Hot_Standby_Feedback
(Sent_At : Replication_Timestamp;
Xmin : Transaction_Id;
Xmin_Epoch : UInt32;
Catalog_Xmin : Transaction_Id;
Catalog_Xmin_Epoch : UInt32) return Protocol.Message
Construct a hot-standby feedback CopyData message.
Parameters
- Sent_At
Current PostgreSQL replication timestamp.
- Xmin
Oldest regular transaction still required.
- Xmin_Epoch
Epoch disambiguating Xmin wraparound.
- Catalog_Xmin
Oldest catalog transaction still required.
- Catalog_Xmin_Epoch
Epoch disambiguating catalog-Xmin wraparound.
Return value
Encoded CopyData protocol message.
Make_Primary_Keepalive
function Make_Primary_Keepalive
(WAL_End : LSN;
Sent_At : Replication_Timestamp;
Reply_Requested : Boolean := False) return Protocol.Message
Construct a primary keepalive CopyData message.
Parameters
- WAL_End
Primary's current end-of-WAL position.
- Sent_At
Current PostgreSQL replication timestamp.
- Reply_Requested
Ask the standby for immediate status feedback.
Return value
Encoded CopyData protocol message.
Make_Standby_Status_Update
function Make_Standby_Status_Update
(Received_LSN : LSN;
Flushed_LSN : LSN;
Applied_LSN : LSN;
Sent_At : Replication_Timestamp;
Reply_Requested : Boolean := False) return Protocol.Message
Construct a standby status-update CopyData message.
Parameters
- Received_LSN
Last WAL byte written locally.
- Flushed_LSN
Last WAL byte flushed durably.
- Applied_LSN
Last WAL byte applied.
- Sent_At
Current PostgreSQL replication timestamp.
- Reply_Requested
Request an immediate primary reply.
Return value
Encoded CopyData protocol message.
Make_XLog_Data
function Make_XLog_Data
(WAL_Start : LSN;
WAL_End : LSN;
Sent_At : Replication_Timestamp;
Data : Byte_Array) return Protocol.Message
Construct a primary XLogData CopyData message.
Parameters
- WAL_Start
LSN of the first byte represented by Data.
- WAL_End
Primary's current end-of-WAL position.
- Sent_At
Current PostgreSQL replication timestamp.
- Data
Raw WAL or logical-output bytes.
Return value
Encoded CopyData protocol message.
No_Logical_Options
No_Logical_Options : constant Logical_Option_Array (1 .. 0);
Empty default option list.
Option
function Option (Name : String) return Logical_Option
Construct a valueless logical plugin option.
Parameters
- Name
Nonempty ASCII letter, digit, or underscore identifier.
Return value
Option preserving absence of a value.
Raised exceptions
- Protocol
.Protocol_Error Name is invalid.
Option
function Option (Name : String; Value : String) return Logical_Option
Construct a valued logical plugin option.
Parameters
- Name
Nonempty ASCII letter, digit, or underscore identifier.
- Value
Option text, which may be empty and is SQL-quoted safely.
Return value
Option preserving the supplied value.
Raised exceptions
- Protocol
.Protocol_Error Name is invalid.
Option_Has_Value
function Option_Has_Value (Item : Logical_Option) return Boolean
Test whether a logical option explicitly carries a value.
Parameters
- Item
Logical option to inspect.
Return value
True when a value was explicitly supplied.
Option_Name
function Option_Name (Item : Logical_Option) return String
Return a logical option's identifier.
Parameters
- Item
Logical option to inspect.
Return value
Its identifier.
Option_Value
function Option_Value (Item : Logical_Option) return String
Return a valued logical option's text.
Parameters
- Item
Logical option to inspect.
Return value
Its value; empty both for a valueless option and an explicitly empty value. Use Option_Has_Value to distinguish those cases.
Options
function Options (Item : Command) return Logical_Option_Array
Return logical START_REPLICATION options, preserving valueless options versus options whose explicit value is empty.
Parameters
- Item
Logical START_REPLICATION command.
Return value
Ordered plugin options.
Raised exceptions
- Protocol
.Protocol_Error Item is not a logical start command.
Original_Message
function Original_Message (Item : Command) return Protocol.Message
Return the Query message retained by a decoded command.
Parameters
- Item
Decoded command.
Return value
Owned copy of the original Query message.
Original_Message
function Original_Message (Item : Stream_Message) return Protocol.Message
Return the CopyData message retained by a decoded stream event.
Parameters
- Item
Decoded stream message.
Return value
Owned copy of the original CopyData message.
Parameter
function Parameter (Item : Command) return String
Return the parameter named by a SHOW command.
Parameters
- Item
SHOW command.
Return value
SHOW parameter name.
Raised exceptions
- Protocol
.Protocol_Error Item is not a SHOW command.
Plugin
function Plugin (Item : Command) return String
Return the plugin named by CREATE_REPLICATION_SLOT.
Parameters
- Item
CREATE_REPLICATION_SLOT command.
Return value
Output plugin name.
Raised exceptions
- Protocol
.Protocol_Error Item is another command kind.
Position
function Position (Item : Command) return LSN
Return the position named by START_REPLICATION.
Parameters
- Item
START_REPLICATION command.
Return value
Requested start LSN.
Raised exceptions
- Protocol
.Protocol_Error Item is not a start command.
Received_LSN
function Received_LSN (Item : Stream_Message) return LSN
Return the standby's last written WAL position.
Parameters
- Item
Standby_Status_Update message.
Return value
Last WAL byte written by the standby.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Replication_Timestamp
subtype Replication_Timestamp is Int64;
Microseconds since PostgreSQL's 2000-01-01 epoch.
Reply_Requested
function Reply_Requested (Item : Stream_Message) return Boolean
Test whether a stream message requests an immediate response.
Parameters
- Item
Keepalive or standby-status message.
Return value
True when an immediate response was requested.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
Sent_At
function Sent_At (Item : Stream_Message) return Replication_Timestamp
Return a stream message's sender timestamp.
Parameters
- Item
Any decoded stream message.
Return value
Sender's PostgreSQL-epoch timestamp.
Show
function Show (Parameter : String) return Protocol.Message
Construct a replication-mode SHOW command.
Parameters
- Parameter
Nonempty ASCII letter, digit, or underscore identifier.
Return value
Simple Query message containing SHOW.
Raised exceptions
- Protocol
.Protocol_Error Parameter is invalid.
Slot_Name
function Slot_Name (Item : Command) return String
Return the slot named by create, drop, or START_REPLICATION. A physical start without a slot returns the empty string.
Parameters
- Item
Command with an applicable slot field.
Return value
Slot name, possibly empty for physical streaming.
Raised exceptions
- Protocol
.Protocol_Error Item has no slot field.
Snapshot
function Snapshot (Item : Command) return Snapshot_Action
Return the snapshot policy named by CREATE_REPLICATION_SLOT.
Parameters
- Item
CREATE_REPLICATION_SLOT command.
Return value
Requested snapshot policy.
Raised exceptions
- Protocol
.Protocol_Error Item is another command kind.
Snapshot_Action
type Snapshot_Action is (Export_Snapshot, No_Snapshot, Use_Snapshot);
Snapshot policy requested while creating a logical replication slot.
Enumeration literals
- Export_Snapshot
Export a new snapshot to a separate SQL session.
- No_Snapshot
Create the slot without exporting a snapshot.
- Use_Snapshot
Bind the slot to the repeatable-read snapshot of the current SQL session.
Start_Logical
function Start_Logical
(Slot_Name : String;
Position : LSN;
Options : Logical_Option_Array := No_Logical_Options)
return Protocol.Message
Construct logical START_REPLICATION syntax.
Parameters
- Slot_Name
Required logical replication slot identifier.
- Position
First logical decoding position requested.
- Options
Ordered output-plugin options.
Return value
Simple Query message containing START_REPLICATION SLOT.
Raised exceptions
- Protocol
.Protocol_Error Slot_Name or an option is invalid.
Start_Physical
function Start_Physical
(Position : LSN;
Slot_Name : String := "";
Timeline : UInt32 := 0) return Protocol.Message
Construct physical START_REPLICATION syntax.
Parameters
- Position
First WAL position requested from the primary.
- Slot_Name
Optional physical replication slot identifier.
- Timeline
Optional nonzero timeline; zero omits TIMELINE.
Return value
Simple Query message containing START_REPLICATION.
Raised exceptions
- Protocol
.Protocol_Error Slot_Name is invalid.
Stream_Message
type Stream_Message is private;
Validated decoded replication streaming message with owned payload.
Stream_Message_Kind
type Stream_Message_Kind is
(XLog_Data,
Primary_Keepalive,
Standby_Status_Update,
Hot_Standby_Feedback);
Replication CopyData payload classification.
Enumeration literals
- XLog_Data
Primary WAL or logical output data.
- Primary_Keepalive
Primary liveness and WAL-end update.
- Standby_Status_Update
Standby's write, flush, and apply progress.
- Hot_Standby_Feedback
Standby's oldest required transaction IDs.
Timeline
function Timeline (Item : Command) return UInt32
Return a command's timeline identifier.
Parameters
- Item
Command for which Has_Timeline is True.
Return value
Requested timeline identifier.
Raised exceptions
- Protocol
.Protocol_Error No timeline is present.
Timeline_History
function Timeline_History (Timeline : UInt32) return Protocol.Message
Construct a TIMELINE_HISTORY command.
Parameters
- Timeline
Nonzero timeline whose history is requested.
Return value
Simple Query message containing TIMELINE_HISTORY.
Raised exceptions
- Protocol
.Protocol_Error Timeline is zero.
Transaction_Id
subtype Transaction_Id is UInt32;
PostgreSQL 32-bit transaction identifier.
Two_Phase
function Two_Phase (Item : Command) return Boolean
Test whether CREATE_REPLICATION_SLOT enabled two-phase decoding.
Parameters
- Item
CREATE_REPLICATION_SLOT command.
Return value
True when prepared transactions are decoded by the slot.
Raised exceptions
- Protocol
.Protocol_Error Item is another command kind.
UInt32
subtype UInt32 is Interfaces.Unsigned_32;
Unsigned 32-bit wire integer.
UInt64
subtype UInt64 is Interfaces.Unsigned_64;
Unsigned 64-bit wire integer.
Value
function Value (Text : String) return LSN
Parse canonical or case-insensitive hexadecimal X/Y LSN text.
Parameters
- Text
PostgreSQL LSN representation.
Return value
Numeric log sequence number.
Raised exceptions
- Protocol
.Protocol_Error Text is malformed or overflows.
Wait
function Wait (Item : Command) return Boolean
Test whether DROP_REPLICATION_SLOT included WAIT.
Parameters
- Item
DROP_REPLICATION_SLOT command.
Return value
True when the command included WAIT.
Raised exceptions
- Protocol
.Protocol_Error Item is another command kind.
WAL_End
function WAL_End (Item : Stream_Message) return LSN
Return the primary's advertised end-of-WAL position.
Parameters
- Item
XLog_Data or Primary_Keepalive message.
Return value
Primary's current end-of-WAL position.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.
WAL_Start
function WAL_Start (Item : Stream_Message) return LSN
Return the first LSN represented by an XLogData message.
Parameters
- Item
XLog_Data message.
Return value
LSN of the first byte represented by Data.
Raised exceptions
- Protocol
.Protocol_Error Item is another variant.