Skip to content

SessionStatusNotify

[Source]

Receives session lifecycle events: connection, authentication, transaction status changes, asynchronous notifications, server notices, and parameter status updates. All callbacks have default no-op implementations, so consumers only need to override the events they care about.

interface tag SessionStatusNotify

Public Behaviours

pg_session_connected

[Source]

Called when we have connected to the server but haven't yet tried to authenticate.

be pg_session_connected(
  session: Session tag)

Parameters

pg_session_connection_failed

[Source]

Called when the session fails to reach the ready state. Fires for any pre-ready failure including: transport-level errors (DNS, TCP, timeout), peer TCP close before the session reaches the ready state, TLS negotiation and handshake failures, unsupported authentication methods, invalid passwords, invalid users, missing databases, server connection-limit exhaustion, SCRAM server-verification failures, server protocol violations (unparseable bytes, wrong-state messages, or unexpected SSL-negotiation bytes), and any other server rejection during startup. Inspect reason to distinguish the cause; the class-valued variants carry the full ErrorResponseMessage.

For failures that originate after the TCP connection is established (TLS, authentication, protocol violation, server rejection), pg_session_connected will have already fired. Applications that need to know whether any bytes were exchanged with the server before the failure can track that callback.

pg_session_shutdown fires immediately after this callback in all cases — the session is torn down whenever connection fails.

be pg_session_connection_failed(
  session: Session tag,
  reason: ConnectionFailureReason)

Parameters

pg_session_authenticated

[Source]

Called when we have successfully authenticated with the server.

be pg_session_authenticated(
  session: Session tag)

Parameters

pg_transaction_status

[Source]

Called when the server reports its transaction status via ReadyForQuery. Fires after every query cycle completes, including the initial ready signal after authentication. The status indicates whether the session is idle, in a transaction block, or in a failed transaction.

be pg_transaction_status(
  session: Session tag,
  status: TransactionStatus)

Parameters

pg_notification

[Source]

Called when the server delivers a LISTEN/NOTIFY notification. Subscribe to notifications by executing LISTEN via Session.execute(). Notifications arrive asynchronously between query cycles.

be pg_notification(
  session: Session tag,
  notification: Notification val)

Parameters

pg_notice

[Source]

Called when the server sends a non-fatal informational message (NoticeResponse). Common triggers include DROP TABLE IF EXISTS on a nonexistent table and RAISE NOTICE from PL/pgSQL. Notices can arrive in any connected state, including during authentication.

be pg_notice(
  session: Session tag,
  notice: NoticeResponseMessage val)

Parameters

pg_parameter_status

[Source]

Called when the server reports a runtime parameter value. PostgreSQL sends these during connection startup for all reporting parameters (server_version, client_encoding, standard_conforming_strings, etc.) and again whenever a SET command changes one.

be pg_parameter_status(
  session: Session tag,
  status: ParameterStatus val)

Parameters

pg_session_shutdown

[Source]

be pg_session_shutdown(
  session: Session tag)

Parameters