Module Neodriver_eio.Driver

User-facing entry point: Driver.connect builds a session from a URI and auth token.

type t

A driver: a connection pool for the configured address, or a routing cluster for neo4j://.

val connect : ?resolver: (Neodriver_core.Addressing.t -> (Neodriver_core.Addressing.t list, Neodriver_core.Errors.t) Stdlib.result) -> ?domain_name_resolver: (string -> (string list, Neodriver_core.Errors.t) Stdlib.result) -> uri:string -> auth:Conn.auth -> ?auth_manager:Neodriver_core.Auth_manager.t -> ?user_agent:string -> ?connection_timeout:float -> ?encryption:Neodriver_core.Config.encryption -> ?trusted_certificates:Neodriver_core.Config.trusted_certificates -> ?client_certificate:Neodriver_core.Config.client_certificate -> ?client_certificate_provider:(unit -> Tls_client.client_certificate) -> ?pool_config:Neodriver_core.Config.pool_config -> ?workspace_config:Neodriver_core.Config.workspace_config -> [> `Network | `Platform of [> `Generic ] ] Eio.Resource.t -> Mtime.t Eio.Time.clock_ty Eio.Resource.t -> Eio.Switch.t -> (t, Neodriver_core.Errors.t) Stdlib.result

Build a driver for uri with auth. auth_manager (default Auth_manager.static auth) supplies the tokens: new connections authenticate with its current token and a reused connection is re-authenticated when it rotates. resolver replaces the address lookup for direct bolt:// drivers (each returned address is tried in turn); user_agent defaults to Conn.default_user_agent; connection_timeout (seconds) defaults to pool_config.connection_timeout and bounds each connection attempt and its subsequent reads, while writes are bounded by pool_config.connection_write_timeout. encryption and trusted_certificates are the explicit security config: they override the URI scheme's TLS choice (see Conn.tls_of_config) and a conflicting combination is an error. client_certificate is the mTLS certificate presented to the server (requires TLS); client_certificate_provider supplies a (possibly rotating) client certificate, fetched per connection, and takes precedence over client_certificate. pool_config (defaults from Config.default_pool_config: 100 connections, 1h lifetime, 60s acquisition timeout, no liveness check) sizes the pool and its acquisition timeout. workspace_config (defaults from Config.default_workspace_config) supplies the defaults of every session created by this driver: retry policy, fetch_size, database and impersonated_user (a session's own ~config overrides them), like the Python driver's driver-level workspace config. Connections are established lazily on first use; for neo4j:// the URI's address is the initial router and routing tables are fetched on demand. The sw switch is captured (it hosts the connection attempts), so it must outlive the returned t.

  • returns

    Error (Configuration_error _) for an unparseable URI or a conflicting security config; Error _ from the lazy connect on first use otherwise.

val is_encrypted : t -> bool

Whether the driver's connections use TLS: resolved from the URI scheme and the explicit encryption/trusted_certificates config (e.g. true for bolt+s, false for bolt, true for bolt with encryption = Enabled). Does not connect.

val session : ?config:Session.config -> t -> Session.t

A new session borrowing a connection from the driver's pool (or routing cluster, selected by the session's access_mode/database) on first use and returning it (with a RESET) on close. config defaults to the driver's workspace defaults (see connect's workspace_config: write access, the configured database/impersonation, retry policy and fetch size).

val acquire : ?mode:Neodriver_core.Config.access_mode -> t -> (Conn.t, Neodriver_core.Errors.t) Stdlib.result

A connection for driver-level operations (e.g. verify connectivity); return it with release. For a routed driver this uses the default database and mode (default write access).

val release : t -> Conn.t -> unit

Return a connection acquired with acquire to the pool (or cluster).

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

Whether the server supports re-authentication (Bolt >= 5.1), i.e. session-level auth (user switching): connects (see acquire) and checks the negotiated protocol.

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

Verify auth against the server, like the Python driver's verify_authentication: a read connection for the system database is opened with auth (re-authenticating a reused connection). Returns Ok true when the server accepts it; Ok false when it rejects it with an authentication error (CredentialsExpired, Forbidden, TokenExpired or Unauthorized); any other error (including the missing re-authentication support of Bolt < 5.1) propagates.

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

Verify the driver can establish a connection: acquire a fresh read connection for the default database (a routed driver fetches a routing table and connects to a reader) and release it. The connection is re-acquired on every call, so a changed cluster is re-discovered.

  • returns

    Error _ when no connection could be established.

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

Whether the server supports multiple databases, based solely on the Bolt protocol version (Bolt >= 4.0). The feature may still be disabled server-side even when this returns Ok true.

val execute_query_bookmark_manager : t -> Neodriver_core.Bookmark_manager.t

The driver's implicit (Neo4j-style) bookmark manager, used by execute_query when no ~config (or a config without its own bookmark_manager) is given — the analogue of the Python Driver.execute_query_bookmark_manager.

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

Execute query in a managed, retried transaction (a fresh session per call) and return its eager result, like the Python driver's Driver.execute_query. config defaults to the driver's workspace defaults (see connect's workspace_config) with the driver's implicit bookmark manager (see execute_query_bookmark_manager); an explicit config controls the session settings exactly (database, access_mode, impersonated_user, bookmarks, auth, ...). metadata and timeout are the transaction metadata and timeout. The result is drained eagerly into an Eager_result.t, so a retry re-runs the query against a fresh connection.

val close : t -> unit

Close the driver's pool/cluster: idle connections are closed and further acquire/session operations fail. Connections still in use by open sessions are closed (not returned to the pool) when those sessions close.

val get_routing_table : t -> database:string option -> Neodriver_core.Routing_table.t option

The driver's cached routing table for database (None for a direct bolt:// driver or before the first fetch). Test-support API for the TestKit backend.

val force_routing_table_update : t -> database:string option -> bookmarks:string list -> (unit, Neodriver_core.Errors.t) Stdlib.result

Force a routing-table refresh for database (test-support API for the TestKit backend; a direct bolt:// driver has no routing table and gets an error).

val connection_pool_metrics : t -> address:string -> int * int

The (in_use, idle) connection counts of the pool for address (the routing cluster's per-address pools; a direct driver ignores the address). Test-support API for the TestKit backend (GetConnectionPoolMetrics).