@graphium/neo4j

English · 한국어

Graph-native OGM with multiple graph DB backends

Explicit persistence model — opt-in Proxy automation, no hidden N+1 footguns

@graphium/neo4j is the Neo4j backend for Graphium.

What's new in 0.4

• Unlimited find() by default — the 0.3 implicit 10 000-row cap is removed. Opt in: Graph.create({ defaultMaxRows: 10_000 }).
• autoFlush dirty tracking — opt-in Proxy wrapper; mutations flush without explicit persist(). Enable: Graph.create({ autoFlush: true }).
• profile: 'production' preset — enables slow-query detector, N+1 detector, and Neo4j EXPLAIN cost alerts in one line.
• Read-only repositories — @InjectRepository(User, { mode: 'read-only' }) for NestJS (Phase 6.1).
• migrate:diff — new CLI subcommand to show schema diff between entities and applied migrations (Phase 4).

Public Surface

• Graph.create(...)
• Neo4jDriver.create(...)
• GraphManager
• Repository
• CypherBuilder<T>
• schema decorators re-exported from @graphium/core

Install

pnpm add @graphium/neo4j reflect-metadata

Quickstart

import 'reflect-metadata'
import { Graph, Neo4jDriver, Node, PrimaryKey, Property } from '@graphium/neo4j'

@Node({ label: 'User' })
class User {
  @PrimaryKey({ type: 'uuid', generated: true })
  id!: string

  @Property({ type: 'string' })
  email!: string
}

const graph = await Graph.create({
  driver: Neo4jDriver.create({
    uri: 'bolt://127.0.0.1:7687',
    username: 'neo4j',
    password: 'password',
  }),
  entities: [User],
})

const gm = graph.getManager()

await gm.save(User, {
  email: '[email protected]',
})

const users = await gm
  .cypher(User)
  .where({ email: '[email protected]' })
  .getMany()

const raw = await gm.cypherRaw('MATCH (u:User) RETURN count(u) AS count', {})
const migrator = gm.getMigrator()

uri is the preferred connection input. NEO4J_URI is read before split NEO4J_HOST, NEO4J_PORT, and NEO4J_SCHEME.

Driver-native tuning should use driverConfig. Transport security still belongs to the URI/scheme policy, for example:

Neo4jDriver.create({
  uri: 'neo4j+s://db.example.com:7687',
  username: 'neo4j',
  password: 'password',
  driverConfig: {
    fetchSize: 2_000,
    maxConnectionPoolSize: 50,
    maxTransactionRetryTime: 60_000,
    connectionAcquisitionTimeout: 30_000,
    maxConnectionLifetime: 120_000,
  },
})

Typed builder access starts at gm.cypher(Entity) or repo.cypher().

Raw Cypher

• gm.cypherRaw(...) runs a full query through the driver
• gm.cypher(Entity).raw(...) appends raw clauses in-order
• whereRaw(...) is the raw predicate helper
• matchRaw(...) and optionalMatchRaw(...) are raw structural match helpers

Related Docs

• Root README
• NeOGM migration guide
• Raw query guidelines