Module Neodriver_eio.Session

Per-session connection: auto-commit queries, explicit and managed transactions.

Per-session connection with auto-commit queries, explicit and managed transactions.

A t owns the session's lazy connection, its bookmarks and its current explicit transaction. run sends an auto-commit query and returns a lazily streamed Neo4j_result.t (records are pulled on demand; the bookmark from the final PULL summary is recorded automatically once the result is consumed); begin_transaction opens an explicit transaction; execute runs a managed transaction (unit of work) with the retry loop described in the PLAN (budget, jittered backoff, decision via Errors.is_retryable). Between retry attempts the transaction's connection is returned to the pool and a fresh one acquired (a failed writer/reader is deactivated, so the next ROUTE skips it).

Modeled on the Python driver's AsyncSession (_async/work/session.py).

type failure =
  1. | Driver of Neodriver_core.Errors.t
  2. | Client
    (*

    How a unit of work failed: Driver e is a driver/server error (e may be retryable); Client is an application (frontend) error, which is never retried.

    *)
type config = {
  1. database : string option;
  2. access_mode : Neodriver_core.Config.access_mode;
  3. impersonated_user : string option;
  4. fetch_size : int option;
  5. bookmarks : Neodriver_core.Bookmarks.t;
  6. bookmark_manager : Neodriver_core.Bookmark_manager.t option;
  7. auth : Neodriver_core.Auth_manager.token option;
  8. max_transaction_retry_time : float;
  9. initial_retry_delay : float;
  10. retry_delay_multiplier : float;
  11. retry_delay_jitter_factor : float;
  12. disable_auto_commit_retries : bool;
  13. notifications_min_severity : string option;
  14. notifications_disabled_categories : string list option;
}

Session settings. bookmarks seeds the session's bookmarks: without a bookmark_manager they are sent with every transaction and replaced by a commit's bookmark (the last_bookmarks causal chaining); with a bookmark_manager they act as one-off initial bookmarks merged into the manager's set for the session's first transaction. bookmark_manager (default None) supplies and receives the bookmarks of every transaction, so sessions sharing a manager are causally chained across the driver. auth is the session's own auth token (user switching): None (default) uses the driver's auth manager, Some token replaces it for this session (the connection is opened with — or re-authenticated to — that token). The retry parameters mirror the Python driver defaults (max_transaction_retry_time is configurable via the TestKit driver request). disable_auto_commit_retries (default false) turns off the automatic one-shot retry of an auto-commit run after a server failure marked idempotent (Bolt >= 6.0 diagnostic_record._idempotent). notifications_min_severity and notifications_disabled_categories are the session-level notification filtering settings sent in every RUN/BEGIN extra (Bolt >= 5.2; None omits the field, Some [] sends an empty category list); the driver-level settings (carried in HELLO) apply when the session does not specify any.

val default_config : config

Session configuration with the driver defaults: write access, no database or impersonation, and the Python retry defaults (1s initial delay, x2 multiplier, 0.2 jitter, 30s budget).

type t

A session: its lazy connection, bookmarks and current transaction.

val create : config -> clock:Mtime.t Eio.Time.clock_ty Eio.Resource.t -> connect: (mode:Neodriver_core.Config.access_mode -> database:string option -> bookmarks:string list -> auth:Neodriver_core.Auth_manager.token option -> (Conn.t * string option, Neodriver_core.Errors.t) Stdlib.result) -> ?release:(Conn.t -> unit) -> ?on_rt:(string option -> Neodriver_packstream.Packstream.value -> unit) -> ?on_home_db_reported:(string -> unit) -> ?pin_on_home_db_reported:bool -> unit -> t

