bluetape4k-graph-neo4j

Latest stable Based on Graph release 0.5.1

Before you run

Use this module for Neo4j Java Driver, Bolt, Cypher, native sessions, schema management, merge, traversal, and paired sync/suspend APIs. Choose it when Neo4j is the operational authority. Avoid it for an embedded graph or when PostgreSQL/AGE must own the data boundary. Entry points are Neo4jGraphOperations.kt and Neo4jGraphSuspendOperations.kt.

Execution mode: release-fixture linked. The snippet assumes password comes from NEO4J_PASSWORD; the linked test creates the container, Driver, ops, test data, and closes operations before Driver/container.

Run

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<ecosystem-version>"))
    implementation("io.github.bluetape4k:bluetape4k-graph-neo4j")
}

val driver = GraphDatabase.driver("bolt://localhost:7687", AuthTokens.basic("neo4j", password))
val ops = Neo4jGraphOperations(driver, database = "neo4j")
val alice = ops.mergeVertex("Person", mapOf("email" to "a@example.com"), mapOf("name" to "Alice"))
val bob = ops.createVertex("Person", mapOf("name" to "Bob"))
ops.createEdge(alice.id, bob.id, "KNOWS")
check(ops.neighbors(alice.id, NeighborOptions(edgeLabel = "KNOWS")).single().id == bob.id)
ops.close()
driver.close()

Expected result

Expected: native merge preserves Alice’s identity, traversal returns Bob, and the caller closes the injected Driver.

Transactions, capabilities, and ownership

transaction { } executes through a Neo4j transaction; an exception must roll back writes. Schema/index operations are implemented by Neo4jGraphSchemaManager.kt. Element IDs use Neo4j elementId(); do not treat them as stable numeric IDs.

The operations object closes its sessions, not an injected Driver. Framework-managed constructors may own both; follow the Ktor or Spring page for that path.

Operations checklist

Record server/image version and selected graph/database.
Watch connection-pool pressure and query latency.
Verify transaction rollback and schema capability separately.
Close operations before caller-owned Driver/DataSource.

Failure and recovery

Symptom: authentication/service-unavailable differs from Cypher or schema errors. Repair credentials/network first, then query/index state; clear partial test data before rerunning transaction assertions.

Separate authentication/service-unavailable errors from Cypher, schema, and transaction errors. Observe driver pool acquisition, retry count, query latency, server logs, database name, indexes, and transaction rollback. Parameterize values; labels and relationship types require validated identifiers.

./gradlew :bluetape4k-graph-neo4j:test --tests '*Neo4jGraphOperationsTest' --tests '*Neo4jGraphMergeOperationsTest'

Expected: the Neo4j 5 fixture passes CRUD, traversal, merge, and rollback. A Memgraph pass is not equivalent evidence because schema DDL and supported Cypher differ.

Complete release example

The pinned Neo4jGraphOperationsTest defines the fixture values and is the complete executable release example. Run:

./gradlew :bluetape4k-graph-neo4j:test --tests '*Neo4jGraphOperationsTest'

Expected: the fixture starts, assertions pass, and owned resources close in the documented order.

See Neo4j and Memgraph, testing, and operations. This module does not provision Neo4j, own injected drivers, or guarantee that every Cypher statement is portable to another Bolt server.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.5.1 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

bluetape4k-graph-neo4j

Before you run

Run

Expected result

Transactions, capabilities, and ownership

Operations checklist

Failure and recovery

Complete release example

Non-goals and related guides

Release diagrams

Overview diagram

Reactive-Coroutine diagram

neighbors Cypher diagram

Neo4j diagram

graph neo4j Architecture 12 diagram

Neo4jGraphOperations diagram

Neo4jCoroutineSession diagram

Neo4jRecordMapper diagram

createVertex diagram

createEdge diagram

shortestPath diagram

Publisher → Coroutine diagram