Description
Stateful PostgreSQL frontend implementing startup, authentication, simple and extended queries, COPY, cancellation, and TLS negotiation.
Abort_Copy
procedure Abort_Copy
(Item : in out Session;
Reason : String;
Timeout : Duration := 30.0)
Abort COPY IN by sending CopyFail with a diagnostic reason.
Parameters
- Item
Session whose copy send direction is open.
- Reason
Human-readable failure text sent to the server.
- Timeout
Maximum time allowed for the write.
Backend_Process_Id
function Backend_Process_Id (Item : Session) return Protocol.UInt32
Return the process identifier received in BackendKeyData.
Parameters
- Item
Authenticated session.
Return value
Server process identifier used for cancellation.
Backend_Secret_Key
function Backend_Secret_Key (Item : Session) return Protocol.Byte_Array
Return a copy of the secret received in BackendKeyData.
Parameters
- Item
Authenticated session.
Return value
Cancellation secret bytes; callers should avoid logging them.
Bind_Portal
procedure Bind_Portal
(Item : in out Session;
Portal_Name : String;
Statement_Name : String;
Parameters : Protocol.Bind_Parameter_Array :=
Protocol.No_Parameters;
Result_Formats : Protocol.Field_Format_Array := Protocol.No_Formats;
Timeout : Duration := 30.0)
Bind parameters and result formats to a portal.
Parameters
- Item
Session in an extended-query cycle.
- Portal_Name
Empty for the unnamed portal, otherwise name.
- Statement_Name
Prepared statement to bind.
- Parameters
Parameter values in statement order.
- Result_Formats
Zero, one, or one-per-column format codes.
- Timeout
Maximum time allowed for the write.
Client_Operation
type Client_Operation is
abstract new Flyology.Operations.Operation with private;
Common limited base for scoped PostgreSQL client operations.
Close_Portal
procedure Close_Portal
(Item : in out Session;
Portal_Name : String;
Timeout : Duration := 30.0)
Close a bound portal in the current extended-query cycle.
Parameters
- Item
Session in an extended-query cycle.
- Portal_Name
Portal to close.
- Timeout
Maximum time allowed for the write.
Close_Statement
procedure Close_Statement
(Item : in out Session;
Statement_Name : String;
Timeout : Duration := 30.0)
Close a prepared statement in the current extended-query cycle.
Parameters
- Item
Session in an extended-query cycle.
- Statement_Name
Prepared statement to close.
- Timeout
Maximum time allowed for the write.
Copy_Event
subtype Copy_Event is Protocol.Backend_Message;
Typed backend event produced while COPY is active or completing.
Database_Error
Database_Error : exception;
Raised when the server returns an ErrorResponse for an operation.
Describe_Portal
procedure Describe_Portal
(Item : in out Session;
Portal_Name : String;
Timeout : Duration := 30.0)
Request row metadata for a bound portal.
Parameters
- Item
Session in an extended-query cycle.
- Portal_Name
Portal to describe.
- Timeout
Maximum time allowed for the write.
Describe_Statement
procedure Describe_Statement
(Item : in out Session;
Statement_Name : String;
Timeout : Duration := 30.0)
Request parameter and row metadata for a prepared statement.
Parameters
- Item
Session in an extended-query cycle.
- Statement_Name
Prepared statement to describe.
- Timeout
Maximum time allowed for the write.
Enter_Pipeline_Mode
procedure Enter_Pipeline_Mode (Item : in out Session)
Allow several Sync-terminated extended-query batches to be outstanding at once. Outside pipeline mode the session must consume ReadyForQuery before it writes the next command. In pipeline mode it can write the next batch immediately after Synchronize, and each ReadyForQuery then ends exactly one batch in the order the batches were written. Simple queries are rejected while the mode is active. A COPY response is rejected too, and that rejection is terminal: the response is already consumed and the server is already streaming, so the session closes and its transport must be discarded. A session that writes a long pipeline without receiving can block once both peers fill their socket buffers, so interleave Receive_Extended_Event with the writes. The call does nothing when the mode is already active.
Parameters
- Item
Ready session with no outstanding synchronization.
Raised exceptions
- Program_Error
Item is not in the Ready state.
Error_Message
function Error_Message (Value : Protocol.Message) return String
Extract the human-readable primary text from ErrorResponse.
Parameters
- Value
Backend ErrorResponse message.
Return value
Message field, or an empty string when absent.
Execute_Portal
function Execute_Portal
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Session;
Portal_Name : String;
Maximum_Rows : Protocol.Row_Limit := 0;
Timeout : Duration := 30.0) return Send_Operation
Start a portal execute send without waiting.
Parameters
- Set
- Item
- Portal_Name
- Maximum_Rows
- Timeout
Return value
Execute_Portal
procedure Execute_Portal
(Item : in out Session;
Portal_Name : String;
Maximum_Rows : Protocol.Row_Limit := 0;
Timeout : Duration := 30.0)
Execute a portal for at most Maximum_Rows rows.
Parameters
- Item
Session in an extended-query cycle.
- Portal_Name
Bound portal to execute.
- Maximum_Rows
Zero for all rows, otherwise a suspension limit.
- Timeout
Maximum time allowed for the write.
Execute_Portal
procedure Execute_Portal
(Item : not null access Session;
Portal_Name : String;
Maximum_Rows : Protocol.Row_Limit := 0;
Timeout : Duration := 30.0;
Operation : in out Send_Operation)
Start or restart a portal execute send.
Parameters
- Item
- Portal_Name
- Maximum_Rows
- Timeout
- Operation
Exit_Pipeline_Mode
procedure Exit_Pipeline_Mode (Item : in out Session)
Return the session to one extended-query batch at a time. Every written batch must already have produced its ReadyForQuery. The call does nothing when the mode is not active.
Parameters
- Item
Ready session with no outstanding synchronization.
Raised exceptions
- Program_Error
A written batch is still outstanding.
Extended_Query_Event
subtype Extended_Query_Event is Protocol.Backend_Message;
Typed backend event produced during an extended-query cycle.
Finish
procedure Finish
(Operation : in out Receive_Operation;
Event : out Protocol.Backend_Message)
Consume a terminal receive, transferring its retained owned event or raising its retained familiar exception.
Parameters
- Operation
- Event
Finish
procedure Finish (Operation : in out Send_Operation)
Consume a terminal send and raise any retained familiar transport or protocol exception.
Parameters
- Operation
Finish
procedure Finish (Operation : in out Startup_Operation)
Consume a terminal startup stage and raise its retained familiar error.
Parameters
- Operation
Finish_Copy
procedure Finish_Copy
(Item : in out Session; Timeout : Duration := 30.0)
Finish the client-to-server COPY direction with CopyDone.
Parameters
- Item
Session whose copy send direction is open.
- Timeout
Maximum time allowed for the write.
Flush
procedure Flush
(Item : in out Session; Timeout : Duration := 30.0)
Ask the server to flush pending extended-query responses immediately.
Parameters
- Item
Session in an extended-query cycle.
- Timeout
Maximum time allowed for the write.
In_Pipeline_Mode
function In_Pipeline_Mode (Item : Session) return Boolean
Report whether pipeline mode is active.
Parameters
- Item
Session to inspect.
Return value
True after Enter_Pipeline_Mode until Exit_Pipeline_Mode.
Is_Ready
function Is_Ready (Item : Session) return Boolean
Test whether Item may begin a new command cycle.
Parameters
- Item
Session to inspect.
Return value
True exactly when State (Item) is Ready.
Negotiate_TLS
function Negotiate_TLS
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Session;
Timeout : Duration := 30.0) return Startup_Operation
Send SSLRequest and receive the one-byte acceptance response. Finish leaves Item in TLS_Negotiated; upgrade the same transport before calling Startup.
Parameters
- Set
- Item
- Timeout
Return value
Negotiate_TLS
procedure Negotiate_TLS
(Item : not null access Session;
Timeout : Duration := 30.0;
Operation : in out Startup_Operation)
Start or restart SSLRequest negotiation.
Parameters
- Item
- Timeout
- Operation
Operation_State
type Operation_State is
(Not_Started,
TLS_Negotiated,
Ready,
Simple_Query_Active,
Extended_Query_Active,
Copy_In_Active,
Copy_Out_Active,
Copy_Both_Active,
…,
Closed);
Client protocol state controlling which operations are currently legal.
Enumeration literals
- Not_Started
No startup packet has been sent.
- TLS_Negotiated
SSLRequest was accepted; the caller must upgrade the same transport before starting authentication.
- Ready
Startup or synchronization completed; commands may begin.
- Simple_Query_Active
A simple-query response is being consumed.
- Extended_Query_Active
An extended-query batch is being written; in pipeline mode earlier batches can still be outstanding.
- Copy_In_Active
Client-to-server COPY data may be sent.
- Copy_Out_Active
Server-to-client COPY data is being received.
- Copy_Both_Active
Bidirectional COPY data may be exchanged.
- Copy_Completion_Active
COPY completion responses remain pending.
- Recovery_Required
An extended-query error requires Synchronize.
- Awaiting_Ready
A terminal response is pending ReadyForQuery and no later pipelined batch has begun.
- Closed
The server or client has terminated the session.
Pending_Synchronizations
function Pending_Synchronizations (Item : Session) return Natural
Count the Sync messages written whose ReadyForQuery has not arrived.
Parameters
- Item
Session to inspect.
Return value
Number of written batches whose responses remain unconsumed.
Prepare_Statement
procedure Prepare_Statement
(Item : in out Session;
Statement_Name : String;
SQL : String;
Parameter_Types : Protocol.Oid_Array := Protocol.No_Oids;
Timeout : Duration := 30.0)
Send Parse for a named or unnamed prepared statement.
Parameters
- Item
Ready session beginning an extended-query cycle.
- Statement_Name
Empty for the unnamed statement, otherwise name.
- SQL
SQL text containing positional parameters when required.
- Parameter_Types
Optional explicit type OIDs for parameters.
- Timeout
Maximum time allowed for the write.
Receive_Copy_Event
function Receive_Copy_Event
(Item : in out Session;
Timeout : Duration := 30.0;
On_Wait : access Transports.Wait_Observer'Class := null)
return Copy_Event
Receive one event while COPY is active or completing.
Parameters
- Item
Session in a COPY-related state.
- Timeout
Maximum time allowed for the complete event.
- On_Wait
Observer notified while the event is still arriving. A replication stream needs this: a primary packs pending WAL into a single XLogData of up to 128 kB, and a standby that stays silent for the whole of it is terminated once assembly outlasts wal_sender_timeout. The observer may send on Item's channel.
Return value
Next typed COPY or completion event.
Receive_Extended_Event
function Receive_Extended_Event
(Item : in out Session; Timeout : Duration := 30.0)
return Extended_Query_Event
Receive and validate one extended-query response event. In pipeline mode each ReadyForQuery ends one batch, in the order the batches were written. A portal executed without Describe_Portal or Describe_Statement returns rows with no RowDescription, which is accepted; the column count is checked only against a description the server actually sent.
Parameters
- Item
Session in an extended-query or recovery state.
- Timeout
Maximum time allowed for the complete event.
Return value
Next typed event, updating Item's protocol state.
Receive_Extended_Event
function Receive_Extended_Event
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Session;
Timeout : Duration := 30.0) return Receive_Operation
Start receiving one owned extended-query event without waiting.
Parameters
- Set
- Item
- Timeout
Return value
Receive_Extended_Event
procedure Receive_Extended_Event
(Item : not null access Session;
Timeout : Duration := 30.0;
Operation : in out Receive_Operation)
Start or restart one extended-query event receive.
Parameters
- Item
- Timeout
- Operation
Receive_Message
function Receive_Message
(Item : in out Session; Timeout : Duration := 30.0)
return Protocol.Message
Receive one raw backend message without interpreting query sequencing.
Parameters
- Item
Started session to read.
- Timeout
Maximum time allowed for the complete message.
Return value
Next complete backend protocol message.
Receive_Operation
type Receive_Operation is new Client_Operation with private;
Limited scoped receive retaining one owned typed query event until Finish. Protocol payload allocation is result storage, not wait state.
Receive_Query_Event
function Receive_Query_Event
(Item : in out Session; Timeout : Duration := 30.0)
return Simple_Query_Event
Receive one owned event for the active simple query. Continue until Ready_For_Query_Response; rows are not accumulated by the session.
Parameters
- Item
Session in Simple_Query_Active or Awaiting_Ready state.
- Timeout
Maximum time allowed for the complete event.
Return value
Next typed simple-query event.
Receive_Query_Event
function Receive_Query_Event
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Session;
Timeout : Duration := 30.0) return Receive_Operation
Start receiving one owned simple-query event without waiting.
Parameters
- Set
- Item
- Timeout
Return value
Receive_Query_Event
procedure Receive_Query_Event
(Item : not null access Session;
Timeout : Duration := 30.0;
Operation : in out Receive_Operation)
Start or restart one simple-query event receive.
Parameters
- Item
- Timeout
- Operation
Resume_Portal
procedure Resume_Portal
(Item : in out Session;
Portal_Name : String;
Maximum_Rows : Protocol.Row_Limit := 0;
Timeout : Duration := 30.0)
Continue a portal after PortalSuspended. Sync ends the batch that owns the portal, so only a batch whose responses arrive through Flush can be resumed.
Parameters
- Item
Session with a suspended portal in the current cycle.
- Portal_Name
Suspended portal to continue.
- Maximum_Rows
Zero for all remaining rows, otherwise a new limit.
- Timeout
Maximum time allowed for the write.
Send_Cancel_Request
procedure Send_Cancel_Request
(Item : Session;
Cancellation_Channel : in out Transports.Transport'Class;
Timeout : Duration := 30.0)
Send Item's cancellation credentials on a caller-opened distinct transport. The server replies only by closing that transport; callers close it after return and continue reading the active query session.
Parameters
- Item
Active session whose stored backend credentials are used.
- Cancellation_Channel
Separate connection to the same server.
- Timeout
Maximum time allowed to send the cancellation packet.
Send_Command
procedure Send_Command
(Item : in out Session;
Command : Protocol.Message;
Timeout : Duration := 30.0)
Send an already encoded frontend message and update Item's state for recognized query, extended-query, COPY, synchronization, or termination tags.
Parameters
- Item
Started session to write.
- Command
Complete frontend protocol message.
- Timeout
Maximum time allowed for the write.
Send_Copy_Data
procedure Send_Copy_Data
(Item : in out Session;
Data : Protocol.Byte_Array;
Timeout : Duration := 30.0)
Send one CopyData payload during COPY IN or COPY BOTH.
Parameters
- Item
Session whose copy send direction is open.
- Data
Raw COPY payload bytes.
- Timeout
Maximum time allowed for the write.
Send_Operation
type Send_Operation is new Client_Operation with private;
Limited scoped send for a PostgreSQL query or execute request. Item and its operation-capable transport remain borrowed until Finish or finalization.
Send_Query
function Send_Query
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Session;
SQL : String;
Timeout : Duration := 30.0) return Send_Operation
Start a simple-query send without waiting.
Parameters
- Set
- Item
- SQL
- Timeout
Return value
Send_Query
procedure Send_Query
(Item : in out Session; SQL : String; Timeout : Duration := 30.0)
Start a simple-query cycle for SQL. Pipeline mode rejects the call because a simple query has no Sync boundary of its own.
Parameters
- Item
Ready session, transitioned to Simple_Query_Active.
- SQL
One or more SQL statements encoded as a Query message.
- Timeout
Maximum time allowed for the write.
Send_Query
procedure Send_Query
(Item : not null access Session;
SQL : String;
Timeout : Duration := 30.0;
Operation : in out Send_Operation)
Start or restart a simple-query send in a reusable operation.
Parameters
- Item
- SQL
- Timeout
- Operation
Session
type Session
(Channel : not null access Transports.Transport'Class) is limited private;
One stateful PostgreSQL connection over a caller-owned transport.
Record fields
- Channel
Open transport whose lifetime exceeds the session.
Simple_Query_Event
subtype Simple_Query_Event is Protocol.Backend_Message;
Typed backend event produced while consuming a simple-query cycle.
SQL_State
function SQL_State (Value : Protocol.Message) return String
Extract the five-character SQLSTATE from ErrorResponse.
Parameters
- Value
Backend ErrorResponse message.
Return value
SQLSTATE field, or an empty string when absent.
Startup
function Startup
(Set : not null access
Flyology.Operations.Completion_Set'Class;
Item : not null access Session;
User : String;
Database : String := "";
Password : String := "";
Application_Name : String := "flyology_postgres";
Timeout : Duration := 30.0;
Replication_Mode : Protocol.Replication_Connection_Mode :=
Protocol.Normal_Connection) return Startup_Operation
Start PostgreSQL startup and authentication without waiting. One deadline spans the complete startup sequence.
Parameters
- Set
- Item
- User
- Database
- Password
- Application_Name
- Timeout
- Replication_Mode
Return value
Startup
procedure Startup
(Item : in out Session;
User : String;
Database : String := "";
Password : String := "";
Application_Name : String := "flyology_postgres";
Timeout : Duration := 30.0;
Replication_Mode : Protocol.Replication_Connection_Mode :=
Protocol.Normal_Connection)
Perform plaintext PostgreSQL startup and complete authentication. Password is consumed as exact String octets; no SASLprep or Unicode normalization is performed.
Parameters
- Item
Password is consumed as its exact String octets. No SASLprep or Unicode normalization is performed by this library.
New session in Not_Started state.
- User
Password is consumed as its exact String octets. No SASLprep or Unicode normalization is performed by this library.
PostgreSQL role name sent in the startup packet.
- Database
Password is consumed as its exact String octets. No SASLprep or Unicode normalization is performed by this library.
Database name, or empty to let the server choose.
- Password
Credential used by cleartext or SCRAM authentication.
- Application_Name
Value reported to the server for observability.
- Timeout
Per-message startup and authentication timeout.
- Replication_Mode
Normal, database replication, or true replication startup parameter.
Raised exceptions
- Database_Error
The server rejects startup or authentication.
- Unsupported_Authentication
The requested method is unknown.
Startup
procedure Startup
(Item : not null access Session;
User : String;
Database : String := "";
Password : String := "";
Application_Name : String := "flyology_postgres";
Timeout : Duration := 30.0;
Replication_Mode : Protocol.Replication_Connection_Mode :=
Protocol.Normal_Connection;
Operation : in out Startup_Operation)
Start or restart startup/authentication in a reusable operation.
Parameters
- Item
- User
- Database
- Password
- Application_Name
- Timeout
- Replication_Mode
- Operation
Startup_Operation
type Startup_Operation is new Client_Operation with private;
Limited scoped PostgreSQL SSL negotiation or startup/authentication operation. Credential and protocol state are owned until Finish.
Startup_TLS
procedure Startup_TLS
(Item : in out Session;
Backend : in out Flyology.IO.TLS.Provider'Class;
Server_Name : String;
User : String;
Database : String := "";
Password : String := "";
Application_Name : String := "flyology_postgres";
Timeout : Duration := 30.0;
Replication_Mode : Protocol.Replication_Connection_Mode :=
Protocol.Normal_Connection)
Require SSLRequest negotiation, then perform startup over verified TLS. Refusal is terminal and never falls back to plaintext; PostgreSQL's separate sslnegotiation=direct mode is not supported.
Parameters
- Item
New session over a TLS-upgradable transport.
- Backend
TLS implementation and trust configuration to use.
- Server_Name
DNS name checked during certificate verification.
- User
PostgreSQL role name sent in the startup packet.
- Database
Database name, or empty to let the server choose.
- Password
Exact credential octets; no SASLprep is performed.
- Application_Name
Value reported to the server for observability.
- Timeout
Per-message negotiation and startup timeout.
- Replication_Mode
Requested connection mode.
Raised exceptions
- TLS_Not_Available
SSLRequest is refused or TLS fails.
- Database_Error
The server rejects startup or authentication.
State
function State (Item : Session) return Operation_State
Return Item's current protocol state.
Parameters
- Item
Session to inspect.
Return value
Current operation state.
Synchronize
procedure Synchronize
(Item : in out Session; Timeout : Duration := 30.0)
End or recover an extended-query cycle by sending Sync. In pipeline mode Sync closes the current batch and the next command opens the following one, so the session does not wait for ReadyForQuery first.
Parameters
- Item
Active or recovery-required extended-query session.
- Timeout
Maximum time allowed for the write.
TLS_Not_Available
TLS_Not_Available : exception;
Raised when SSLRequest is refused or TLS cannot be negotiated.
Unsupported_Authentication
Unsupported_Authentication : exception;
Raised when the server requests an unsupported authentication method.