Connection configuration. Use def for sensible defaults and override the fields you need. Must be validated with validateConfig before use.

A validated configuration ready for connect. Created via validateConfig.

Validate a Config, returning either validation errors or a ValidatedConfig.

Authentication scheme for the HELLO handshake.

Routing mode for cluster-aware connections.

User-agent identifier sent to the server in the HELLO message.

A BOLT protocol version (major.minor).

An open connection to a Neo4j server. Obtain via connect.

Connect to a Neo4j server using a validated configuration.

Close a connection to a Neo4j server.

Reset the connection state after an error.

Check if a connection is alive by sending RESET. Returns True if healthy, False otherwise.

Send LOGON with credentials (Bolt 5.1+). Transitions from Authentication to Ready state.

Send LOGOFF (Bolt 5.1+). Transitions from Ready to Authentication state.

Get the negotiated BOLT protocol version.

Get the server agent string.

Get the server-assigned connection ID.

Check whether the server supports telemetry.

Get the server-advertised idle timeout in seconds, if any.

Telemetry API type indicators (Bolt 5.4+).

Send a TELEMETRY message if the server supports it (Bolt 5.4+). No-op if the server does not support telemetry.

Run an action inside an explicit transaction. Automatically commits on success and rolls back on failure.

Run a transaction with automatic retry on transient failures. Uses exponential backoff between retries.

Convenience: acquire a pooled connection, run a retrying transaction, and release.

Configuration for retry logic on transient failures.

Default retry configuration: 5 retries, 200ms initial delay, 5s max delay.

Check if an error is a transient Neo4j failure that can be retried.

Check if an error indicates stale routing information. These errors mean the driver sent a request to the wrong server (e.g. a write to a read replica). The routing table should be invalidated and the operation retried on a fresh leader.

A typed Neo4j value. Every field in a query result record is a Bolt.

A single result row: a vector of Bolt values, one per column.

Errors that can occur during BOLT communication.

Extract a null value.

Extract a boolean value.

Extract an integer value.

Extract a floating-point value.

Extract a byte string value.

Extract a text value.

Extract a list value.

Extract a dictionary value.

Extract a node value.

Extract a relationship value.

Extract a path value.

Server metadata from a PULL SUCCESS response.

A pool of Neo4j connections with health-check and retry configuration.

Configuration for the connection pool.

Default pool configuration: 10 max connections, 60 second idle timeout, 1 ping retry.

Strategy for validating connections when they are checked out of the pool.

Snapshot of pool-level counters.

Create a new connection pool. If the server advertises connection.recv_timeout_seconds, the pool's idle timeout is capped to min(configured, hint - 5) so connections are recycled before the server closes them.

Destroy the pool, closing all connections.

Acquire a healthy connection from the pool, run an action, then release it. Validates the connection using the configured ValidationStrategy. On connection failure during the action, discards the dead connection and retries once with a fresh one.

A checked-out connection handle, bundling the connection with its local pool reference for proper release.

Acquire a validated connection from the pool. The caller is responsible for releasing it with releaseConnection or releaseConnectionOnError.

This is the low-level primitive behind withConnection. Prefer withConnection for simple request-response patterns. Use acquireConnection when you need the connection to outlive a callback (e.g. for streaming with bracketIO).

Release a connection back to the pool after successful use.

Release a connection after an error, destroying it instead of returning it to the pool (since it may be in a bad state).

Read a snapshot of the pool's lifetime counters.

Access mode for routing: determines whether to use reader or writer servers.

A parsed routing table returned by the ROUTE message.

A routing-aware connection pool that directs connections based on access mode.

Configuration for a routing-aware connection pool.

Default routing pool configuration.

Create a routing-aware connection pool. Connects to the seed address, fetches the initial routing table, and sets up per-address pools.

Destroy all per-address pools in the routing pool.

Acquire a connection routed by access mode, run an action, then release. On connection failure, tries the next address in round-robin order until all addresses are exhausted.

Acquire a routed connection by access mode. Returns a CheckedOutConnection that must be released by the caller. Tries addresses in round-robin order, failing over on unavailable servers.

Run a retrying transaction routed by access mode. Re-acquires routing table and connection on each retry attempt, so that routing errors (NotALeader) and transient errors trigger fresh routing.

Invalidate the cached routing table, forcing a refresh on the next operation. Use this when a routing error (e.g. NotALeader) indicates the table is stale.

Fetch a routing table from the server. The connection must be in Ready state.

A session bundles a connection pool with bookmark management and configuration. Sessions track bookmarks automatically across managed transactions (readTransaction, writeTransaction) to ensure causal consistency.

Session configuration.

Default session configuration: default database, write access, no initial bookmarks.

