GraphJin: one governed graph for AI agents over databases, files and code

The problem GraphJin solves for agents that touch production data

Handing an AI agent a database credential and a prompt is the default approach, and it fails in a predictable way. The agent guesses table names, writes a query that scans the wrong partition, and nobody can reconstruct afterwards what it saw. GraphJin's answer is to put a compiler between the agent and the systems. The README frames it as giving agents "one governed graph over the systems a real company already has": databases, warehouses, files, source code, workflows, metadata and security policy.

The audience is narrower than the tagline suggests. This is for teams that already have more than one data system and want a single query surface in front of them, and for teams wiring an MCP client such as Codex or Claude into internal data. A single-service CRUD app with one Postgres instance does not need the governance layer; the compiler underneath is still useful, but the agent machinery is overhead.

Discovery before action: the catalog, the ledger and the MCP tool surface

The mechanism that distinguishes GraphJin from a plain GraphQL-to-SQL translator is the ordering it imposes on an agent's work. According to the README, agents begin with `query_catalog(search: "<user instruction>")`, then `graphql_help`, relationship evidence, examples, config recipes and safety notes, and only then write or run queries. The catalog is the discovery step, not an afterthought.

Action is bounded by source-mode access, query allow-lists, read-only boundaries and policy-aware MCP tools. Secrets are stored locally and encrypted, and configuration changes go through `gj_config` preview and apply rather than a direct write. For runtime checks the README names `gj_security` and `gj_runtime`, plus a built-in console that exposes policy and bounded runtime status.

The claim worth pausing on is that every answer is checked against an execution ledger before it leaves the server. That is the strongest governance statement in the README, and it is also the one the README states without describing the ledger's contents, retention or failure behaviour when a check does not pass. Treat that as the first thing to verify in a real deployment.

There is also a server-side agent. A single POST to `/api/v1/agent` runs the discovery loop as the caller, under the caller's permissions, and returns a typed answer. The README documents the response shape as `{status, answer, data, evidence, actions, next}`, and the built-in console at `/agent` streams each tool call as it happens. Durable state lives in an owner-scoped `gj_artifacts` store for saved queries, fragments and workflows, and `gj_watch` runs standing questions that resume from persisted subscription cursors, delivering events to a durable inbox (`gj_watch_event`), webhooks or workflows. The README states that normal watches are durable by default and that explicit ephemeral watches use TTL leases.

Installing GraphJin and running the SQLite demo

GraphJin ships as a single binary through several channels. The README lists npm for all platforms, Homebrew on macOS, a Scoop bucket on Windows, .deb and .rpm downloads for Linux, and a Docker image. Pick one:

npm install -g graphjin

brew install dosco/graphjin/graphjin

docker pull dosco/graphjin

The fastest way to see what the project actually does is the built-in demo, which the README describes as requiring no clone and no Docker. It is a SaaS company ops app with accounts, subscriptions, invoices and support tickets on SQLite, with seeded data, saved queries and workflows:

graphjin serve --demo

The project is extracted to `./graphjin-demo` and its state lives under `./graphjin-demo/demo/`. Deleting the `demo/` folder resets the data; deleting `./graphjin-demo` gives you a fresh copy. The README shows the startup banner pointing at the web UI on `http://localhost:8083/`, GraphQL at `/api/v1/graphql`, REST at `/api/v1/rest/`, workflows at `/api/v1/workflows/<name>` and MCP at `/api/v1/mcp`.

To exercise the agent rather than the raw API, put a model key in `./.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or `GOOGLE_APIKEY`) and restart the same command. The README gives this request as the first real use:

curl -sS localhost:8083/api/v1/agent \
  -H 'content-type: application/json' \
  -d '{"instruction": "Which account is most at risk of churning?"}'

The response is the typed object described above, and the same conversation is available in the console at `localhost:8083/agent`. If you want the larger demos, clone the repository and pass `--path`:

graphjin serve --demo --path examples/coffee-roastery

That one is described as the flagship agentic demo, spanning Postgres, a BigQuery emulator and CodeSQL. Each demo keeps state under `<path>/demo/` and reuses it on later starts.

Wiring GraphJin into Codex or Claude over MCP

The MCP endpoint is the part most teams will touch first, and the README treats local setup as the common case. GraphJin ships a helper that normalizes the URL, probes auth and writes the right client config:

graphjin mcp add codex
graphjin mcp add claude
graphjin mcp add all http://localhost:8080

The defaults are `client=codex`, `server=http://localhost:8080` and project scope. The command rewrites the server to `http://localhost:8080/api/v1/mcp`. If you prefer the native client commands, the README gives both:

codex mcp add graphjin --url http://localhost:8080/api/v1/mcp
claude mcp add --transport http graphjin http://localhost:8080/api/v1/mcp

