GraphLift
One typed query contract over three graph databases and an edge store. Compose a query once; each dialect renders it — or refuses it by name, rather than emitting something that runs and means something else.
Pre-release. Nothing here is published to a registry yet, and this page says which parts are built and which are planned.
The contract
A graph query is not portable by accident. Every backend has operations the others do not, and a layer that papers over the difference silently changes what your query means.
So the contract is explicit about it. Each backend's translator declares, per operation, what it can render and what it cannot — and where it cannot, the reason is the one measured against that server.
The same suite judges all four. Each implementation runs
assert_dialect_translator_laws, which needs no server: rendering is pure, so it proves the four renderings are
comparable, not that a server accepts them.
Acceptance is a separate suite with a server behind it.
assert_result_reader_laws
writes, reads back and compares against a pinned server in CI for each of the three
databases, and against the edge store running locally. The table below says which.
Backends
| Backend | Dialect | Read side run against |
|---|---|---|
| TypeDB | TypeQL 3.x | a pinned TypeDB server in CI |
| Neo4j | Cypher | pinned Neo4j servers in CI, Community and Enterprise |
| TerminusDB | JSON-LD WOQL | a pinned TerminusDB server in CI |
| edgegraph (SQLite in a Cloudflare Durable Object) | SQL over one graph layout | the store under wrangler dev --local in CI |
Compare the four, capability by capability.
All four are landed. The three databases are live-tested against pinned servers in CI;
the edge store runs under wrangler dev --local in its own CI job. No other
backend is in progress — this page used to promise Weaviate and ArangoDB as upcoming, and
nothing in the tree was ever started for either.
For agents
graphlift-mcp is
an MCP server over the contract, speaking stdio — the transport
Claude Desktop and most MCP clients use. Three tools:
- backends
- What each dialect declares it can render, per operation — with the measured reason where a capability is absent.
- check
- Would this request render for this backend? Answers supported, or refuses by name, without emitting a query.
- render
- The query, or the same refusal. A returned query is one the dialect declared it can render.
What it does not do: execute. It renders and refuses, and opens no
connection, takes no credential and runs no transaction — that decision is
graphlift#463. Reaching data is a separate binary,
graphlift-exec:
read-only unless given --allow-write, capped by a timeout and a row limit,
with one audit line per call, so an agent's reach is the set of binaries and flags you
grant it. There is no HTTP MCP API. This page advertised three
HTTP endpoints for query building, schema and migration while no route served any of
them (graphlift#441).
Clients for the edge
@graphlift/typedb-clients
speaks TypeDB 3.x's HTTP API, so one transport serves Node 18+, browsers
and Cloudflare Workers, and the subpath entry points differ only in their defaults.
There is also a Durable Object connection pool in
@graphlift/typedb-cloudflare.
HTTP only. Not gRPC: npm's typedb-driver tops out at
2.29.7, which a 3.x server refuses outright, and no 3.x driver is published there
(graphlift#243). No WebSocket client exists either. This page once claimed three
transports over a module whose own first comment names the one it does not speak.
Installing
Nothing is published yet. The npm entry package is
@graphlift/typedb, and
the release workflow
publishes it and its workspace dependency closure on a v* tag — but it
lands inert: no registry token is configured, so a tag stops at a named error rather
than reaching npm (graphlift#440). Until then, build from source:
git clone https://github.com/CaptainEmpower/graphlift
cd graphlift
pnpm install
cargo build --locked --manifest-path crates/graphlift-cli/Cargo.toml
cargo build --locked --manifest-path crates/graphlift-exec/Cargo.toml
cargo build --locked --manifest-path crates/graphlift-mcp/Cargo.toml
Each Rust product is its own workspace, so there is no single build. The CLI, the
execution binary and the MCP server take the contract and the backends in by path. A bare
cargo build --workspace at the root builds only the repository's own
scripts and its BDD harness.
This page used to offer an install command for a package called graphlift-client. No package of that name exists in this repository or on npm, and the command is not reproduced here — a wrong command in a code block is one copy-paste away from being run.
The CLI
graphlift, the CLI —
what works today:
graphlift backends— the capability table the contract declaresgraphlift db schema introspect— read a live database's schema back as TypeQL, Cypher or JSON-LDgraphlift db schema diff— compare a live schema with its migrations or with another database's, and exit 4 when they differgraphlift db ping— reach the server the environment names and open one database, writing nothinggraphlift db create,listanddrop— manage a server's databases;droptakes the name twicegraphlift migrate— create a migration from what changed on a server, apply it, roll it back, and report applied stategraphlift sync— copy schema and data from one backend's database into another's, the edge store included; it previews unless given--allow-write, and--move, given--allow-source-deleteas well, deletes from the source only what it verified on the targetgraphlift query— render a query for a backend, or refuse it by name; it prints the query and runs nothinggraphlift generate types— typed Rust or TypeScript models from the schema, offline from the migrations or from a live databasegraphlift newandgraphlift init— scaffold a project with a sample query and a migrations directorygraphlift validate— check that every query description in a project renders, exit 2 on a refusalgraphlift dev— serve the same answers as the render commands over local HTTP while you editgraphlift ai query— a plain-language request, by keyword matching, rendered by the contract for TypeDB, Neo4j or TerminusDB, or refused by name
And what does not. Every subcommand that only refused was removed
(graphlift#362), so graphlift --help lists what works and nothing else.
Natural language
A keyword parser turns a plain-language request into a contract request. No model is called: the configured AI provider is printed and not used.
It does not read your schema. No database is consulted. Given
--schema, the file is not parsed and a fixed example set
(person, company, employment) is used instead;
without it the type list is empty. So the types a generated query names are not
checked against anything you have.
Through the contract, and unit-tested only, with no benchmark, so
nothing here measures how often it is right. The sentence becomes the same request
graphlift query --spec takes, and the contract renders it for the backend
you name or refuses it; what a request cannot say, such as an average, is declined by
name rather than answered with a count (graphlift#464).
Where to look
The datasheet grades every capability ✅ Verified, 🟦 By design, 🟡 Partial, 🔴 Aspirational or ⚪ Planned, with the evidence that backs it. If this page and that document ever disagree, the document is the one under a CI gate.