Skip to content
All logs

Why I built Cyphra, a typed ORM for Neo4j

Prisma doesn't support Neo4j, and the driver returns untyped rows with no migrations. Cyphra is the tool I wanted: one schema file, a generated TypeScript client and migrations from schema diffs. MIT.

Florian Amette3 min read

Everything in the Cyber ecosystem lives in one graph.

Concepts, skills, roles, courses, labs, library topics and the people learning them. Cyber Library, Cyber Courses, CyberCTF and Cyber Bench are all clients of that one graph. "What do I need to learn before this?" is a walk along REQUIRES edges. A graph database is the natural home for that, so the backend runs on Neo4j, and Neo4j only.

The database was never the problem. The TypeScript around it was.

What it looked like without an ORM

Three things kept hurting.

Every row was a guess. The driver hands you records, not types. Each value is untyped until you cast it, and integers come back as the driver's own Integer class. I ended up writing a wrapper whose whole job is to make every column unknown instead of any, plus a toInt helper to read numbers. Nothing tells you that u.emial is a typo until production does.

No migrations. The GraphQL layer doesn't manage constraints, so the backend creates them itself: a hand-written list of about 25 CREATE CONSTRAINT strings, run on cold start. Renaming one means writing the DROP by hand, too.

No Prisma. On Postgres I'd reach for Prisma without thinking. But Prisma doesn't support Neo4j: the request was closed as not planned in December 2024. The other Neo4j libraries each solve part of the problem. None gave me a schema, a typed client and migrations in one place.

I had already written a Neo4j adapter for Better Auth. Every new app meant writing the same glue again.

So I built the tool I wanted

Cyphra is a typed ORM for Neo4j. You describe the graph once:

node User {
  id    String @id @default(cuid())
  email String @unique
  posts Post[] @relationship(type: "AUTHORED", direction: OUT)
}

cyphra generate writes a client that knows every property and relationship:

const active = await db.user.findMany({
  where: { posts: { some: { title: { contains: "graph" } } } },
  select: { email: true },
});

active is typed from the select. Misspell email and it's a compile error, not a 3 a.m. bug.

What you get

FeatureWhat it replaces
One .cyphra schemaConstraints scattered in code
Generated typed clientunknown rows and manual casts
cyphra migrate devHand-written CREATE CONSTRAINT lists
Nested writes in one transactionMulti-step Cypher by hand
db.$cypherNothing. Raw Cypher stays one call away
cyphra devSetting up Neo4j locally: it starts Neo4j 5 in Docker and writes your .env
cyphra pullRewriting a schema for an existing database

The API will feel familiar if you've used Prisma: findMany, include, select, upsert, $transaction. That's on purpose. The goal is to make Neo4j as easy to pick as Postgres.

Not a wrapper around Cypher

Graphs are the point, so relationships are first-class: relationship properties are typed too, and connect won't create duplicate edges. When the ORM isn't enough, you write Cypher. Cyphra doesn't hide the database, it removes the boilerplate around it.

Hosting

The library and CLI are free and MIT. If you don't want to run Neo4j yourself, there's Cyphra Cloud in early access, and the Kubernetes operator behind it is open source too. Self-hosting stays first-class.

Try it

It's young, so tell me what breaks. Issues and PRs welcome.

Ship the fix. Then share the patch.