Conn (neodriver_eio.Neodriver

type auth = {

scheme : string;
principal : string;
credentials : string;

}

Authentication token sent in HELLO (Bolt <= 5.0) or LOGON (Bolt >= 5.1). Only the basic scheme is supported so far.

type config = {

host : string;
port : int;
scheme : Neodriver_core.Addressing.scheme;
connection_timeout : float;
user_agent : string;
auth : auth;

}

Target connection settings. The scheme selects TLS: Bolt plain, Bolt_secure TLS with certificate validation, Bolt_self_signed TLS without validation. Routing schemes (Neo4j*) are rejected until routing is implemented.

type t

An established, authenticated Bolt connection: the transport, the negotiated protocol version and the tracked server state.

val default_user_agent : string

Default user_agent header for HELLO.

val basic_auth : ?principal:string -> ?credentials:string -> unit -> auth

The basic authentication token (scheme = "basic"), with the given principal (default neo4j) and credentials (default empty).

val connect : 
  ?resolver:
    (Neodriver_core.Addressing.t ->
      (Neodriver_core.Addressing.t list, Neodriver_core.Errors.t) Stdlib.result) ->
  [> `Network | `Platform of [> `Generic ] ] Eio.Resource.t ->
  Mtime.t Eio.Time.clock_ty Eio.Resource.t ->
  Eio.Switch.t ->
  config ->
  (t, Neodriver_core.Errors.t) Stdlib.result

Establish a connection (over TLS when the scheme requires it), negotiate the Bolt protocol version and authenticate. resolver replaces the address lookup: the address built from config is passed to it and each returned address is tried in turn (first success wins, errors are aggregated). Without resolver, the single configured address is used. An IPv6 literal in config.host is treated as such (the address is built with brackets around the host). For Bolt >= 5.1 the authentication is sent via LOGON after HELLO; for older versions it is inline in HELLO. clock bounds the whole attempt and subsequent reads/writes by config.connection_timeout.

returns
Error _ for connection/handshake failures, for routing schemes (unsupported until routing is implemented), or for an authentication failure reported by the server.

val address : t -> Neodriver_core.Addressing.t

The resolved address the connection is established with.

val version : t -> int * int

The negotiated protocol version (major, minor).

val server_state : t -> State.t

The tracked server protocol state.

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

Send a RESET and wait for the response; the server returns to Ready.

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

Re-authenticate with auth via LOGON (Bolt >= 5.1 only). A RESET is sent first if the server is in the Failed state.

returns
Error _ for older protocol versions or on server failure.

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

De-authenticate via LOGOFF (Bolt >= 5.1 only). A RESET is sent first if the server is in the Failed state.

returns
Error _ for older protocol versions or on server failure.

val close : t -> unit

Close the connection.

val hydration : t -> Neodriver_core.Hydration.t

A fresh hydration scope for the connection's protocol version.

type run_metadata = {

fields : string list;
qid : int option;
bookmark : string option;
t_first : int option;

}

Metadata of a RUN response: the result's field names, the query id (for multiple results), the bookmark reported for an auto-commit transaction (if any) and the t_first timing (result available-after, milliseconds).

val run : 
  ?mode:Neodriver_core.Config.access_mode ->
  ?db:string ->
  ?bookmarks:string list ->
  ?timeout:float ->
  ?metadata:(string * Neodriver_core.Values.t) list ->
  t ->
  hydration:Neodriver_core.Hydration.t ->
  query:string ->
  parameters:(string * Neodriver_core.Values.t) list ->
  (run_metadata, Neodriver_core.Errors.t) Stdlib.result

Send a RUN message for query. parameters are dehydrated with hydration. The optional mode, db, bookmarks, timeout (seconds) and metadata (tx_metadata) go into the request's extra map.

returns
Error _ if the server fails the request (the connection enters Failed and is RESET before the next request).

val begin_ : 
  t ->
  extra:Neodriver_packstream.Packstream.value ->
  (unit, Neodriver_core.Errors.t) Stdlib.result

Send a BEGIN message (start a transaction) with the given extra map (see build_extra). A RESET is sent first if the server is in the Failed state.

val build_extra : 
  ?mode:Neodriver_core.Config.access_mode ->
  ?db:string ->
  ?imp_user:string ->
  ?bookmarks:string list ->
  ?timeout:float ->
  ?metadata:(string * Neodriver_packstream.Packstream.value) list ->
  unit ->
  Neodriver_packstream.Packstream.value

The extra map for BEGIN (and auto-commit RUN): mode (Read -> "r"), db, imp_user, bookmarks, timeout (seconds, sent as tx_timeout milliseconds) and metadata (tx_metadata, already dehydrated).

val commit : 
  t ->
  (Neodriver_packstream.Packstream.value, Neodriver_core.Errors.t)
    Stdlib.result

Send a COMMIT message (end the transaction, applying its writes). Returns the full response metadata (its bookmark entry records the commit position).

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

Send a ROLLBACK message (end the transaction, discarding its writes). On a Failed connection the server already discarded the transaction implicitly, so a RESET is sent instead.

val pull : 
  ?n:int ->
  ?qid:int ->
  t ->
  hydration:Neodriver_core.Hydration.t ->
  (Neodriver_core.Values.t list list
   * (Neodriver_packstream.Packstream.value, Neodriver_core.Errors.t)
       Stdlib.result,
    Neodriver_core.Errors.t)
    Stdlib.result

Send a PULL message, fetching up to n records (all by default) of the result qid. Records are hydrated with hydration. Returns the records delivered and the terminal outcome: Ok _ with the PULL summary metadata (its has_more flag, readable via Bolt.metadata_has_more, says whether more records remain) on SUCCESS, or Error _ for a server FAILURE (the records delivered before the failure are kept). A server failure leaves the connection in the Failed state.

val discard : 
  ?n:int ->
  ?qid:int ->
  t ->
  (unit, Neodriver_core.Errors.t) Stdlib.result

Send a DISCARD message, discarding up to n remaining records (all by default) of the result qid. A server failure is surfaced as Error _.

type stream

A lazily-streamed result on a connection: RUN is sent immediately, records are pulled in batches on demand. The terminal state is a summary (normal end) or an error (a server failure, surfaced after the buffered records are consumed).

val stream : 
  ?on_complete:(Neodriver_packstream.Packstream.value -> unit) ->
  t ->
  hydration:Neodriver_core.Hydration.t ->
  run_metadata:run_metadata ->
  stream

A fresh stream for the given connection, hydration scope and RUN metadata. on_complete fires with the final summary once the stream ends normally.

val connection : stream -> t

The connection the stream is running on.

val buffered : stream -> Neodriver_core.Values.t list list

The records buffered so far, in order.

val has_more : stream -> bool

Whether the stream still has records to pull.

val error : stream -> Neodriver_core.Errors.t option

A server failure that interrupted the stream.

val summary : stream -> Neodriver_packstream.Packstream.value option

The final PULL summary metadata, once the stream has ended normally.

val run_metadata : stream -> run_metadata

The RUN metadata (field names, query id, timings, bookmark).

val pull_stream : 
  ?n:int ->
  stream ->
  (Neodriver_core.Values.t list list, Neodriver_core.Errors.t) Stdlib.result

Pull up to n more records (all by default), buffering them, and return the newly fetched records. A server failure mid-stream is stored on the stream (error) and the records delivered before it are kept. Once the stream ends normally, its summary is stored.

returns
Error _ for transport failures.

val server_agent : t -> string option

The server agent string reported in the HELLO response, if any.

val capabilities : t -> Neodriver_core.Capabilities.t

The protocol capabilities of the connection's version.

val current_auth : t -> auth option

The authentication token the connection is currently logged on with, if any.

val re_auth : t -> auth -> (bool, Neodriver_core.Errors.t) Stdlib.result

Re-authenticate when auth differs from the current token (LOGOFF then LOGON, Bolt >= 5.1). Returns whether the token changed (false when it is the same as the current one).

returns
Error _ for older protocol versions or on server failure.

val mark_unauthenticated : t -> unit

Forget the current token (the next re_auth will log on again).