Skip to content

Session

[Source]

The main entry point for interacting with a PostgreSQL server. Manages the connection lifecycle — connecting, authenticating, executing queries, and shutting down — as a state machine.

Create a session with ServerConnectInfo and DatabaseConnectInfo. Connection and authentication events are delivered to a SessionStatusNotify receiver.

Query execution is serialized: only one operation is in flight at a time. Additional calls to execute, prepare, copy_in, copy_out, stream, or pipeline are queued and dispatched in order. Within a pipeline call, multiple queries are sent to the server in a single write and processed sequentially, reducing round-trip latency.

An optional connection timeout can be set via ServerConnectInfo. If the TCP connection is not established within the given duration, pg_session_connection_failed is called with ConnectionFailedTimeout.

Most operations accept an optional statement_timeout parameter. When provided, the driver automatically sends a CancelRequest if the operation does not complete within the given duration. Construct the timeout with lori.MakeTimerDuration(milliseconds).

actor tag Session is
  TCPConnectionActor tag,
  ClientLifecycleEventReceiver ref

Implements

Constructors

create

[Source]

new tag create(
  server_connect_info': ServerConnectInfo val,
  database_connect_info': DatabaseConnectInfo val,
  notify': SessionStatusNotify tag,
  registry: CodecRegistry val = reference)
: Session tag^

Parameters

Returns

Public fields

var state: _SessionState ref

[Source]

Public Behaviours

execute

[Source]

Execute a query. If statement_timeout is provided, the query will be cancelled via CancelRequest if it does not complete within the given duration.

be execute(
  query: Query,
  receiver: ResultReceiver tag,
  statement_timeout: (TimerDuration | None val) = reference)

Parameters

prepare

[Source]

Prepare a named server-side statement. The SQL string must contain a single statement. On success, receiver.pg_statement_prepared(session, name) is called. The statement can then be executed with NamedPreparedQuery(name, params). If statement_timeout is provided, the prepare will be cancelled if it does not complete within the given duration.

be prepare(
  name: String val,
  sql: String val,
  receiver: PrepareReceiver tag,
  statement_timeout: (TimerDuration | None val) = reference)

Parameters

close_statement

[Source]

Close (destroy) a named prepared statement on the server. Fire-and-forget: no callback is issued. It is not an error to close a nonexistent statement.

be close_statement(
  name: String val)

Parameters

cancel

[Source]

Request cancellation of the currently executing query. Opens a separate TCP connection to send a PostgreSQL CancelRequest. Cancellation is best-effort — the server may or may not honor it. If cancelled, the query's ResultReceiver receives pg_query_failed with an ErrorResponse (SQLSTATE 57014). Queued queries are not affected.

Safe to call in any session state. No-op if no query is in flight.

be cancel()

copy_in

[Source]

Start a COPY ... FROM STDIN operation. The SQL string should be a COPY command with FROM STDIN. On success, the receiver's pg_copy_ready() is called, and the caller should then send data via send_copy_data(), finishing with finish_copy() or abort_copy(). If statement_timeout is provided, the entire COPY operation (including client data transfer) will be cancelled if it does not complete within the given duration.

be copy_in(
  sql: String val,
  receiver: CopyInReceiver tag,
  statement_timeout: (TimerDuration | None val) = reference)

Parameters

send_copy_data

[Source]

Send a chunk of data to the server during a COPY IN operation. Data does not need to align with row boundaries — the server reassembles the stream. No-op if not in COPY IN mode.

be send_copy_data(
  data: Array[U8 val] val)

Parameters

finish_copy

[Source]

Signal successful completion of the COPY data stream. The server will validate the data and respond with pg_copy_complete() or pg_copy_failed(). No-op if not in COPY IN mode.

be finish_copy()

abort_copy

[Source]

Abort the COPY operation with the given error message. The server will respond with pg_copy_failed(). No-op if not in COPY IN mode.

be abort_copy(
  reason: String val)

Parameters

copy_out

[Source]

Start a COPY ... TO STDOUT operation. The SQL string should be a COPY command with TO STDOUT. Data arrives via the receiver's pg_copy_data() callback. The operation completes with pg_copy_complete() or fails with pg_copy_failed(). If statement_timeout is provided, the COPY operation will be cancelled if it does not complete within the given duration.

be copy_out(
  sql: String val,
  receiver: CopyOutReceiver tag,
  statement_timeout: (TimerDuration | None val) = reference)

Parameters

stream

[Source]

Start a streaming query that delivers rows in windowed batches via StreamingResultReceiver. Each batch contains up to window_size rows. Call fetch_more() from pg_stream_batch to pull the next batch, or close_stream() to end early.

Only PreparedQuery and NamedPreparedQuery are supported — streaming uses the extended query protocol's Execute(max_rows) + PortalSuspended mechanism which requires a prepared statement.

If statement_timeout is provided, the entire streaming operation (from initial Execute to final ReadyForQuery) will be cancelled if it does not complete within the given duration.

be stream(
  query: (PreparedQuery val | NamedPreparedQuery val),
  window_size: U32 val,
  receiver: StreamingResultReceiver tag,
  statement_timeout: (TimerDuration | None val) = reference)

Parameters

fetch_more

[Source]

Request the next batch of rows during a streaming query. The next pg_stream_batch callback delivers the rows. Safe to call at any time — no-op if no streaming query is active, if the stream has already completed naturally, or if the stream has already failed.

be fetch_more()

close_stream

[Source]

End a streaming query early. The pg_stream_complete callback fires when the server acknowledges the close. Safe to call at any time — no-op if no streaming query is active, if the stream has already completed naturally, or if the stream has already failed.

be close_stream()

pipeline

[Source]

Execute multiple queries in a single pipeline. All queries are sent to the server in one TCP write and processed in order, reducing round-trip latency from N round trips to 1. Each query has its own Sync boundary for error isolation — if one query fails, subsequent queries continue executing.

Results are delivered via PipelineReceiver with an index corresponding to each query's position in the array. pg_pipeline_complete always fires last. Only PreparedQuery and NamedPreparedQuery are supported — pipelining uses the extended query protocol.

If statement_timeout is provided, the entire pipeline will be cancelled if it does not complete within the given duration.

be pipeline(
  queries: Array[(PreparedQuery val | NamedPreparedQuery val)] val,
  receiver: PipelineReceiver tag,
  statement_timeout: (TimerDuration | None val) = reference)

Parameters

close

[Source]

Close the connection. Sends a Terminate message to the server before closing the TCP connection. Does not wait for outstanding queries to finish.

be close()

dispose

[Source]

be dispose()

Public Functions

server_connect_info

[Source]

fun box server_connect_info()
: ServerConnectInfo val

Returns