Create a session. connect establishes the session's connection on first use with the session's access_mode, database, current bookmarks and auth (the session's own auth token, or None to use the driver's — a routed driver selects the address from its routing table — the bookmarks go into the ROUTE request — and returns the Conn.t together with the effective database actually used: the resolved home database for a default-database routed session, otherwise the requested database). The session uses that effective database for RUN/BEGIN from then on. release returns the connection on close (default Conn.close; a pool provides Pool.release). on_rt receives the rt routing tables the server returns in auto-commit RUN responses when server-side routing is enabled, keyed by the session's effective database (the routing cluster installs it to update its tables); it defaults to a no-op. on_home_db_reported receives the db a server reports for an unpinned (guessed) default-database RUN/BEGIN success (the routing cluster drops its stale home-database cache entry on a mismatch); it defaults to a no-op. pin_on_home_db_reported (default false) additionally pins such an unpinned session to the reported database, so later RUN/BEGIN messages carry it explicitly: routed drivers set it to true; a direct bolt:// session leaves it false — a database its connection is not routed to is never a usable target. clock bounds the transaction retry budget and backoff.

val conn : t -> (Conn.t, Neodriver_core.Errors.t) Stdlib.result

The session's connection, connecting on first use. A held connection whose auth changed (a rotation or an AuthorizationExpired mark) is re-authenticated before it is returned.

val tx_conn : t -> (Conn.t, Neodriver_core.Errors.t) Stdlib.result

The connection of the session's in-flight explicit transaction, without re-authentication (the transaction owns it; the re-auth is the caller's, at BEGIN time).

val run : ?timeout:float -> ?metadata:(string * Neodriver_core.Values.t) list -> t -> query:string -> parameters:(string * Neodriver_core.Values.t) list -> (Neodriver_eio__.Neo4j_result.t, Neodriver_core.Errors.t) Stdlib.result

Run an auto-commit query: send RUN only (the result streams on demand via Result). The session's bookmarks, database and access mode go into the RUN extra. Any previously pending auto-commit result is drained first. Once the result ends normally, the session's bookmarks are updated from its final summary. A server failure that answered the RUN and is marked idempotent (Bolt >= 6.0) is retried once (without re-sending the TELEMETRY notification), unless disable_auto_commit_retries; failures answering the PULL surface from the result and are never retried.

val begin_transaction : ?metadata:(string * Neodriver_core.Values.t) list -> ?timeout:float -> t -> (Tx.t, Neodriver_core.Errors.t) Stdlib.result

Begin an explicit transaction on the session's connection.

  • returns

    Error (Transaction_error "Explicit transaction already open") if a transaction is already open.

val execute : t -> mode:Neodriver_core.Config.access_mode -> ?metadata:(string * Neodriver_core.Values.t) list -> ?timeout:float -> ?telemetry:int -> ?pipeline_begin:bool -> (Tx.t -> (unit, failure) Stdlib.result) -> (unit, failure) Stdlib.result

Run the unit of work work in a managed transaction with retry. work is invoked on a fresh transaction each attempt. On Ok the transaction is committed and the session's bookmarks updated. On Error (Driver e) the transaction is rolled back; if Errors.is_retryable e and the max_transaction_retry_time budget remains, work is retried after a jittered backoff. On Error Client the transaction is rolled back without retrying. telemetry is the TELEMETRY feature code reported for the API (0, the transaction-function default, matching Session.execute_read/execute_write; high-level callers such as execute_query pass their own code).

val last_bookmarks : t -> Neodriver_core.Bookmarks.t

The session's last known bookmarks (seeded from the config, updated on every successful commit). The bookmarks of sessions sharing a Bookmark_manager are available through the manager; last_bookmarks reports what this session itself last committed (or was seeded with).

val mark_tx_ended : t -> bookmark:string option -> unit

Record the end of the session's current transaction: a successful commit's bookmark updates the session's bookmarks; None leaves them unchanged. The session is then free to begin a new transaction.

val close : t -> unit

Close the session's open transaction (if any) and its connection, best-effort.

val close_with_result : t -> (unit, Neodriver_core.Errors.t) Stdlib.result

Close the session's open transaction (if any) and its connection, like close, but surfaces a server FAILURE answering the rollback of the open transaction (connection-level failures are best-effort). The session is cleaned up on every path.