One detail matters here. GraphJin's `/api/v1/mcp` endpoint is Streamable HTTP, so Claude needs `--transport http`; the README notes that SSE is only for older or custom MCP servers. Getting this wrong produces a connection that looks configured but never completes a handshake. Add `--global` to `graphjin mcp add codex` when you want the connection available outside the current project. The README also states that local non-TLS HTTP is appropriate for loopback development and that hosted servers should use HTTPS.

Where GraphJin is the wrong tool

The cost of the governance layer is configuration surface. Source-mode access, query allow-lists, read-only boundaries, policy-aware tools, encrypted secrets, `gj_config` preview and apply, watches with durable cursors, and an artifact store are all things you have to understand before the system behaves the way you expect. A team that wants "point GraphQL at my Postgres and go" will find the demo pleasant and the production setup long.

The second limitation is structural. GraphJin is a server process that sits between callers and data sources. That is what makes the ledger, the allow-lists and the permission model possible, and it is also a component that can be unavailable, misconfigured or bypassed if someone keeps a direct connection open. If your constraint is that no additional service may run next to the database, this project does not fit regardless of feature set.

Third, the evidence model is only as good as the sources behind it. The README lists a wide range of connectors, from PostgreSQL and MySQL through Snowflake, BigQuery, Cassandra and S3/GCS files to CodeSQL source indexes. Breadth across that many engines usually means depth varies by engine, and the README does not publish a per-connector maturity table. Check the connector you actually depend on before assuming parity with Postgres.

How GraphJin differs from Hasura and PostGraphile

The closest comparison is Hasura. Both put GraphQL in front of a database and both handle permissions, but Hasura's model is event-driven: you declare tables and relationships, then attach permissions, actions and event triggers to them. GraphJin's model is compiler-driven, and the README describes the same compiler serving applications, a standalone API service, a REST/OpenAPI gateway and a real-time subscription server. The agent layer is built on top of that compiler rather than beside it, which is why catalog discovery and the execution ledger are part of the query path.

PostGraphile is the sharper contrast. It introspects a PostgreSQL schema and derives a GraphQL API from it, which is elegant when Postgres is the only system in play. GraphJin's premise is that Postgres is one of many sources, and that the interesting problem is querying across them under one policy. If your world is a single Postgres schema and you want the API to follow the schema automatically, PostGraphile's approach is less machinery. If your world is Postgres plus BigQuery plus a MongoDB collection plus a file source, the cross-source graph is the point.

One more difference worth noting: GraphJin is also a Go library. The README points at `github.com/dosco/graphjin/core/v3` on pkg.go.dev, so the compiler can be embedded rather than run as a service. That option does not exist for the hosted GraphQL engines.

Maintenance, release cadence and the Apache-2.0 licence

The repository is not archived, and the most recent push recorded is 2026-08-29. Releases are frequent and granular: v3.20.65, v3.20.66 and v3.20.67 all landed on 2026-08-28 and 2026-08-29. Note that the version in the repository `package.json` is 3.20.77 while the newest release listed is v3.20.67, so the npm package version and the tagged release version do not move in lockstep. Pin explicitly if that matters to you.

Upgrade cost is a real consideration here because the surface is broad. A change to the compiler, the connector set, the MCP tool definitions or the artifact schema can affect different consumers. The repository carries an `AUTO_RELEASE.md` and a `Makefile` with a `release` target, which suggests releases are automated rather than hand-assembled, and the Makefile's own comment about the test timeout is a useful signal: it explains that the default 600s Go test timeout was 43 seconds away from failing a green build because `cmd/` alone boots enough real instances to sit near 556s under `-race`, so `GO_TEST_TIMEOUT` was raised to 30m. A test suite that boots real database instances is thorough and slow; budget for that if you plan to run `make test` locally.

The licence is Apache-2.0, which permits commercial use, modification and redistribution, and includes an explicit patent grant. The repository also carries a `NOTICE` file, and Apache-2.0 convention is to preserve it in redistributions. GraphJin is offered both as open source and as a hosted service at graphjin.com; the README does not describe which features are exclusive to the hosted offering, so if you are evaluating the hosted path, confirm that separately. Nothing here is legal advice.

Editorial conclusion

Adopt GraphJin if you already run several data systems and want one auditable GraphQL and MCP surface for agents, and you are willing to learn the catalog, policy and artifact model. Do not adopt it if you need a thin single-database GraphQL layer, or if you cannot run a server process next to your data. Before committing, verify that graphjin serve --demo --path examples/coffee-roastery starts on your machine, that your model key works at /api/v1/agent, and that the source-mode and allow-list settings match the access you actually intend to grant.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes