Description
Owned PostgreSQL wire messages, strict decoders, typed backend events, and constructors for frontend protocol operations.
Append_Byte
procedure Append_Byte
(Target : in out Flyology.Bytes.Unbounded_Bytes; Value : Byte)
Append one raw byte.
Parameters
- Target
Buffer extended by one byte.
- Value
Byte to append.
Append_Bytes
procedure Append_Bytes
(Target : in out Flyology.Bytes.Unbounded_Bytes; Value : Byte_Array)
Append Value in array order.
Parameters
- Target
Buffer extended by Value'Length bytes.
- Value
Bytes to copy.
Append_C_String
procedure Append_C_String
(Target : in out Flyology.Bytes.Unbounded_Bytes; Value : String)
Append String character codes followed by a zero terminator.
Parameters
- Target
Buffer to extend.
- Value
Text that must not contain NUL.
Raised exceptions
- Protocol_Error
Value contains NUL.
Append_U16
procedure Append_U16
(Target : in out Flyology.Bytes.Unbounded_Bytes; Value : UInt16)
Append Value in PostgreSQL network byte order.
Parameters
- Target
Buffer extended by two bytes.
- Value
Unsigned value to encode.
Append_U32
procedure Append_U32
(Target : in out Flyology.Bytes.Unbounded_Bytes; Value : UInt32)
Append Value in PostgreSQL network byte order.
Parameters
- Target
Buffer extended by four bytes.
- Value
Unsigned value to encode.
Backend_Message
type Backend_Message (Response : Backend_Message_Kind := Unknown_Response)
is private;
Strictly decoded backend response retaining its original message.
Record fields
- Response
Variant selected from the backend message tag.
Backend_Message_Kind
type Backend_Message_Kind is
(Row_Description_Response,
Data_Row_Response,
Command_Complete_Response,
Empty_Query_Response,
Error_Response,
Notice_Response,
Parameter_Status_Response,
Parse_Complete_Response,
…,
Unknown_Response);
Supported backend response classification.
Enumeration literals
- Row_Description_Response
Result-column metadata.
- Data_Row_Response
One row of nullable field values.
- Command_Complete_Response
Successful command tag.
- Empty_Query_Response
Empty simple query.
- Error_Response
Error diagnostic fields.
- Notice_Response
Asynchronous notice diagnostic fields.
- Parameter_Status_Response
Run-time parameter update.
- Parse_Complete_Response
Parse acknowledgement.
- Bind_Complete_Response
Bind acknowledgement.
- Close_Complete_Response
Close acknowledgement.
- Parameter_Description_Response
Prepared parameter type OIDs.
- No_Data_Response
Describe found no row metadata.
- Portal_Suspended_Response
Execute stopped at its row limit.
- Copy_In_Response
Server is ready to receive COPY data.
- Copy_Out_Response
Server will send COPY data.
- Copy_Both_Response
Bidirectional COPY begins.
- Copy_Data_Response
One backend COPY payload.
- Copy_Done_Response
Backend closes its COPY direction.
- Ready_For_Query_Response
Query cycle completed.
- Unknown_Response
Tag intentionally retained without typed decode.
Binary_Column
function Binary_Column (Value : Byte_Array) return Column_Value
Construct a non-null binary result column.
Parameters
- Value
Exact binary representation bytes.
Return value
Non-null column owning Value.
Binary_Parameter
function Binary_Parameter (Value : Byte_Array) return Bind_Parameter
Construct a non-null binary-format parameter.
Parameters
- Value
Exact type-specific binary bytes.
Return value
Non-null binary-format Bind parameter.
Bind_Parameter
type Bind_Parameter is private;
Owned Bind parameter preserving nullness, format, and exact bytes.
Bind_Parameter_Array
type Bind_Parameter_Array is
array (Positive range <>) of Bind_Parameter;
Bind parameters in prepared-statement order.
Byte
subtype Byte is Ada.Streams.Stream_Element;
One PostgreSQL wire octet.
Byte_Array
subtype Byte_Array is Ada.Streams.Stream_Element_Array;
Contiguous PostgreSQL wire octets.
Byte_Offset
subtype Byte_Offset is Ada.Streams.Stream_Element_Offset;
Index or cursor into a Byte_Array.
Code
function Code (Item : Message) return Character
Return a message's raw protocol tag.
Parameters
- Item
Message to inspect.
Return value
Its raw one-byte tag.
Column_At
function Column_At
(Item : Data_Row; Index : Positive) return Column_Value
Return one decoded column value by position.
Parameters
- Item
Row to inspect.
- Index
One-based column index.
Return value
Selected nullable column.
Raised exceptions
- Constraint_Error
Index exceeds Column_Count.
Column_Attribute_Number
function Column_Attribute_Number
(Item : Field_Description) return Int16
Return a result field's source attribute number.
Parameters
- Item
Field metadata.
Return value
Source table attribute number, or zero.
Column_Bytes
function Column_Bytes (Item : Column_Value) return Byte_Array
Copy a non-null result column's exact bytes.
Parameters
- Item
Non-null column to inspect.
Return value
Copy of its exact bytes.
Raised exceptions
- Protocol_Error
Item is null.
Column_Count
function Column_Count (Item : Data_Row) return Natural
Return the number of values in a decoded row.
Parameters
- Item
Row to inspect.
Return value
Number of columns.
Column_Text
function Column_Text (Item : Column_Value) return String
Interpret non-null bytes as character codes without transcoding.
Parameters
- Item
Non-null text-format column.
Return value
String with identical byte values.
Raised exceptions
- Protocol_Error
Item is null.
Column_Value
type Column_Value is private;
Owned nullable DataRow column bytes.
Column_Value_Array
type Column_Value_Array is array (Positive range <>) of Column_Value;
Column values in row order.
Completion_Tag
function Completion_Tag (Item : Backend_Message) return String
Return text carried by CommandComplete.
Parameters
- Item
Command_Complete_Response event.
Return value
PostgreSQL command tag.
Raised exceptions
- Protocol_Error
Item is another variant.
Copy_Bytes
function Copy_Bytes (Item : Frontend_Copy_Message) return Byte_Array
Copy the payload of a frontend CopyData message.
Parameters
- Item
Frontend_Copy_Data message.
Return value
Copy of its raw payload.
Raised exceptions
- Protocol_Error
Item is another variant.
Copy_Column_Count
function Copy_Column_Count
(Item : Copy_Format_Description) return Natural
Return the number of per-column COPY formats.
Parameters
- Item
COPY format metadata.
Return value
Number of per-column format entries.
Copy_Column_Format
function Copy_Column_Format
(Item : Copy_Format_Description; Index : Positive) return Field_Format
Return one column's COPY format.
Parameters
- Item
COPY format metadata.
- Index
One-based column index.
Return value
Format selected for that column.
Raised exceptions
- Constraint_Error
Index exceeds Copy_Column_Count.
Copy_Data
function Copy_Data (Item : Backend_Message) return Byte_Array
Copy bytes carried by a backend CopyData event.
Parameters
- Item
Copy_Data_Response event.
Return value
Copy of raw COPY payload bytes.
Raised exceptions
- Protocol_Error
Item is another variant.
Copy_Failure_Reason
function Copy_Failure_Reason (Item : Frontend_Copy_Message) return String
Return the reason carried by a frontend CopyFail message.
Parameters
- Item
Frontend_Copy_Fail message.
Return value
Client-supplied failure reason.
Raised exceptions
- Protocol_Error
Item is another variant.
Copy_Format_Description
type Copy_Format_Description is private;
COPY overall and per-column text/binary format metadata.
Copy_Formats
function Copy_Formats
(Item : Backend_Message) return Copy_Format_Description
Return formats carried by a COPY response.
Parameters
- Item
Copy_In, Copy_Out, or Copy_Both response.
Return value
Decoded COPY format metadata.
Raised exceptions
- Protocol_Error
Item is another variant.
Copy_Kind
function Copy_Kind
(Item : Frontend_Copy_Message) return Frontend_Copy_Kind
Return a decoded frontend COPY message's variant.
Parameters
- Item
Decoded frontend COPY message.
Return value
Its variant.
Data_Row
type Data_Row is private;
Owned ordered nullable columns decoded from DataRow.
Decode_Backend
function Decode_Backend (Item : Message) return Backend_Message
Decode supported backend payloads strictly while retaining Item. Unknown tags remain Unknown_Response without payload interpretation.
Parameters
- Item
Raw backend protocol message.
Return value
Typed owned backend event.
Raised exceptions
- Protocol_Error
A recognized payload is malformed.
Decode_Frontend_Copy
function Decode_Frontend_Copy
(Item : Message) return Frontend_Copy_Message
Decode and validate a CopyData, CopyDone, or CopyFail message.
Parameters
- Item
Raw frontend protocol message.
Return value
Typed COPY message.
Raised exceptions
- Protocol_Error
Item is another kind or malformed.
Decode_Initial
function Decode_Initial (Contents : Byte_Array) return Initial_Request
Strictly decode an untagged initial packet including its length field.
Parameters
- Contents
Complete packet bytes.
Return value
Classified owned initial request.
Raised exceptions
- Protocol_Error
Length or recognized contents are malformed.
Description
function Description (Item : Backend_Message) return Row_Description
Return metadata carried by RowDescription.
Parameters
- Item
Row_Description_Response event.
Return value
Decoded result-field metadata.
Raised exceptions
- Protocol_Error
Item is another variant.
Diagnostic
type Diagnostic is private;
Ordered ErrorResponse or NoticeResponse diagnostic fields.
Diagnostic_Data
function Diagnostic_Data (Item : Backend_Message) return Diagnostic
Return fields carried by ErrorResponse or NoticeResponse.
Parameters
- Item
Error_Response or Notice_Response event.
Return value
Decoded diagnostic fields.
Raised exceptions
- Protocol_Error
Item is another variant.
Diagnostic_Message
function Diagnostic_Message (Item : Diagnostic) return String
Return a diagnostic's primary human-readable message.
Parameters
- Item
Diagnostic to inspect.
Return value
Primary human-readable message, or empty when absent.
Diagnostic_SQL_State
function Diagnostic_SQL_State (Item : Diagnostic) return String
Return a diagnostic's SQLSTATE code.
Parameters
- Item
Diagnostic to inspect.
Return value
Five-character SQLSTATE, or empty when absent.
Encode
function Encode (Item : Message) return Byte_Array
Encode tag, length, and payload for transport.
Parameters
- Item
Message to serialize.
Return value
Complete PostgreSQL wire representation.
Encode_Cancel_Request
function Encode_Cancel_Request
(Process_Id : UInt32; Secret_Key : Byte_Array) return Byte_Array
Encode an out-of-band CancelRequest packet.
Parameters
- Process_Id
Target backend process identifier.
- Secret_Key
Exact backend cancellation secret, 4 through 256 bytes.
Return value
Complete untagged cancellation packet.
Raised exceptions
- Protocol_Error
Secret_Key is outside the supported range.
Encode_SSL_Request
function Encode_SSL_Request return Byte_Array
Encode the fixed PostgreSQL SSLRequest packet.
Return value
Complete eight-byte PostgreSQL SSLRequest packet.
Encode_Startup
function Encode_Startup
(User : String;
Database : String := "";
Application_Name : String := "flyology_postgres";
Protocol_Major : UInt16 := 3;
Protocol_Minor : UInt16 := 0;
Replication_Mode : Replication_Connection_Mode := Normal_Connection)
return Byte_Array
Encode a protocol-version-3 startup packet.
Parameters
- User
Required PostgreSQL role name.
- Database
Optional database name.
- Application_Name
Optional application_name value.
- Protocol_Major
Protocol major version, normally 3.
- Protocol_Minor
Protocol minor version.
- Replication_Mode
Optional replication startup parameter.
Return value
Complete untagged startup packet including length.
Raised exceptions
- Protocol_Error
A string contains NUL or exceeds size limits.
Field_At
function Field_At
(Item : Row_Description; Index : Positive) return Field_Description
Return one result field description by position.
Parameters
- Item
Row metadata to inspect.
- Index
One-based field index.
Return value
Metadata for the selected field.
Raised exceptions
- Constraint_Error
Index exceeds Field_Count.
Field_Count
function Field_Count (Item : Row_Description) return Natural
Return the number of described result fields.
Parameters
- Item
Row metadata to inspect.
Return value
Number of fields.
Field_Description
type Field_Description is private;
Metadata for one RowDescription field.
Field_Description_Array
type Field_Description_Array is
array (Positive range <>) of Field_Description;
Result field metadata in wire order.
Field_Format
type Field_Format is (Text_Format, Binary_Format);
PostgreSQL field representation code.
Enumeration literals
- Text_Format
Server's textual representation.
- Binary_Format
Type-specific binary representation.
Field_Format_Array
type Field_Format_Array is array (Positive range <>) of Field_Format;
Ordered parameter or result-column formats.
Field_Name
function Field_Name (Item : Field_Description) return String
Return a result field's label.
Parameters
- Item
Field metadata.
Return value
Column label.
Field_Text
function Field_Text
(Item : Diagnostic; Code : Character) return String
Look up a diagnostic field by its protocol code.
Parameters
- Item
Diagnostic fields to search.
- Code
PostgreSQL one-byte diagnostic field code.
Return value
First matching field text, or empty when absent.
Format
function Format (Item : Field_Description) return Field_Format
Return a result field's text or binary format.
Parameters
- Item
Field metadata.
Return value
Text or binary representation code.
Frontend_Copy_Kind
type Frontend_Copy_Kind is
(Frontend_Copy_Data, Frontend_Copy_Done, Frontend_Copy_Fail);
Frontend messages valid while COPY is active.
Enumeration literals
- Frontend_Copy_Data
One raw COPY payload.
- Frontend_Copy_Done
Client closes its COPY direction.
- Frontend_Copy_Fail
Client aborts COPY with a reason.
Frontend_Copy_Message
type Frontend_Copy_Message is private;
Strictly decoded frontend COPY message retaining its original bytes.
Frontend_Kind
type Frontend_Kind is
(Bind,
Close,
Copy_Data,
Copy_Done,
Copy_Fail,
Describe,
Execute,
Flush,
…,
Unknown);
Frontend message classification derived from the one-byte tag.
Enumeration literals
- Bind
Bind parameters to a portal.
- Close
Close a prepared statement or portal.
- Copy_Data
Transfer one COPY payload.
- Copy_Done
Finish one COPY direction.
- Copy_Fail
Abort COPY with a reason.
- Describe
Request statement or portal metadata.
- Execute
Execute a bound portal.
- Flush
Ask the backend to flush pending responses.
- Function_Call
Legacy function-call protocol message.
- Password_Or_SASL_Response
Authentication response message.
- Parse
Create a prepared statement.
- Query
Execute simple-query SQL text.
- Sync
End or recover an extended-query cycle.
- Terminate_Command
Close the frontend connection cleanly.
- Unknown
Tag not classified by this package.
Initial_Kind
type Initial_Kind is
(Startup, SSL_Request, GSS_Request, Cancel_Request, Unknown_Initial);
Untagged initial packet classification.
Enumeration literals
- Startup
Protocol version and startup parameters.
- SSL_Request
Request PostgreSQL SSLRequest negotiation.
- GSS_Request
Request GSSAPI encryption negotiation.
- Cancel_Request
Out-of-band query cancellation credentials.
- Unknown_Initial
Unknown special request code or startup version.
Initial_Request
type Initial_Request is private;
Owned decoded initial packet: startup, negotiation, or cancellation.
Int16
subtype Int16 is Interfaces.Integer_16;
Signed 16-bit wire integer.
Int32
subtype Int32 is Interfaces.Integer_32;
Signed 32-bit wire integer.
Is_Null
function Is_Null (Item : Bind_Parameter) return Boolean
Test whether a Bind parameter represents SQL NULL.
Parameters
- Item
Bind parameter to inspect.
Return value
True when Item represents SQL NULL.
Is_Null
function Is_Null (Item : Column_Value) return Boolean
Test whether a result column is SQL NULL.
Parameters
- Item
Column to inspect.
Return value
True when Item is SQL NULL.
Kind
function Kind (Item : Initial_Request) return Initial_Kind
Return a decoded initial packet's variant.
Parameters
- Item
Decoded initial request.
Return value
Its request variant.
Kind
function Kind (Item : Message) return Frontend_Kind
Classify a frontend message by its tag.
Parameters
- Item
Frontend message to classify by tag.
Return value
Known frontend kind or Unknown.
Make_Bind_Message
function Make_Bind_Message
(Portal_Name : String;
Statement_Name : String;
Parameters : Bind_Parameter_Array := No_Parameters;
Result_Formats : Field_Format_Array := No_Formats) return Message
Construct an extended-query Bind message.
Parameters
- Portal_Name
Empty for the unnamed portal, otherwise name.
- Statement_Name
Prepared statement to bind.
- Parameters
Values in statement parameter order.
- Result_Formats
Zero, one, or one-per-column format codes.
Return value
Encoded-payload Bind message.
Make_Close_Message
function Make_Close_Message
(Object_Type : Object_Kind; Name : String) return Message
Construct a Close message for a statement or portal.
Parameters
- Object_Type
Whether Name denotes a statement or portal.
- Name
Object name, empty for the unnamed object.
Return value
Close frontend message.
Make_Copy_Data_Message
function Make_Copy_Data_Message (Data : Byte_Array) return Message
Construct a frontend CopyData message.
Parameters
- Data
Raw COPY payload bytes.
Return value
CopyData frontend message owning Data.
Make_Copy_Done_Message
function Make_Copy_Done_Message return Message
Construct a frontend CopyDone message.
Return value
Empty CopyDone frontend message.
Make_Copy_Fail_Message
function Make_Copy_Fail_Message (Reason : String) return Message
Construct a frontend CopyFail message.
Parameters
- Reason
Human-readable COPY failure text.
Return value
CopyFail frontend message.
Make_Describe_Message
function Make_Describe_Message
(Object_Type : Object_Kind; Name : String) return Message
Construct a Describe message for a statement or portal.
Parameters
- Object_Type
Whether Name denotes a statement or portal.
- Name
Object name, empty for the unnamed object.
Return value
Describe frontend message.
Make_Empty_Message
function Make_Empty_Message (Code : Character) return Message
Construct a message without payload bytes.
Parameters
- Code
PostgreSQL one-byte message tag.
Return value
Message with an empty payload.
Make_Execute_Message
function Make_Execute_Message
(Portal_Name : String; Maximum_Rows : Row_Limit := 0) return Message
Construct an Execute message for a bound portal.
Parameters
- Portal_Name
Bound portal to execute.
- Maximum_Rows
Zero for all rows, otherwise suspension limit.
Return value
Execute frontend message.
Make_Field_Description
function Make_Field_Description
(Name : String;
Table_Oid : UInt32 := 0;
Column_Attribute_Number : Int16 := 0;
Type_Oid : UInt32 := 25;
Type_Size : Int16 := -1;
Type_Modifier : Int32 := -1;
Format : Field_Format := Text_Format)
return Field_Description
Construct metadata for one result column.
Parameters
- Name
Column label shown to the client.
- Table_Oid
Source table OID, or zero when not a table column.
- Column_Attribute_Number
Source attribute number, or zero.
- Type_Oid
PostgreSQL data type OID; defaults to text.
- Type_Size
Type width, or -1 for variable-width types.
- Type_Modifier
Type-specific modifier, or -1 when absent.
- Format
Requested text or binary representation.
Return value
Owned field description.
Make_Flush_Message
function Make_Flush_Message return Message
Construct a Flush message.
Return value
Empty Flush frontend message.
Make_Message
function Make_Message
(Code : Character; Payload : Byte_Array) return Message
Construct an owned message from a tag and payload.
Parameters
- Code
PostgreSQL one-byte message tag.
- Payload
Bytes after the encoded length.
Return value
Message owning a copy of Payload.
Raised exceptions
- Protocol_Error
The encoded message would exceed the limit.
Make_Parse_Message
function Make_Parse_Message
(Statement_Name : String;
SQL : String;
Parameter_Types : Oid_Array := No_Oids) return Message
Construct an extended-query Parse message.
Parameters
- Statement_Name
Empty for the unnamed statement, otherwise name.
- SQL
SQL text, possibly containing positional parameters.
- Parameter_Types
Zero or one type OID per SQL parameter.
Return value
Encoded-payload Parse message.
Make_Sync_Message
function Make_Sync_Message return Message
Construct a Sync message.
Return value
Empty Sync frontend message.
Maximum_Message_Size
Maximum_Message_Size : constant := Flyology.Postgres.Maximum_Message_Size;
Largest accepted complete wire message, including header bytes.
Message
type Message is private;
Owned tagged protocol message payload, excluding encoded length bytes.
No_Formats
No_Formats : constant Field_Format_Array (1 .. 0) :=
(others => Text_Format);
Empty format list selecting PostgreSQL's text defaults.
No_Oids
No_Oids : constant Oid_Array (1 .. 0) := (others => 0);
Empty OID list requesting server-side type inference.
No_Parameters
No_Parameters : constant Bind_Parameter_Array (1 .. 0);
Empty Bind parameter list.
Nonlocalized_Severity
function Nonlocalized_Severity (Item : Diagnostic) return String
Return the stable nonlocalized diagnostic severity.
Parameters
- Item
Diagnostic to inspect.
Return value
Nonlocalized severity field, or empty when absent.
Null_Column
Null_Column : constant Column_Value;
Reusable SQL NULL column value.
Null_Parameter
function Null_Parameter
(Format : Field_Format := Text_Format) return Bind_Parameter
Construct an SQL NULL parameter.
Parameters
- Format
Declared format code retained for the null parameter.
Return value
SQL NULL Bind parameter.
Object_Kind
type Object_Kind is (Statement_Object, Portal_Object);
Extended-query object selected by Describe or Close.
Enumeration literals
- Statement_Object
Prepared statement.
- Portal_Object
Bound portal.
Oid_Array
type Oid_Array is array (Positive range <>) of UInt32;
Ordered PostgreSQL object identifiers, typically parameter type OIDs.
Original_Message
function Original_Message (Item : Backend_Message) return Message
Return the raw message retained by a decoded backend event.
Parameters
- Item
Decoded backend event.
Return value
Owned original protocol message.
Original_Message
function Original_Message (Item : Frontend_Copy_Message) return Message
Return the raw message retained by a decoded frontend COPY event.
Parameters
- Item
Decoded frontend COPY message.
Return value
Owned original message.
Overall_Format
function Overall_Format
(Item : Copy_Format_Description) return Field_Format
Return the overall text or binary COPY format.
Parameters
- Item
COPY format metadata.
Return value
Overall COPY representation.
Parameter_Bytes
function Parameter_Bytes (Item : Bind_Parameter) return Byte_Array
Copy a non-null Bind parameter's exact bytes.
Parameters
- Item
Non-null Bind parameter to inspect.
Return value
Copy of its exact value bytes.
Raised exceptions
- Protocol_Error
Item is null.
Parameter_Count
function Parameter_Count (Item : Parameter_Description) return Natural
Return the number of prepared-statement parameters.
Parameters
- Item
Parameter metadata.
Return value
Number of parameter type OIDs.
Parameter_Data
function Parameter_Data (Item : Backend_Message) return Parameter_Status
Return the update carried by ParameterStatus.
Parameters
- Item
Parameter_Status_Response event.
Return value
Decoded parameter update.
Raised exceptions
- Protocol_Error
Item is another variant.
Parameter_Description
type Parameter_Description is private;
Ordered parameter type OIDs decoded from ParameterDescription.
Parameter_Format
function Parameter_Format (Item : Bind_Parameter) return Field_Format
Return a Bind parameter's representation format.
Parameters
- Item
Bind parameter to inspect.
Return value
Its text or binary format.
Parameter_Name
function Parameter_Name (Item : Parameter_Status) return String
Return an updated run-time parameter's name.
Parameters
- Item
Parameter update.
Return value
Parameter name.
Parameter_Status
type Parameter_Status is private;
One owned ParameterStatus name/value update.
Parameter_Type_At
function Parameter_Type_At
(Item : Parameter_Description; Index : Positive) return UInt32
Return one prepared parameter's PostgreSQL type OID.
Parameters
- Item
Parameter metadata.
- Index
One-based parameter index.
Return value
PostgreSQL type OID for the parameter.
Raised exceptions
- Constraint_Error
Index exceeds Parameter_Count.
Parameter_Types
function Parameter_Types
(Item : Backend_Message) return Parameter_Description
Return type OIDs carried by ParameterDescription.
Parameters
- Item
Parameter_Description_Response event.
Return value
Decoded parameter OIDs.
Raised exceptions
- Protocol_Error
Item is another variant.
Parameter_Value
function Parameter_Value (Item : Parameter_Status) return String
Return an updated run-time parameter's value.
Parameters
- Item
Parameter update.
Return value
Current parameter value.
Payload
function Payload (Item : Message) return Byte_Array
Copy a message's payload.
Parameters
- Item
Message to inspect.
Return value
Copy of its payload bytes.
Payload_Length
function Payload_Length (Item : Message) return Natural
Return a message's payload size.
Parameters
- Item
Message to inspect.
Return value
Number of bytes after the encoded length.
Process_Id
function Process_Id (Item : Initial_Request) return UInt32
Return the process identifier carried by CancelRequest.
Parameters
- Item
Cancel_Request.
Return value
Target backend process identifier.
Raised exceptions
- Protocol_Error
Item is not Cancel_Request.
Protocol_Error
Protocol_Error : exception;
Raised for malformed, oversized, inconsistent, or mis-typed messages.
Read_C_String
function Read_C_String
(Source : Byte_Array; Cursor : in out Byte_Offset) return String
Read bytes through the next zero terminator and advance Cursor.
Parameters
- Source
Buffer being decoded.
- Cursor
First text byte; advanced past the terminator.
Return value
String containing bytes before the terminator.
Raised exceptions
- Protocol_Error
No terminator remains in Source.
Read_U16
function Read_U16
(Source : Byte_Array; Cursor : in out Byte_Offset) return UInt16
Read one network-order unsigned 16-bit integer and advance Cursor.
Parameters
- Source
Buffer being decoded.
- Cursor
Position of the first byte; advanced by two.
Return value
Decoded value.
Raised exceptions
- Protocol_Error
Fewer than two bytes remain.
Read_U32
function Read_U32
(Source : Byte_Array; Cursor : in out Byte_Offset) return UInt32
Read one network-order unsigned 32-bit integer and advance Cursor.
Parameters
- Source
Buffer being decoded.
- Cursor
Position of the first byte; advanced by four.
Return value
Decoded value.
Raised exceptions
- Protocol_Error
Fewer than four bytes remain.
Replication_Connection_Mode
type Replication_Connection_Mode is
(Normal_Connection,
Physical_Replication_Connection,
Logical_Replication_Connection);
Startup replication parameter selection.
Enumeration literals
- Normal_Connection
Ordinary SQL connection with no parameter.
- Physical_Replication_Connection
Physical mode using
true.- Logical_Replication_Connection
Database-capable mode using
database.
Response_Kind
function Response_Kind (Item : Backend_Message) return Backend_Message_Kind
Return a decoded backend event's variant.
Parameters
- Item
Backend event.
Return value
Its response variant.
Row_Data
function Row_Data (Item : Backend_Message) return Data_Row
Return columns carried by DataRow.
Parameters
- Item
Data_Row_Response event.
Return value
Decoded nullable row columns.
Raised exceptions
- Protocol_Error
Item is another variant.
Row_Description
type Row_Description is private;
Owned ordered field metadata decoded from RowDescription.
Row_Limit
subtype Row_Limit is Int32 range 0 .. Int32'Last;
Execute row limit; zero requests all rows.
Secret_Key
function Secret_Key (Item : Initial_Request) return Byte_Array
Copy the secret carried by CancelRequest.
Parameters
- Item
Cancel_Request.
Return value
Copy of target backend cancellation secret bytes.
Raised exceptions
- Protocol_Error
Item is not Cancel_Request.
Severity
function Severity (Item : Diagnostic) return String
Return the localized diagnostic severity.
Parameters
- Item
Diagnostic to inspect.
Return value
Localized severity field, or empty when absent.
Startup_Data
function Startup_Data
(Item : Initial_Request) return Startup_Information
Return fields carried by a startup packet.
Parameters
- Item
Startup request.
Return value
Decoded supported startup fields.
Raised exceptions
- Protocol_Error
Item is not Startup.
Startup_Information
type Startup_Information is record
Protocol_Major : UInt16 := 3;
Protocol_Minor : UInt16 := 0;
User : Ada.Strings.Unbounded.Unbounded_String;
Database : Ada.Strings.Unbounded.Unbounded_String;
Application_Name : Ada.Strings.Unbounded.Unbounded_String;
Replication_Mode : Replication_Connection_Mode := Normal_Connection;
end record;
Supported fields decoded from a version-3 startup packet.
Record fields
- Protocol_Major
Protocol major version, normally 3.
- Protocol_Minor
Protocol minor version.
- User
Required PostgreSQL role name.
- Database
Optional database name.
- Application_Name
Optional client application name.
- Replication_Mode
Decoded replication startup parameter.
Table_Oid
function Table_Oid (Item : Field_Description) return UInt32
Return a result field's source table OID.
Parameters
- Item
Field metadata.
Return value
Source table OID, or zero.
Text_Column
function Text_Column (Value : String) return Column_Value
Construct a non-null text result column.
Parameters
- Value
Exact text representation bytes.
Return value
Non-null column containing Value.
Text_Parameter
function Text_Parameter (Value : String) return Bind_Parameter
Construct a non-null text-format parameter.
Parameters
- Value
Exact text bytes, without a terminating zero.
Return value
Non-null text-format Bind parameter.
Transaction_State
function Transaction_State
(Item : Backend_Message) return Transaction_Status
Return the status carried by ReadyForQuery.
Parameters
- Item
Ready_For_Query_Response event.
Return value
Decoded transaction state.
Raised exceptions
- Protocol_Error
Item is another variant.
Transaction_Status
type Transaction_Status is
(Idle, In_Transaction, Failed_Transaction);
ReadyForQuery transaction state.
Enumeration literals
- Idle
Not inside an explicit transaction block.
- In_Transaction
Inside a valid transaction block.
- Failed_Transaction
Transaction block is aborted until rollback.
Type_Modifier
function Type_Modifier (Item : Field_Description) return Int32
Return a result field's type-specific modifier.
Parameters
- Item
Field metadata.
Return value
Type-specific modifier, or -1.
Type_Oid
function Type_Oid (Item : Field_Description) return UInt32
Return a result field's PostgreSQL type OID.
Parameters
- Item
Field metadata.
Return value
PostgreSQL data type OID.
Type_Size
function Type_Size (Item : Field_Description) return Int16
Return a result field's declared type width.
Parameters
- Item
Field metadata.
Return value
Type width, or -1 for variable width.
UInt16
subtype UInt16 is Interfaces.Unsigned_16;
Unsigned 16-bit wire integer.
UInt32
subtype UInt32 is Interfaces.Unsigned_32;
Unsigned 32-bit wire integer.