// STRYKE-NEO4J — NEO4J GRAPH CLIENT FOR STRYKE // CYPHER + PARAMS + RUN + SCHEMA INTROSPECTION

Contents

• Install
• Usage
• Connection options
• API surface
• Function reference
• Cypher safety & identifier quoting
• Transactions & batch
• Query planning
• URL helpers
• Why a package, not a builtin
• FFI contract
• Troubleshooting
• Layout
• Sibling packages

Install

# build the cdylib, install as a stryke package
cd ~/projects/stryke-neo4j
cargo build --release
s pkg install -g .

# one-liner
make install

The release build produces target/release/libstryke_neo4j.{dylib,so}; s pkg install -g . places it in ~/.stryke/store/neo4j@<ver>/. The cdylib is dlopened in-process on first use Neo4j.

Usage

use Neo4j

var %conn = ( uri => "neo4j://localhost:7687", user => "neo4j", password => $ENV{NEO4J_PASS} )

# write with named params ($name placeholders, never string-interpolated)
Neo4j::run("CREATE (p:Person {id: \$id, name: \$name})",
    params => { id => 1, name => "Ada" }, %conn)

# query — each row is a hashref keyed by the RETURN aliases
val @people = Neo4j::query("MATCH (p:Person) WHERE p.id = \$id RETURN p.name AS name",
    params => { id => 1 }, %conn)
p $people[0]{name}        # Ada

# scalar + schema introspection
p Neo4j::scalar("MATCH (p:Person) RETURN count(p) AS n", %conn)
p Neo4j::labels(%conn)    # [ { label => "Person" }, ... ]

The convenience helpers cover the common single-node / single-relationship CRUD shape without hand-writing Cypher. They take scalar properties only; for list or map properties, or anything more elaborate, fall back to run / query with explicit Cypher.

# node CRUD by (label, key, value) — scalar props only
val $node = Neo4j::create_node("Person", { id => 1, name => "Ada" }, %conn)
Neo4j::merge_node("Person", "id", 1, props => { name => "Ada Lovelace" }, %conn)  # upsert
Neo4j::set_props("Person", "id", 1, props => { active => \1 }, %conn)            # update-only
p Neo4j::get_node("Person", "id", 1, %conn){name}                                # Ada Lovelace
p Neo4j::exists_node("Person", "id", 1, %conn)                                   # true

# typed relationships between two matched nodes
Neo4j::create_rel(
    from_label => "Person", from_key => "id", from_value => 2,
    to_label   => "Person", to_key   => "id", to_value   => 1,
    type       => "KNOWS", props => { since => 2020 }, %conn)
Neo4j::merge_rel(                                  # idempotent edge
    from_label => "Person", from_key => "id", from_value => 2,
    to_label   => "Person", to_key   => "id", to_value   => 1,
    type       => "KNOWS", %conn)

# counts + degree (portable across 4.x / 5.x)
p Neo4j::node_count(label => "Person", %conn)                       # 2
p Neo4j::relationship_count(type => "KNOWS", %conn)                 # 1
p Neo4j::degree("Person", "id", 2, direction => "out", type => "KNOWS", %conn)  # 1

# pluck a flat list, group-by a property
val @names = Neo4j::query_column("MATCH (p:Person) RETURN p.name AS nm", "nm", %conn)
val @dist  = Neo4j::count_property_values("Person", "name", %conn)  # [ { value, count }, ... ]

# remove
Neo4j::delete_node("Person", "id", 1, %conn)                        # count removed
Neo4j::delete_nodes("Person", match => { active => \0 }, %conn)     # DETACH DELETE matched

Connection options

Each call takes a trailing %opts hash carrying the Bolt endpoint and credentials (or $NEO4J_URL as a fallback). A Graph connection pool is cached per (uri, user, database).

When no uri is passed and $NEO4J_URL is set in the environment, that Bolt URI is used as the fallback endpoint. Credentials default to user neo4j with an empty password and the server's default database when unspecified. The pool is keyed on (uri, user, password, database); a pool whose call errors is dropped from the cache so the next call reconnects cleanly.

API surface

Function reference

Every function takes a trailing %opts hash carrying connection params (see above). The signatures below list the leading positional / named arguments; %opts is omitted for brevity. Return shapes are exactly what the .stk wrappers hand back.

Liveness

Query

All four bind $name placeholders from %opts{params} (a hashref) — values are sent as Bolt parameters, never interpolated into the query text.

Write

Graph helpers (scalar properties)

Labels, relationship types, and property names cannot be parametrized in Cypher, so these helpers backtick-quote them (internal backticks doubled) — injection-safe. Property values are passed as bound parameters. A non-scalar property value (list / map) is rejected with an error; use run with hand-written Cypher for those.

Schema management

Introspection

Query planning

Cypher helpers (pure, connection-free)

URL helpers (pure, connection-free)

Cypher safety & identifier quoting

Cypher can parametrize values but not structural identifiers — labels, relationship types, and property names. The graph helpers interpolate those into the query text, so they backtick-quote each one (doubling any internal backtick) to keep interpolation injection-safe. The pure helpers expose the same machinery for hand-written Cypher:

p Neo4j::quote_ident("Person")              # `Person`
p Neo4j::quote_ident("weird`label")         # `weird``label`
p Neo4j::escape("O'Brien")                  # O\'Brien
p Neo4j::quote_literal("O'Brien")           # 'O\'Brien'
p Neo4j::format_value({ a => 1 })           # {`a`: 1}
p Neo4j::format_value([1, 2])               # [1, 2]
p Neo4j::valid_identifier("n1")             # true
p Neo4j::valid_identifier("1n")             # false

For values inside query / run, always prefer params over building literals by hand — the bound-parameter path never touches the query text at all.

Transactions & batch

batch runs a list of steps inside a single Bolt transaction. Every step commits together; if any step errors the whole transaction rolls back and the call dies with the failing step's error.

val $n = Neo4j::batch([
    { cypher => "CREATE (:Person {id: \$id})", params => { id => 1 } },
    { cypher => "CREATE (:Person {id: \$id})", params => { id => 2 } },
], %conn)
p $n                       # 2  (committed step count)

Query planning

explain returns the planner's chosen plan without executing the query; profile runs it and returns the plan annotated with runtime stats (db hits, rows). Both bind params like query.

val @plan = Neo4j::explain("MATCH (p:Person) WHERE p.id = \$id RETURN p",
    params => { id => 1 }, %conn)
val @prof = Neo4j::profile("MATCH (p:Person) RETURN count(p) AS n", %conn)

URL helpers

Bolt-URI parsing, password redaction, and reconstruction — all pure, no connection required. Useful for logging a connection string without leaking the password, or normalizing endpoints.

val $p = Neo4j::parse_url("neo4j+s://alice:secret\@graph.example.com:7687")
p $p->{host}        # graph.example.com
p $p->{port}        # 7687
p $p->{username}    # alice
p $p->{password}    # ***   (always redacted)
p $p->{tls}         # true  (neo4j+s implies TLS)

p Neo4j::redact_url("neo4j://alice:secret\@host:7687")   # neo4j://alice:***@host:7687
p Neo4j::build_url({ scheme => "neo4j", host => "db", port => 7687,
                     username => "neo4j", password => "pw" })   # neo4j://neo4j:pw@db:7687

Why a package, not a builtin

The Bolt driver (neo4rs) pulls in tokio and a TLS stack. That dependency tree ships once, on demand, as an opt-in package — stryke core is never linked against it.

The stryke side is a thin .stk wrapper; the heavy code lives in the libstryke_neo4j cdylib and is dlopened on first use Neo4j. The cdylib holds one shared tokio runtime and one Graph connection pool per (uri, user, db) — no per-call fork, no per-call reconnect.

FFI contract

Each export is a #[no_mangle] extern "C" fn neo4j__* taking a JSON request string and returning a JSON response string. stryke's FFI bridge resolves these symbols at load. Handler errors and panics are caught and surfaced as {"error": "..."} — a panic never crosses the C ABI into the host shell.

# the .stk wrapper decodes the JSON and dies on an {error} payload
fn Neo4j::_decode ($name, $json) {
    val $o = from_json $json
    if (ref $o eq "HASH" && exists $o->{error}) {
        die "Neo4j::$name: $o->{error}"
    }
    $o
}

Troubleshooting

Layout

stryke-neo4j/
├── Cargo.toml             # cdylib crate (publish = false)
├── src/
│   └── lib.rs            # neo4j__* FFI exports + Bolt ops
├── lib/                   # stryke .stk wrapper (Neo4j package)
├── stryke.toml            # stryke package manifest + ffi exports
├── t/                     # offline surface + live tests
├── Makefile               # `make install` builds + installs
└── docs/                  # this site (GitHub Pages)

Sibling packages

Part of the stryke package family. Browse the others via the MenkeTechnologiesMeta umbrella repo:

• stryke-arrow — Apache Arrow / Parquet / Feather
• stryke-aws — S3, DynamoDB, SQS, Lambda, STS
• stryke-azure — Blob, Queues, Cosmos DB, Key Vault, Entra
• stryke-clickhouse — ClickHouse
• stryke-demo — live demos for every connector
• stryke-docker — Docker daemon API
• stryke-duckdb — embedded DuckDB SQL engine
• stryke-email — email + campaign client
• stryke-fleet — parallel expect/PTY automation
• stryke-gcp — Cloud Storage, Pub/Sub, Secret Manager, BigQuery, Firestore
• stryke-grpc — reflection-based gRPC client
• stryke-gui — mouse / keyboard / screen / clipboard automation
• stryke-k8s — Kubernetes
• stryke-kafka — Apache Kafka
• stryke-mcpd — MCP servers without a runtime
• stryke-mongo — MongoDB
• stryke-mssql — Microsoft SQL Server
• stryke-mysql — MySQL / MariaDB
• stryke-office — Office docs / PDF / images
• stryke-parquet — Parquet file inspector
• stryke-polars — Polars + ndarray + linalg + FFT
• stryke-postgres — PostgreSQL
• stryke-redis — Redis / Valkey
• stryke-scrape — web scraping / crawling
• stryke-scylla — ScyllaDB / Cassandra
• stryke-search — Elasticsearch / OpenSearch
• stryke-selenium — browser automation (WebDriver)
• stryke-spark — Spark Connect (no JVM)
• stryke-utils — pure-stryke utility belt
• stryke-zmq — ZeroMQ messaging