Mutable bookmark holder for causal consistency across transactions. Within a session, each committed transaction produces a bookmark that supersedes all previous bookmarks. The manager tracks the latest bookmark(s) so they can be passed to the next transaction's BEGIN.

Create a session using a direct (non-routing) connection pool.

Create a session using a routing-aware connection pool.

Run a read transaction. Uses ReadAccess for routing (directs to read replicas in a cluster). Automatically handles BEGIN, COMMIT, ROLLBACK, bookmark propagation, and retries on transient failures.

Run a write transaction. Uses WriteAccess for routing (directs to the leader in a cluster). Automatically handles BEGIN, COMMIT, ROLLBACK, bookmark propagation, and retries on transient failures.

Get the last bookmarks from the session. Pass these to a new session's SessionConfig to ensure the new session sees all committed writes.

A node in the query execution plan tree (from EXPLAIN).

A node in the query profile tree (from PROFILE). Extends PlanNode with actual execution statistics.

Run EXPLAIN on a Cypher query, returning the query plan without executing it.

Run PROFILE on a Cypher query, returning both decoded rows and the profile tree with actual execution statistics (db hits, rows, timing, etc.).

Information about a completed query, passed to the queryLogger callback.

A notification emitted by the server during query execution. Notifications include warnings about performance (cartesian products, missing indexes), deprecation notices, and hints.

Severity level of a notification.

Position in a Cypher query string.

Typed query statistics from the PULL SUCCESS metadata. All integer fields default to 0 and booleans to False when absent.

A monad for running queries against a Neo4j connection. Use runBolt to execute a BoltM action with a Connection.

Run a BoltM action with a Connection.

Run a Cypher query, decode each record using the FromBolt instance, and return the decoded rows or a DecodeError. Pass mempty for no parameters.

Like query, but with an explicit RowDecoder instead of using FromBolt.

Run a Cypher query and return a ResultSet (field names + records). Use decodeResultSet or groupByField for multi-pass decoding. Pass mempty for no parameters.

Run a Cypher query, decode each record using the FromBolt instance, and return the decoded rows paired with server metadata (QueryMeta). Pass mempty for no parameters.

Like queryMeta, but with an explicit RowDecoder instead of using FromBolt.

Run a Cypher query and return a ResultSet paired with server metadata (QueryMeta — timing, statistics, notifications, plan/profile). Pass mempty for no parameters.

Run a Cypher query for side effects only, discarding the result. Pass mempty for no parameters.

Errors that can occur when decoding a Bolt value or record row.

A decoder for a single Bolt value.

A decoder for a full result row. Compose with Applicative to decode multiple columns.

Types that can be decoded from a result row without an explicit decoder.

Implement this for your application types to use query without passing a RowDecoder explicitly:

data Person = Person { name :: Text, age :: Int64 }

instance FromBolt Person where
  rowDecoder = Person <$> field "name" text <*> field "age" int64

Types that can be encoded to a Ps value for use as query parameters. All PackStream instances are automatically ToBolt instances.

Decode a BoltBoolean.

Decode a BoltInteger as a PSInteger.

Decode a BoltInteger narrowed to Int64. Fails if the value is out of range.

Decode a BoltFloat.

Decode a BoltString.

Decode a BoltBytes.

Make a decoder nullable: returns Nothing for BoltNull, otherwise applies the inner decoder.

Decode a BoltList, applying the element decoder to each item.

Decode a BoltDictionary.

Decode a UUID from a BoltString.

Decode a UTCTime from a BoltString (ISO 8601) or BoltDateTime.

Decode a Day from a BoltString (ISO 8601).

Decode a TimeOfDay from a BoltString (ISO 8601).

Decode any Bolt value to an Value.

Extract a property from a BoltNode by key and decode it.

Extract a property from a BoltNode by key, returning Nothing if the key is missing.

Extract labels from a BoltNode.

Extract the raw properties HashMap from a BoltNode.

Decode a BoltNode.

Decode a BoltRelationship.

Decode a BoltPath.

Decode a value at a positional column index.

Decode a value by column name.

A query result: field (column) names paired with the result records. Supports multi-pass decoding — decode the same rows with different RowDecoders without re-running the query.

Decode every record in a ResultSet using a RowDecoder. Fails on the first DecodeError.

Decode the first record of a ResultSet, or fail with EmptyResultSet.

Group consecutive records by a decoded key field.

Records whose key decodes to Nothing (e.g. NULL from an OPTIONAL MATCH with no match) are skipped. Grouping is consecutive, not global: if the same key appears in non-adjacent runs, they become separate groups.

Each sub-ResultSet shares the parent's field names.

Prefer Cypher COLLECT() when possible — this function is an escape hatch for queries where server-side aggregation is impractical.

A PackStream value. This is the intermediate AST used for serialization.