Description
Application-owned state contracts for replication slots, retained WAL, timeline history, and prepared logical transactions. Implementations choose their durability technology while preserving the atomicity and monotonicity requirements declared by each operation.
Acquire
procedure Acquire
(Item : in out Slot_Store;
Name : String;
Expected : Slot_Kind;
Result : out Acquire_Result;
Lease : out UInt64;
State : out Slot_State)
Atomically reject an already-active slot or issue a nonzero generation lease. Later mutations are conditional on the lease, preventing a stale replication session from advancing state.
Parameters
- Item
Store to mutate.
- Name
Slot name.
- Expected
Required physical or logical category.
- Result
Acquisition outcome.
- Lease
New nonzero generation on success, otherwise zero.
- State
Consistent slot snapshot associated with the outcome.
Acquire_Result
type Acquire_Result is
(Acquired, Missing, Kind_Mismatch, Already_Active, Invalidated);
Outcome of atomic slot acquisition.
Enumeration literals
- Acquired
A new exclusive lease was issued.
- Missing
No slot has the requested name.
- Kind_Mismatch
The stored slot has a different category.
- Already_Active
Another owner holds the slot lease.
- Invalidated
The slot is no longer usable.
Advance
procedure Advance
(Item : in out Slot_Store;
Name : String;
Lease : UInt64;
Restart : LSN;
Confirmed : LSN;
Advanced : out Boolean)
Atomically and durably advance a slot without moving either LSN backwards. A stale or inactive lease must be rejected without mutation.
Parameters
- Item
Store to mutate.
- Name
Slot name.
- Lease
Generation returned by Acquire.
- Restart
New WAL retention position.
- Confirmed
New logical acknowledgement; use zero when not applicable.
- Advanced
True only after the new state satisfies the backend's durability contract.
Append
procedure Append
(Item : in out WAL_Store;
Start : LSN;
Data : Byte_Array)
Durably append a contiguous WAL range.
Parameters
- Item
Store to mutate.
- Start
Current_LSN, or the base position of an empty store.
- Data
Bytes to append in WAL order.
Byte_Array
subtype Byte_Array is Ada.Streams.Stream_Element_Array;
Contiguous protocol or WAL bytes exchanged with a persistence backend.
Confirmed_LSN
function Confirmed_LSN (Item : Slot_State) return LSN
Read a slot's durable logical acknowledgement.
Parameters
- Item
Existing slot snapshot.
Return value
Confirmed LSN, or zero when not applicable.
Create
procedure Create
(Item : in out Slot_Store;
Name : String;
State : Slot_State;
Result : out Create_Result)
Create a named slot without replacing an existing slot.
Parameters
- Item
Store to mutate.
- Name
Nonempty stable slot name.
- State
Initial state created by Make_Slot.
- Result
Whether the slot was created or already existed.
Create_Result
type Create_Result is (Created, Already_Exists);
Outcome of idempotent slot creation.
Enumeration literals
- Created
A new slot was stored.
- Already_Exists
The name was already present and was not changed.
Current_LSN
function Current_LSN (Item : WAL_Store) return LSN
Read the position immediately after available WAL.
Parameters
- Item
Store to query.
Return value
Exclusive end LSN.
Current_Timeline
function Current_Timeline (Item : Timeline_Store) return UInt32
Read the current PostgreSQL timeline identifier.
Parameters
- Item
Store to query.
Return value
Nonzero current timeline.
Drop
procedure Drop
(Item : in out Slot_Store;
Name : String;
Dropped : out Boolean)
Drop an inactive slot without affecting an active owner.
Parameters
- Item
Store to mutate.
- Name
Slot name.
- Dropped
True only when an inactive stored slot was removed.
Exists
function Exists (Item : Prepared_Transaction) return Boolean
Test whether a snapshot represents stored prepared state.
Parameters
- Item
Snapshot to inspect.
Return value
True when Item is not No_Prepared_Transaction.
Exists
function Exists (Item : Slot_State) return Boolean
Test whether a slot snapshot represents a stored slot.
Parameters
- Item
Slot snapshot to inspect.
Return value
True when Item is not No_Slot.
First_LSN
function First_LSN (Item : WAL_Store) return LSN
Read the first retained WAL position.
Parameters
- Item
Store to query.
Return value
Inclusive first retained LSN.
Generation
function Generation (Item : Slot_State) return UInt64
Read the lease generation captured by a slot snapshot.
Parameters
- Item
Slot snapshot to inspect.
Return value
Nonzero generation for an acquired slot, otherwise zero.
History
function History
(Item : Timeline_Store; Timeline : UInt32) return Byte_Array
Read a timeline history file exactly as sent to a standby.
Parameters
- Item
Store to query.
- Timeline
Timeline whose history is requested.
Return value
History contents, or an empty array when unavailable.
Invalidate
procedure Invalidate
(Item : in out Slot_Store;
Name : String;
Invalidated : out Boolean)
Mark a stored slot unusable for future acquisitions.
Parameters
- Item
Store to mutate.
- Name
Slot name.
- Invalidated
True when the named slot exists and is invalidated.
Is_Active
function Is_Active (Item : Slot_State) return Boolean
Test whether the snapshot was acquired by a replication session.
Parameters
- Item
Slot snapshot to inspect.
Return value
True when the slot has an active lease.
Is_Invalidated
function Is_Invalidated (Item : Slot_State) return Boolean
Test whether a slot can no longer be acquired.
Parameters
- Item
Slot snapshot to inspect.
Return value
True when the slot has been invalidated.
Kind
function Kind (Item : Slot_State) return Slot_Kind
Read the category of a slot snapshot.
Parameters
- Item
Existing slot snapshot.
Return value
Physical_Slot or Logical_Slot.
Load
function Load
(Item : Prepared_Store;
Slot_Name : String;
GID : String) return Prepared_Transaction
Load a consistent prepared-transaction snapshot.
Parameters
- Item
Store to query.
- Slot_Name
Logical slot name.
- GID
PostgreSQL prepared-transaction identifier.
Return value
Stored state, or No_Prepared_Transaction when absent.
Load
function Load
(Item : Slot_Store; Name : String) return Slot_State
Load a consistent snapshot of a named slot.
Parameters
- Item
Store to query.
- Name
Slot name.
Return value
Stored state, or No_Slot when absent.
Make_Prepared
function Make_Prepared
(XID : Transaction_Id;
Prepare_LSN : LSN;
Payload : Byte_Array;
Phase : Prepared_Phase := Prepared) return Prepared_Transaction
Construct durable consumer state for a prepared transaction.
Parameters
- XID
Nonzero source transaction identifier.
- Prepare_LSN
Nonzero source prepare position.
- Payload
Deterministic data needed to apply the transaction.
- Phase
Initial recovery phase.
Return value
Initialized prepared-transaction snapshot.
Raised exceptions
- Constraint_Error
XID or Prepare_LSN is zero.
Make_Slot
function Make_Slot
(Kind : Slot_Kind;
Restart_LSN : LSN;
Confirmed_LSN : LSN := 0;
Plugin : String := "") return Slot_State
Construct an inactive, valid slot snapshot.
Parameters
- Kind
Physical or logical slot category.
- Restart_LSN
Oldest WAL position retained for the slot.
- Confirmed_LSN
Logical position durably acknowledged by a consumer; use zero when confirmation is not applicable.
- Plugin
Logical output plugin name; required for logical slots and forbidden for physical slots.
Return value
The initialized slot snapshot.
Raised exceptions
- Constraint_Error
The kind, plugin, or LSN combination is inconsistent.
Mark_Target_Applied
procedure Mark_Target_Applied
(Item : in out Prepared_Store;
Slot_Name : String;
GID : String;
Changed : out Boolean)
Atomically and durably move existing state from Prepared to Target_Applied without regressing an already-applied marker.
Parameters
- Item
Store to mutate.
- Slot_Name
Logical slot name.
- GID
PostgreSQL prepared-transaction identifier.
- Changed
True only when this call performed the transition.
No_Prepared_Transaction
No_Prepared_Transaction : constant Prepared_Transaction;
Sentinel returned by Load when no prepared transaction exists.
No_Slot
No_Slot : constant Slot_State;
Sentinel returned by Load when the named slot does not exist.
Oldest_Restart_LSN
function Oldest_Restart_LSN (Item : Slot_Store) return LSN
Compute the retention floor across all non-invalidated slots.
Parameters
- Item
Store to query.
Return value
Oldest restart LSN, or zero when no slot retains WAL.
Payload
function Payload (Item : Prepared_Transaction) return Byte_Array
Copy the deterministic target-application payload.
Parameters
- Item
Existing prepared snapshot.
Return value
Stored payload bytes.
Phase
function Phase (Item : Prepared_Transaction) return Prepared_Phase
Read the durable recovery phase.
Parameters
- Item
Existing prepared snapshot.
Return value
Prepared or Target_Applied.
Plugin
function Plugin (Item : Slot_State) return String
Read a slot's logical output plugin.
Parameters
- Item
Existing slot snapshot.
Return value
Plugin name, or an empty string for a physical slot.
Prepare_LSN
function Prepare_LSN (Item : Prepared_Transaction) return LSN
Read the source prepare position.
Parameters
- Item
Existing prepared snapshot.
Return value
Stored prepare LSN.
Prepared_Phase
type Prepared_Phase is (Prepared, Target_Applied);
Durable consumer phase for a two-phase logical transaction.
Enumeration literals
- Prepared
Payload is durable but not marked applied at the target.
- Target_Applied
Target application is durably recorded.
Prepared_Store
type Prepared_Store is limited interface;
Durable state interface for prepared logical-consumer recovery.
Prepared_Transaction
type Prepared_Transaction is private;
Durable prepared-transaction snapshot and replay payload.
Promote
procedure Promote
(Item : in out Timeline_Store;
Parent : UInt32;
Fork_LSN : LSN;
New_Timeline : out UInt32)
Atomically allocate and persist a timeline whose history records Parent and Fork_LSN before it becomes current.
Parameters
- Item
Store to mutate.
- Parent
Timeline being promoted from; it must still be current.
- Fork_LSN
Nonzero WAL fork position.
- New_Timeline
Newly persisted current timeline.
Put
procedure Put
(Item : in out Prepared_Store;
Slot_Name : String;
GID : String;
Transaction : Prepared_Transaction)
Durably insert or replace prepared state identified by slot and GID.
Parameters
- Item
Store to mutate.
- Slot_Name
Logical slot name.
- GID
PostgreSQL prepared-transaction identifier.
- Transaction
Complete state to persist before source acknowledgement.
Read
function Read
(Item : WAL_Store;
Start : LSN;
Maximum : Positive) return Byte_Array
Read a bounded contiguous WAL range beginning at Start.
Parameters
- Item
Store to query.
- Start
Inclusive retained LSN.
- Maximum
Maximum number of bytes to return.
Return value
Up to Maximum bytes, empty only when Start equals Current_LSN.
Release
procedure Release
(Item : in out Slot_Store;
Name : String;
Lease : UInt64;
Released : out Boolean)
Release an active slot only when the generation still matches.
Parameters
- Item
Store to mutate.
- Name
Slot name.
- Lease
Generation returned by Acquire.
- Released
True only when this owner released the active lease.
Remove
procedure Remove
(Item : in out Prepared_Store;
Slot_Name : String;
GID : String;
Removed : out Boolean)
Remove prepared state after the source commit is durably acknowledged.
Parameters
- Item
Store to mutate.
- Slot_Name
Logical slot name.
- GID
PostgreSQL prepared-transaction identifier.
- Removed
True only when stored state was removed.
Restart_LSN
function Restart_LSN (Item : Slot_State) return LSN
Read the oldest WAL position retained by a slot.
Parameters
- Item
Existing slot snapshot.
Return value
Stored restart LSN.
Retain_From
procedure Retain_From
(Item : in out WAL_Store; Oldest : LSN)
Discard bytes before Oldest while preserving the retained suffix.
Parameters
- Item
Store to mutate.
- Oldest
New inclusive first retained LSN.
Slot_Kind
type Slot_Kind is (Physical_Slot, Logical_Slot);
Replication slot category.
Enumeration literals
- Physical_Slot
Retains WAL for a physical standby.
- Logical_Slot
Retains WAL and confirmed output for a plugin.
Slot_State
type Slot_State is private;
Immutable snapshot of one stored replication slot.
Slot_Store
type Slot_Store is limited interface;
Atomic persistence interface for physical and logical slot state.
Store_Error
Store_Error : exception;
Raised when a store cannot satisfy its persistence contract.
Timeline_Store
type Timeline_Store is limited interface;
Persistence interface for current timeline and history files.
UInt64
subtype UInt64 is Interfaces.Unsigned_64;
Unsigned generation counter used to fence stale slot owners.
WAL_Store
type WAL_Store is limited interface;
Contiguous retained-WAL persistence interface.
XID
function XID (Item : Prepared_Transaction) return Transaction_Id
Read the source transaction identifier.
Parameters
- Item
Existing prepared snapshot.
Return value
Stored XID.