Skip to content
Back to search

graphjin

One governed graph for AI agents — GraphQL + MCP over your databases, files, APIs, and code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dosco/graphjin with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dosco/graphjin'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dosco--graphjin/badge.svg)](/listings/dosco--graphjin)

HTML

<a href="/listings/dosco--graphjin"><img src="/api/listings/dosco--graphjin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**npm (all platforms)**

npm install -g graphjin

**macOS (Homebrew)**

brew install dosco/graphjin/graphjin

**Windows (Scoop)**

scoop bucket add graphjin https://github.com/dosco/graphjin-scoop
scoop install graphjin

**Linux**

Download .deb/.rpm from [releases](https://github.com/dosco/graphjin/releases)

**Docker**

docker pull dosco/graphjin

**Docker — as an agent environment**

The same binary also ships as a graded environment for training and evaluating agents. It boots ready with nothing mounted: the demo world and a 113-task verified suite are built in.

docker run -d -p 8090:8090 --tmpfs /tmp:size=1g dosco/graphjin:env-latest

`/health` says what it is — build, suite fingerprint, dataset fingerprint, reward contract, and whether the suite matches the world it is served on. `/tmp` must be writable: each world provisions its own database there.

See [the environment docs](https://graphjin.com/environment/quickstart/) for the full story.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "graphjin",
  4. "metadata": {
  5. "description": "GraphJin is a GraphQL-to-database query compiler that lets Claude safely query and mutate SQL and MongoDB through MCP tools."
  6. },
  7. "owner": {
  8. "name": "@dosco"
  9. },
  10. "plugins": [
  11. {
  12. "name": "graphjin-mcp",
  13. "description": "Connect Claude to your SQL or MongoDB databases using GraphJin's schema-aware MCP server.",
  14. "category": "development",
  15. "source": "./claude-plugins/graphjin-mcp",
  16. "homepage": "https://github.com/dosco/graphjin/tree/master/claude-plugins/graphjin-mcp"
  17. }
  18. ]
  19. }
README.md · README · 938 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # GraphJin — One Governed Graph for Your AI Agents
  2. [![Apache 2.0](https://img.shields.io/github/license/dosco/graphjin.svg?style=for-the-badge)](https://github.com/dosco/graphjin/blob/master/LICENSE)
  3. [![NPM Package](https://img.shields.io/npm/v/graphjin?style=for-the-badge)](https://www.npmjs.com/package/graphjin)
  4. [![Docker Pulls](https://img.shields.io/docker/pulls/dosco/graphjin?style=for-the-badge)](https://hub.docker.com/r/dosco/graphjin/tags)
  5. [![Discord Chat](https://img.shields.io/discord/628796009539043348.svg?style=for-the-badge&logo=discord)](https://discord.gg/6pSWCTZ)
  6. [![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge&logo=go)](https://pkg.go.dev/github.com/dosco/graphjin/core/v3)
  7. [![GoReport](https://goreportcard.com/badge/github.com/gojp/goreportcard?style=for-the-badge)](https://goreportcard.com/report/github.com/dosco/graphjin/core/v3)
  8. GraphJin is a compiler and runtime that gives AI agents one governed graph over the systems a real company already has: databases, warehouses, files, source code, workflows, metadata, and security policy. Instead of handing an agent raw credentials and hoping it guesses correctly, GraphJin exposes that graph through GraphQL + MCP: the agent discovers before acting, validates queries, runs approved work, observes runtime status — and every answer is checked against an execution ledger before it leaves the server.
  9. It is not only for agents. GraphJin is still a high-performance GraphQL-to-database compiler, Go library, standalone API service, REST/OpenAPI gateway, and real-time subscription server. The agent use case is where everything comes together: the same compiler that serves your apps can also give AI a smart, auditable way to work across data, code, and operations.
  10. Works with PostgreSQL, MySQL, MongoDB, SQLite, Oracle, MSSQL, Snowflake, Redshift, BigQuery, Apache Cassandra / Amazon Keyspaces, S3/GCS/local files, CodeSQL source indexes - and models from Claude/GPT-4 to local 7B models.
  11. ## Why GraphJin For Agents
  12. - **A built-in agent, one call away** - POST one instruction to `/api/v1/agent` (or call the `ask_graphjin_agent` MCP tool) and GraphJin runs the discovery loop itself - as the caller, under the caller's permissions - and returns a typed, evidence-backed answer. See [Server-Side Agent](#server-side-agent).
  13. - **One governed surface for many systems** - Query operational databases, warehouses, MongoDB, object stores, local files, CodeSQL source indexes, workflows, and GraphJin system roots through GraphQL and MCP.
  14. - **Smart discovery before action** - Agents start with `query_catalog(search: "<user instruction>")`, `graphql_help`, relationship evidence, examples, config recipes, and safety notes before writing or running queries.
  15. - **Guarded action, not raw access** - Source-mode access, query allow-lists, read-only boundaries, policy-aware MCP tools, local encrypted secrets, and `gj_config` preview/apply keep changes auditable.
  16. - **Operational awareness** - `gj_security`, `gj_runtime`, and the built-in console expose policy and bounded runtime status so agents can check what is safe before they act.
  17. - **Standing questions, not just answers** - Hand a cursor-paginated subscription to `gj_watch` and GraphJin keeps answering it under the owner's permissions, resumes from persisted cursors across restarts, treats absence as a first-class event, and files what it finds in a durable inbox (`gj_watch_event`), a webhook, or a workflow. Evaluation runs on database polls, not model calls - a model writes the watch once, and nothing calls one again unless you turn on optional per-watch triage. See [Watches](#watches-and-standing-questions).
  18. - **Durable memory** - Saved queries, fragments, and workflows live in the owner-scoped `gj_artifacts` store. Normal watches are durable by default; explicit ephemeral watches use TTL leases.
  19. ## Installation
  20. **npm (all platforms)**
  21. ```bash
  22. npm install -g graphjin
  23. ```
  24. **macOS (Homebrew)**
  25. ```bash
  26. brew install dosco/graphjin/graphjin
  27. ```
  28. **Windows (Scoop)**
  29. ```bash
  30. scoop bucket add graphjin https://github.com/dosco/graphjin-scoop
  31. scoop install graphjin
  32. ```
  33. **Linux**
  34. Download .deb/.rpm from [releases](https://github.com/dosco/graphjin/releases)
  35. **Docker**
  36. ```bash
  37. docker pull dosco/graphjin
  38. ```
  39. **Docker — as an agent environment**
  40. The same binary also ships as a graded environment for training and evaluating
  41. agents. It boots ready with nothing mounted: the demo world and a 113-task
  42. verified suite are built in.
  43. ```bash
  44. docker run -d -p 8090:8090 --tmpfs /tmp:size=1g dosco/graphjin:env-latest
  45. ```
  46. `/health` says what it is — build, suite fingerprint, dataset fingerprint,
  47. reward contract, and whether the suite matches the world it is served on.
  48. `/tmp` must be writable: each world provisions its own database there.
  49. See [the environment docs](https://graphjin.com/environment/quickstart/) for
  50. the full story.
  51. ## Try It Now
  52. One command, no clone, no Docker. The binary ships with a built-in demo — a
  53. SaaS company ops app (accounts, subscriptions, invoices, support tickets) on
  54. SQLite with seeded data, saved queries, and workflows:
  55. ```bash
  56. graphjin serve --demo
  57. ```
  58. The demo project is extracted to `./graphjin-demo`, and its state lives under
  59. `./graphjin-demo/demo/`. Delete the `demo/` folder to reset the data, or
  60. delete `./graphjin-demo` entirely for a fresh copy. You'll see output like
  61. this:
  62. ```
  63. GraphJin started
  64. ───────────────────────
  65. Web UI: http://localhost:8083/
  66. GraphQL: http://localhost:8083/api/v1/graphql
  67. REST API: http://localhost:8083/api/v1/rest/
  68. Workflows: http://localhost:8083/api/v1/workflows/<name>
  69. MCP: http://localhost:8083/api/v1/mcp
  70. ```
  71. **Ask the built-in agent**
  72. With a model API key in `./.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_APIKEY`), the same command switches into agentic mode and enables GraphJin's built-in agent - one instruction in, a typed, evidence-backed answer out:
  73. ```bash
  74. curl -sS localhost:8083/api/v1/agent \
  75. -H 'content-type: application/json' \
  76. -d '{"instruction": "Which account is most at risk of churning?"}'
  77. ```
  78. Answers come back as `{status, answer, data, evidence, actions, next}`, grounded by server-side protocol guards. You can also chat with it in the built-in web console at `localhost:8083/agent` — it streams every tool call live as it works. See [Server-Side Agent](#server-side-agent) below, [AGENTIC.md](AGENTIC.md#server-side-agent), and [graphjin.com/agentic/server-agent](https://graphjin.com/agentic/server-agent/).
  79. **More demo verticals**
  80. The bigger demos live in the repo — clone it and pass `--path`:
  81. ```bash
  82. git clone https://github.com/dosco/graphjin
  83. cd graphjin
  84. graphjin serve --demo --path examples/webshop # classic GraphQL starter (Postgres)
  85. graphjin serve --demo --path examples/coffee-roastery # flagship agentic demo (Postgres + BigQuery-emu + CodeSQL)
  86. ```
  87. Each demo keeps its state under `<path>/demo/` and reuses it on later starts.
  88. A MySQL corrugated-box plant with JWT roles and a PCB fab spanning Postgres +
  89. Snowflake-emu + MongoDB + a file source + an OpenAPI supplier API live in
  90. [examples/](examples/README.md), each with an end-to-end smoke suite
  91. (`make smoke-all` runs them all). The full tour is at
  92. <https://graphjin.com/start/demos/>.
  93. ## Add GraphJin To Your AI Client
  94. ### Local / Dev
  95. Use GraphJin's helper when you want one command that normalizes the URL, probes
  96. auth, and installs the right Codex or Claude config:
  97. ```bash
  98. graphjin mcp add codex
  99. graphjin mcp add claude
  100. graphjin mcp add all http://localhost:8080
  101. ```
  102. Defaults are `client=codex`, `server=http://localhost:8080`, and project scope.
  103. The command normalizes the server to `http://localhost:8080/api/v1/mcp`. Local
  104. non-TLS HTTP is correct for loopback development; hosted servers should use
  105. HTTPS.
  106. If you prefer native client commands, add GraphJin's Streamable HTTP endpoint
  107. directly:
  108. ```bash
  109. codex mcp add graphjin --url http://localhost:8080/api/v1/mcp
  110. claude mcp add --transport http graphjin http://localhost:8080/api/v1/mcp
  111. ```
  112. GraphJin's `/api/v1/mcp` endpoint is Streamable HTTP, so Claude should use
  113. `--transport http` for GraphJin. SSE is only for older/custom MCP servers.
  114. Use `--global` when you want the MCP connection available outside the current project:
  115. ```bash
  116. graphjin mcp add codex --global
  117. ```
  118. Codex can also add non-URL stdio MCP servers with the generic command shape:
  119. ```bash
  120. codex mcp add <server-name> -- <command> [args...]
  121. ```
  122. ### Hosted GraphJin With OAuth
  123. When `mcp.oauth.enabled: true` is configured on a hosted GraphJin server, modern
  124. MCP clients can add it by URL and handle OAuth login themselves:
  125. ```bash
  126. codex mcp add graphjin --url https://graphjin.example.com/api/v1/mcp
  127. claude mcp add --transport http graphjin https://graphjin.example.com/api/v1/mcp
  128. ```
  129. This is the native remote-MCP path. GraphJin serves OAuth protected-resource
  130. metadata, authorization-server metadata, DCR/CIMD discovery, and MCP 401
  131. challenges so the client can discover login automatically. See the official
  132. [OpenAI Docs MCP quickstart](https://platform.openai.com/docs/docs-mcp) for the
  133. Codex `mcp add --url` flow and the
  134. [Claude Code MCP docs](https://docs.claude.com/en/docs/claude-code/mcp) for
  135. Claude's HTTP transport and authentication flow.
  136. For legacy/custom SSE servers, use Claude's SSE transport explicitly:
  137. ```bash
  138. claude mcp add --transport sse <name> <url>
  139. claude mcp add --transport sse private-api https://api.company.com/sse \
  140. --header "X-API-Key: your-key-here"
  141. ```
  142. ### Legacy / Current `auth_login` Fallback
  143. If a server still uses GraphJin's current `auth_login` device-code flow instead of standards OAuth, `graphjin mcp add` detects that automatically:
  144. ```bash
  145. graphjin mcp add codex https://graphjin.example.com
  146. ```
  147. The command opens the device-code login, saves `~/.config/graphjin/client.json`, and installs a credential-free local proxy config for the AI client. Re-run `graphjin mcp setup https://graphjin.example.com` later only when you want to refresh or rotate that saved CLI/proxy token.
  148. The deprecated aliases still work for scripts:
  149. ```bash
  150. graphjin mcp install codex https://graphjin.example.com
  151. graphjin mcp plugin install https://graphjin.example.com # deprecated Claude alias
  152. ```
  153. ## Authenticate The CLI
  154. Before `graphjin cli` can talk to a server, point it at one. There are no `--server` or `--token` flags — both come from a single saved config file (`~/.config/graphjin/client.json`, mode `0600`):
  155. ```bash
  156. graphjin cli setup http://localhost:8080 # local dev, no auth needed
  157. graphjin cli setup https://graphjin.example.com # signs in via the server's OIDC IdP
  158. ```
  159. What `setup` does, depending on the server:
  160. - **No built-in login** (the server has `auth_login.enabled: false`): saves only the URL. CLI calls send no `Authorization` header.
  161. - **Built-in login enabled**: kicks off an [RFC 8628 device-code flow](https://www.rfc-editor.org/rfc/rfc8628). The CLI prints a verification URL + short code, opens your browser, you sign in with the configured identity provider (Google, Okta, Keycloak, Auth0-as-IdP, Azure AD — anything OIDC), and the server mints a 30-day JWT. Both URL and JWT are saved to `client.json`.
  162. After setup every `graphjin cli ...` command just works:
  163. ```bash
  164. graphjin cli health
  165. graphjin cli query list
  166. graphjin cli schema tables
  167. graphjin cli setup show # print the saved config (token redacted)
  168. graphjin cli setup logout # delete client.json
  169. graphjin cli setup # re-run sign-in against the same server (refresh token)
  170. ```
  171. To enable built-in login, set this on the server:
  172. ```yaml
  173. auth:
  174. type: jwt
  175. jwt:
  176. secret: "long-random-shared-secret" # used to sign and verify local JWTs
  177. auth_login:
  178. enabled: true
  179. audience_graphjin: true # shorthand for audience: "graphjin-cli"
  180. oidc:
  181. issuer_url: "https://accounts.google.com"
  182. client_id: "..."
  183. client_secret: "..." # or $GJ_AUTH_LOGIN_OIDC_CLIENT_SECRET
  184. allowed_domains: ["example.com"] # optional allow-list
  185. mcp:
  186. oauth:
  187. enabled: true
  188. mode: builtin # reuses auth_login identity
  189. scopes: ["mcp"]
  190. ```
  191. Successful authentication is recorded in structured logs with the verified `email` and `name` claims (when present), giving you a clean audit trail of who called every endpoint.
  192. ## Getting started
  193. To use GraphJin with your own databases you have to first create a new GraphJin app, then configure it using its config files and then launch GraphJin.
  194. **Step 1: Create New GraphJin App**
  195. ```bash
  196. graphjin serve new my-app
  197. ```
  198. **Step 2: Start the GraphJin Service**
  199. ```bash
  200. graphjin serve --path ./my-app
  201. ```
  202. **Step 3: Add GraphJin to an AI client**
  203. ```bash
  204. graphjin mcp add claude http://localhost:8080
  205. ```
  206. **Step 4: Ask Claude questions like:**
  207. - "What tables are in the database?"
  208. - "Show me all products under $50"
  209. - "List customers and their purchases"
  210. - "What's the total revenue by product?"
  211. - "Find products with 'wireless' in the name"
  212. - "Add a new product called 'USB-C Cable' for $19.99"
  213. ## How It Works
  214. 1. **Connects to database** - Reads your schema automatically
  215. 2. **Discovers relationships** - Foreign keys become navigable joins
  216. 3. **Exposes metadata** - Built-in `gj_*` tables make discovered databases, tables, columns, relationships, functions, and indexes queryable when their feature capabilities are enabled
  217. 4. **Indexes source code** - CodeSQL turns tree-sitter syntax trees and database references into a managed SQLite database
  218. 5. **Exposes MCP tools** - Teach any LLM the query syntax
  219. 6. **Runs JS workflows** - Chain multiple GraphJin MCP tools in one reusable workflow
  220. 7. **Compiles to SQL** - Every request becomes a single optimized query
  221. No resolvers. No ORM. No N+1 queries. Just point and query.
  222. ## CodeSQL: Query Source Code Like a Database
  223. CodeSQL is a managed source kind for source trees. Configure a source folder and GraphJin creates a SQLite cache under `config/codesql/`, indexes it with tree-sitter, and updates it on restart. In development it also watches for changes while the service runs; in production live watching is disabled.
  224. ```yaml
  225. sources:
  226. - name: app
  227. kind: database
  228. type: postgres
  229. connection_string: postgres://app:secret@db/app
  230. default: true
  231. - name: code
  232. kind: code
  233. path: /srv/app
  234. infer_db_refs: true
  235. tables:
  236. - name: users
  237. source: app
  238. - name: gj_code
  239. source: code
  240. read_only: true
  241. ```
  242. GraphJin exposes CodeSQL through one ordinary GraphQL root, `gj_code`. Use `kind` to select files, symbols, references, imports, database references, docs, parse errors, change sets, and locks:
  243. ```graphql
  244. query {
  245. gj_code(where: { kind: { eq: "symbol" }, name: { iregex: "handler|resolver" } }, limit: 20) {
  246. name
  247. symbol_kind
  248. language
  249. start_row
  250. path
  251. hash
  252. }
  253. }
  254. ```
  255. GraphJin's built-in catalog creates `gj_catalog` according to the deployment-mode defaults; no source entry is required. Schema, catalog, entrypoint, capability, workflow, and system metadata are catalog items; table and column metadata are selected by `kind`. When one CodeSQL source is active, GraphJin links catalog items to code references automatically:
  256. ```graphql
  257. query {
  258. gj_catalog(where: { kind: { eq: "column" }, table_name: { eq: "users" }, column_name: { eq: "email" } }) {
  259. database_name
  260. table_name
  261. column_name
  262. gj_code {
  263. kind
  264. ref_kind
  265. path
  266. symbol_id
  267. }
  268. }
  269. }
  270. ```
  271. This is where the model gets genuinely powerful: the same agent can inspect production data systems and the code that operates them. It can ask, "which handlers touch customer invoices?", "what tables do these workflows depend on?", or "show me the imports and call sites near this data path" without switching tools or inventing a new backend.
  272. ## What AI Can Do
  273. **Simple queries with filters:**
  274. ```graphql
  275. { products(where: { price: { gt: 50 } }, limit: 10) { id name price } }
  276. ```
  277. **Nested relationships:**
  278. ```graphql
  279. {
  280. orders(limit: 5) {
  281. id total
  282. customer { name email }
  283. items { quantity product { name category { name } } }
  284. }
  285. }
  286. ```
  287. **Aggregations:**
  288. ```graphql
  289. { products { count_id sum_price avg_price } }
  290. ```
  291. **Analytics directives:**
  292. ```graphql
  293. {
  294. orders {
  295. account_id
  296. month
  297. total
  298. running_total: total @running(aggregate: sum, by: "account_id", orderBy: { month: asc })
  299. moving_avg_total: total @moving(aggregate: avg, rows: 6, by: "account_id", orderBy: { month: asc })
  300. previous_total: total @previous(by: "account_id", orderBy: { month: asc })
  301. rank_by_total: total @rank(by: "account_id", order: desc)
  302. }
  303. }
  304. ```
  305. Use analytics directives when each original row should remain visible while adding report metrics such as running totals, moving averages, previous/next values, first/last values, and rank within a group. Ordinary one-row-per-group summaries still use `distinct` plus aggregate fields. Supported SQL databases validate analytics support at compile time; MongoDB and known-old database versions return clear errors.
  306. **Mutations:**
  307. ```graphql
  308. mutation {
  309. products(insert: { name: "New Product", price: 29.99 }) { id }
  310. }
  311. ```
  312. PostgreSQL and SQLite also support an update-free insert conflict policy for a single row. GraphJin infers one supplied unique key and returns the stored row unchanged on conflict:
  313. ```graphql
  314. mutation {
  315. users(insert: { email: "ada@example.com", full_name: "Ada" }, on_conflict: get) {
  316. id email full_name
  317. }
  318. }
  319. ```
  320. **Spatial queries:**
  321. ```graphql
  322. {
  323. stores(where: { location: { st_dwithin: { point: [-122.4, 37.7], distance: 1000 } } }) {
  324. name address
  325. }
  326. }
  327. ```
  328. ## Real-time Subscriptions
  329. Get live updates when your data changes. For databases with batching support, GraphJin handles thousands of concurrent subscribers with a single database query - not one per subscriber.
  330. ```graphql
  331. subscription {
  332. orders(where: { user_id: { eq: $user_id } }) {
  333. id total status
  334. items { product { name } }
  335. }
  336. }
  337. ```
  338. **Why it's efficient:**
  339. - Traditional approach: 1,000 subscribers = 1,000 database queries
  340. - GraphJin: 1,000 subscribers = 1 optimized batch query
  341. - Automatic change detection - updates only sent when data actually changes
  342. - Built-in cursor pagination for feeds and infinite scroll
  343. Dialects that do not implement GraphJin's batched polling path are listed as unsupported in the database support matrix.
  344. Subscribe over **WebSockets** (`graphql-ws` / `graphql-transport-ws` subprotocols) or **Server-Sent Events** — set `Accept: text/event-stream` on a `POST /api/v1/graphql` request and GraphJin streams `event: next` frames for each result, terminated by `event: complete`. Works from Node.js, Go, or any browser `EventSource` / WebSocket client.
  345. ## Filesystem Tables (Local, S3, GCS)
  346. Object stores show up as ordinary tables in your GraphQL schema. Declare them in config and they get the same query surface as a database table — no per-storage GraphQL plumbing on your side.
  347. ```yaml
  348. sources:
  349. - name: avatars
  350. kind: filesystem
  351. backend: s3
  352. bucket: my-bucket
  353. prefix: avatars/
  354. region: us-east-1
  355. presign_ttl: 15m
  356. - name: invoices
  357. kind: filesystem
  358. backend: gcs
  359. bucket: invoices
  360. prefix: 2026/
  361. - name: uploads_local
  362. kind: filesystem
  363. backend: local
  364. root: /var/lib/graphjin/uploads
  365. tables:
  366. - name: avatars
  367. source: avatars
  368. read_only: true
  369. - name: invoices
  370. source: invoices
  371. read_only: true
  372. - name: uploads_local
  373. source: uploads_local
  374. ```
  375. Every filesystem table exposes the same columns regardless of backend:
  376. ```graphql
  377. { avatars(
  378. where: { key: { like: "users/%" } }
  379. order_by: { key: asc }
  380. limit: 50
  381. ) {
  382. key size content_type modified_at url
  383. }
  384. }
  385. { avatars(id: "users/42.png") {
  386. key size url data # data is base64 because the field was selected
  387. }
  388. }
  389. ```
  390. The legacy `prefix`, `key`, and `inline_data` arguments remain accepted, but new callers should use the normal GraphJin read surface: `id`, `where`, `order_by`, `limit`, `offset`, `first`, `last`, `after`, and `before`.
  391. For cursor pagination, request the standard root cursor field, e.g. `avatars_cursor`, and pass it back through `after: $cursor`.
  392. `url` is a presigned GET URL by default (15 min, configurable per table). Auth follows the standard credential chain: AWS env / `~/.aws` / IRSA / EC2 IMDS for S3, Application Default Credentials for GCS — never embedded in GraphJin config.
  393. Slim builds drop SDK weight: `-tags no_s3` or `-tags no_gcs` excludes either backend. Custom backends register through `core.OptionSetFilesystemBackend(name, factory)` — same SDK GraphJin uses for the built-ins.
  394. ## File Uploads
  395. The GraphQL endpoint accepts multipart bodies per the [graphql-multipart-request-spec](https://github.com/jaydenseric/graphql-multipart-request-spec). Files can be inlined as base64 (default) or streamed straight to a filesystem table:
  396. ```yaml
  397. uploads:
  398. enabled: true
  399. storage: avatars # name of a filesystems[] entry; omit to inline as base64
  400. storage_key_prefix: "{date}/" # {date} → YYYY/MM/DD
  401. max_size: 25_000_000
  402. allowed_mime: ["image/*", "application/pdf"]
  403. ```
  404. When `storage` is set, the file body is written to the backend and the GraphQL variable becomes a stable reference — mutations persist this directly into a JSONB column:
  405. ```json
  406. { "key": "2026/05/08/abc123.png",
  407. "url": "https://s3.../...?presigned",
  408. "size": 12345,
  409. "content_type": "image/png" }
  410. ```
  411. When `storage` is empty the variable carries the bytes inline as `{filename, content_type, size, data}` (base64) — useful for small uploads going straight into `bytea`.
  412. ## Apollo Federation v2
  413. GraphJin can register as a federation subgraph so it composes with other services behind Apollo Router / Cosmo / Hive Gateway:
  414. ```yaml
  415. federation:
  416. enabled: true
  417. version: "v2.5"
  418. keys:
  419. users: ["id"] # auto-derived from PKs by default
  420. orders: ["id", "tenant_id"] # composite keys via override
  421. shareable: ["Tag.name"] # field-level @shareable
  422. inaccessible: ["Users.encrypted_password"]
  423. ```
  424. `_service { sdl }` returns a federation-flavoured SDL with `@link`, `@key`, `@shareable`, `@inaccessible`, `@tag`, `_Service`, and `_Entity`. Composition succeeds out of the box; `_entities` resolution is on the roadmap (the engine returns a clear error today, so gateways see the gap rather than silent failures).
  425. ## HTTP API Routes
  426. `graphjin serve` exposes everything under a single host/port. All routes go through the configured auth handler unless noted.
  427. | Route | Methods | Purpose |
  428. |---|---|---|
  429. | `/api/v1/graphql` | `GET`, `POST` | GraphQL queries and mutations. Subscriptions if the request is a WebSocket upgrade or carries `Accept: text/event-stream` (SSE). |
  430. | `/api/v1/rest/<name>` | `GET`, `POST` | Run a saved/persisted query by name. Variables go in `?variables=…` (GET) or the JSON body (POST). |
  431. | `/api/v1/workflows/<name>` | `GET`, `POST` | Legacy workflow execution endpoint. In source mode it is registered only when `mcp.legacy_discovery: true`; use `gj_workflow_execution(insert)` through GraphQL otherwise. |
  432. | `/api/v1/openapi.json` | `GET` | OpenAPI 3 spec generated from your saved REST queries. |
  433. | `/api/v1/mcp` | `POST` | MCP (Model Context Protocol) HTTP transport — Streamable HTTP, stateless. |
  434. | `/api/v1/mcp/message` | `POST` | Legacy MCP message route for older local proxy/client integrations. New clients should use `/api/v1/mcp`. |
  435. | `/api/v1/agent` | `POST` | Server-side agent: send one instruction, get a typed evidence-backed answer (only when `agent.enabled`). See [Server-Side Agent](#server-side-agent). |
  436. | `/.well-known/oauth-protected-resource[/api/v1/mcp]` | `GET` | MCP OAuth protected-resource metadata (only when `mcp.oauth.enabled`). |
  437. | `/.well-known/oauth-authorization-server` | `GET` | Built-in MCP OAuth authorization-server metadata (only when `mcp.oauth.enabled`). |
  438. | `/api/v1/oauth/register` | `POST` | Built-in MCP OAuth dynamic client registration (only in builtin mode). |
  439. | `/api/v1/oauth/authorize` | `GET` | Built-in MCP OAuth authorization-code + PKCE start (only in builtin mode). |
  440. | `/api/v1/oauth/token` | `POST` | Built-in MCP OAuth token exchange/refresh (only in builtin mode). |
  441. | `/api/v1/discovery` | `GET` | Legacy discovery document. In source mode it is registered only when `mcp.legacy_discovery: true`; use catalog GraphQL roots otherwise. |
  442. | `/api/v1/discovery/<section>` | `GET` | Legacy discovery drill-down (e.g. `tables`, `insights`), gated the same way as `/api/v1/discovery`. |
  443. | `/api/v1/auth/device` | `POST` | OIDC device-flow start (only if `auth_login.enabled`). |
  444. | `/api/v1/auth/device/token` | `POST` | OIDC device-flow poll. |
  445. | `/api/v1/auth/login` | `GET` | OIDC login redirect. |
  446. | `/api/v1/auth/callback` | `GET` | OIDC callback. |
  447. | `/health` | `GET` | Liveness probe. **No auth.** |
  448. | `/` | `GET` | Built-in Web UI. Defaults on in `dev` and `agentic` modes, off in `prod`; set `web_ui` explicitly to override. The UI uses `/api/v1/graphql` and GraphJin system roots such as `gj_catalog`, `gj_security`, `gj_runtime`, `gj_code`, and `gj_config`; there is no separate admin REST API. |
  449. **Mode flags that change which routes are live:**
  450. - `mcp.disable: true` — removes `/api/v1/mcp` and `/api/v1/mcp/message`.
  451. - `mcp.only: true` — keeps only `/health` and `/api/v1/mcp*`. Legacy `/api/v1/workflows/*` and `/api/v1/discovery*` remain only when `mcp.legacy_discovery: true`.
  452. - Source mode (`sources:` present) disables legacy `/api/v1/workflows/*` and `/api/v1/discovery*` unless `mcp.legacy_discovery: true`.
  453. - `web_ui: false` — drops `/` even in dev or agentic mode.
  454. ## MCP Tools
  455. GraphJin exposes a catalog-first MCP surface that guides AI models to discover before acting. The surface is caller-aware: `tools/list`, `graphql_help`, and `query_catalog` reflect the caller's visible tools, `gj_*` roots, catalog capabilities, and blocked/admin-only actions.
  456. - Start goal-driven work with `query_catalog(search: "<user instruction>")` when it is listed.
  457. - Inspect the best row with `query_catalog(id: "...")` before writing queries, choosing relationships, or using GraphJin-specific syntax.
  458. - Use `config_recipe` rows for operator work; they spell out preflight, preview/apply, unsupported apply, verification, stop conditions, and forbidden patterns.
  459. - Act through governed GraphQL roots such as `gj_workflow_execution(insert)`, `gj_workflow(insert/update/delete)`, and `gj_config(id: "current", update: ...)` only when policy exposes them.
  460. - In source mode, `gj_config` writes must run `mode: "preview"` with `expected_catalog_revision`, then resend the exact same payload with `mode: "apply"` and `preview_id`.
  461. - Source access and GraphJin root changes should use `source_patches` by exact source name instead of rewriting the full `sources` array.
  462. - Watches are managed through the unified `gj_watch` lifecycle/review root plus the `gj_watch_event` inbox and REST wrappers (`/api/v1/watches`, `/api/v1/watch-events/unseen`). A deterministic notification is a plain watch; semantic or noisy triage adds inline, tool-free AxFlow in `enrich_json`; only an explicitly requested autonomous action adds workflow/webhook delivery. Review a flow with `flow_review_json` and its `flow_hash`, or a proposed action with `action_review_json` and its `action_hash`. Flow failures deliver the raw notification but never execute autonomous delivery. MCP clients can subscribe to the aggregate `graphjin://watch-events/unseen` resource or the per-watch `graphjin://watch-events/unseen/{watch_id}` template; exact subscriptions keep independent conversations from waking for each other's watches. Unsubscribing does not pause or delete durable watches.
  463. - Use `/api/v1/watches/cleanup-preview` before `/api/v1/watches/cleanup-apply`. Expired ephemeral watches can be expired automatically, but durable watch deletion is always explicit.
  464. - Legacy discovery tools are migration shims and are disabled unless `mcp.legacy_discovery: true`.
  465. Schema reloads, schema changes, where-clause validation, and query repair remain MCP action tools.
  466. For teams building MCP agents, internal copilots, workflow agents, or enterprise automation, see [AGENTIC.md](AGENTIC.md). It explains the catalog-first agent loop in detail: discover, inspect, validate, act, observe, and refine.
  467. Key discovery tools, when listed for the caller:
  468. - `graphql_help` to choose a catalog-backed topic route when the task is broad or unclear
  469. - `query_catalog` to search schema, relationship, workflow, language, `config_recipe`, config, policy, capability, and query-pattern items. Use `search` for ranked text discovery and `where` for exact filters.
  470. - `query_catalog(id: "...")` to inspect evidence, examples, details, safety notes, and graph edges for one row
  471. - `validate_where_clause` to validate filters before execution
  472. For JS orchestration, use:
  473. - `query_catalog` with `where: { kind: { eq: "workflow" } }` to discover reusable workflows
  474. - `graphql_help(for: "workflow_runtime")` and workflow catalog rows to discover exactly which globals/functions are available inside workflow scripts
  475. - `gj_workflow_execution(insert: { workflow_name: "...", variables: {...} })` to run `./workflows/<name>.js` through GraphQL. This is mutation-only and returns an ephemeral result row; it does not store run history. Mark the workflows source or `gj_workflow_execution` table `read_only` to block it. The `execute_workflow` MCP compatibility tool is available only when `mcp.legacy_discovery: true` and `mcp.allow_workflow_execution: true`.
  476. Legacy prompts such as `write_query` and `fix_query_error` are available only when the caller's MCP surface lists them; in source mode their guidance lives in `graphql_help`, `query_catalog`, and GraphJin repair hints.
  477. ## Server-Side Agent
  478. Instead of your client chaining `query_catalog` → `validate_where_clause` → `execute_saved_query`, let GraphJin run the catalog-first discovery loop for you. Dev and agentic modes enable the agent and expose `ask_graphjin_agent` alongside the primitive MCP tools by default. The REST endpoint `POST /api/v1/agent` takes the same instruction and returns a typed, evidence-backed answer (`status`, `answer`, `data`, `evidence`, `actions`, `next`).
  479. - **Zero configuration:** dev and agentic modes also enable a private `.graphjin/artifacts.sqlite3` store, watches (`runner: all`), and stateful MCP HTTP. No application subscription starts until an active, approved watch exists. Production defaults are unchanged.
  480. - **Execution control:** there are no per-request agent modes. `agent.read_only: true` forces the server-side agent to reject mutations, including saved-query mutations; otherwise core roles, row-level security, source/table `read_only`, and Go protocol guards decide what can run.
  481. - **Caller-scoped:** the agent runs as the caller, so core roles + row-level security enforce access. The caller's role only changes which *guidance* the agent follows, never what it can read or write.
  482. - **Grounded:** Go protocol guards keep every answer backed by real catalog/validation/execution evidence and downgrade to `blocked` (with evidence) when a step is skipped.
  483. - **Semantic-aware discovery:** when semantic catalog search is ready, the agent uses short business-intent phrases and may make one private two-or-three-phrase coverage batch; one Ax request embeds cache misses, and only real catalog relationship paths count as join evidence. Lexical-only prompts and public MCP stay unchanged.
  484. - **Machine-actionable refusals:** blocked responses carry a structured `refusal` (code, reasons, unblock steps, `policy_final`/`retryable`) so a calling agent can course-correct in one step instead of guessing.
  485. - **Server-owned model:** `ask_graphjin_agent` always uses the provider, model, and credential environment variable configured under `agent`. Without server credentials it fails closed with `model_credentials_required`.
  486. It is an RLM loop — the model writes JavaScript that calls the discovery tools, and the typed result is parsed from `key: value` output. It needs strong **code generation**, not provider tool-calling. Ax requests structured JSON for typed stages, choosing the mechanism from the named deployment profile (`agent.provider`) and its rules for the selected model; `agent.structured_output_mode: auto` is the default, with `native`, `function`, and `json_object` available as overrides. `agent.service_tier` similarly defaults to provider-delegated `auto`, with portable `standard`, `flex`, and `priority` requests available when the profile/model supports them. See [AGENTIC.md](AGENTIC.md#server-side-agent) and [CONFIG.md](CONFIG.md#agent-configuration).
  487. ## Watches And Standing Questions
  488. Asking is a pull: it only produces value when someone thinks to ask. A watch is the
  489. push direction. You hand `gj_watch` a cursor-paginated subscription once, and GraphJin
  490. keeps answering it against live data, under the owner's stored identity and role.
  491. ```graphql
  492. mutation {
  493. gj_watch(insert: {
  494. name: "failed_invoices"
  495. description: "Alert when a failed invoice changes."
  496. query: "subscription failed_invoices { invoices(where: {status: {eq: \"failed\"}}, first: 25, after: $cursor) { id account_id status attempts } invoices_cursor }"
  497. }) { id name status enabled }
  498. }
  499. ```
  500. - **It costs database polls, not model calls.** The runner rides GraphJin's existing
  501. cursor-backed subscriptions, compares a hash of each result, and writes a cursor
  502. checkpoint even when nothing changed. No model is consulted to decide whether
  503. something happened. A model writes the watch once; after that the only optional model
  504. cost is per-watch triage in `enrich_json`, which is off by default and capped per day.
  505. - **Absence is a first-class event.** A watch with `absence_json` fires when the
  506. expected thing *does not* arrive, so silence stops being indistinguishable from
  507. health.
  508. - **It survives restarts.** Cursors are persisted, so a watch resumes where it left off
  509. rather than replaying or skipping.
  510. - **It cannot outrun its owner.** A watch only ever sees what its owner could already
  511. query, and both `gj_watch` and `gj_watch_event` are owner-scoped.
  512. - **Waking you and acting are different permissions.** Inbox delivery is immediate;
  513. autonomous webhook or workflow delivery stays paused until the exact current
  514. `action_hash` is approved. Alerts fail open, actions fail closed.
  515. The built-in demo registers four standing questions on a first run (declared in
  516. `examples/saas-ops/seed/watches.yml`), three of which have already fired by the time the
  517. console opens. Management, review, cleanup, and MCP resource subscriptions are covered
  518. under [MCP Tools](#mcp-tools); the full model is in
  519. [AGENTIC.md](AGENTIC.md#watches-standing-questions-with-a-durable-inbox).
  520. ## Train And Measure Agents On Your Own Graph
  521. The same machinery that grades GraphJin's public benchmark grades agents on
  522. *your* data, and runs as a reinforcement-learning environment for tuning small
  523. models on it.
  524. ```bash
  525. # Generate a verified task suite from your catalog, with a train/eval split
  526. graphjin eval create --demo --writable --scale 500 --composition coverage --split 0.8
  527. # Serve it: pooled isolated worlds, one graded episode per request
  528. graphjin env serve --path ./graphjin-demo --suite eval/suite.yml --pool 4 \
  529. --split eval/suite.split.json --side train --freeze-time 2026-08-01T12:00:00Z
  530. ```
  531. - **Tasks come from your schema, and the reward comes from the database.** Each
  532. task carries a hidden oracle — a read-only query that computes the answer —
  533. so being plausible earns nothing. Writes are graded by the state the database
  534. ended in *and* by every other row staying put.
  535. - **Worlds are isolated and resettable.** An episode leases one, so a task that
  536. writes changes only the world it was given.
  537. - **Your real schema, without your real data.** `graphjin env clone` learns a
  538. running server's schema from its catalog and writes a local synthetic copy.
  539. No rows are read; the only real values that cross over are the closed sets
  540. the catalog already publishes.
  541. Three ways to drive an episode — GraphJin calls your endpoint, you supply each
  542. completion, or you bring the whole agent over MCP — all grading through the same
  543. contract.
  544. **→ [The GraphJin Agent Environment](https://graphjin.com/environment/)**
  545. ## JS Workflows (GraphQL + REST)
  546. Workflows let an LLM run multi-step logic in JavaScript while still using GraphJin MCP tools for DB-aware operations.
  547. Create a file in `./workflows`, for example `./workflows/customer_insights.js`:
  548. ```js
  549. function main(input) {
  550. const tables = gj.tools.queryCatalog({
  551. where: { kind: { eq: "table" } }
  552. }).cards;
  553. const top = gj.tools.executeSavedQuery({
  554. name: "top_customers",
  555. variables: { limit: input.limit || 5 }
  556. });
  557. return { tables, top };
  558. }
  559. ```
  560. ### Run via GraphQL
  561. ```graphql
  562. mutation {
  563. gj_workflow_execution(insert: {
  564. workflow_name: "customer_insights"
  565. variables: { limit: 5 }
  566. }) {
  567. status
  568. result_json
  569. error
  570. }
  571. }
  572. ```
  573. Legacy MCP clients can call `execute_workflow` only when `mcp.legacy_discovery: true`.
  574. ### Run via REST
  575. This legacy HTTP endpoint is available in legacy database mode, or in source mode only when `mcp.legacy_discovery: true`.
  576. - `POST /api/v1/workflows/<name>` with JSON body
  577. - `GET /api/v1/workflows/<name>?variables={...json...}`
  578. Both map variables to the same workflow input object.
  579. ## Chat Walkthroughs
  580. Real conversations showing how an AI assistant uses GraphJin MCP tools to help you go from zero to running queries.
  581. ### "I have databases running but don't know the details"
  582. > **You:** I have some databases running locally but I'm not sure about the ports or connection details. Can you help me set up GraphJin?
  583. > **Claude:** Let me scan your system to find running databases.
  584. >
  585. > *calls `discover_databases`*
  586. >
  587. > I found 2 databases on your system:
  588. > - **PostgreSQL** on localhost:5432 (TCP) — listening, auth: ok (user: postgres), databases: `myapp`, `myapp_test`
  589. > - **MySQL** on localhost:3306 (TCP) — listening, auth: auth_failed — default credentials failed, provide username and password
  590. >
  591. > The PostgreSQL instance has databases `myapp` and `myapp_test`. Which one would you like to configure GraphJin with?
  592. > **You:** Let's go with the "myapp" database on Postgres.
  593. > **Claude:** I'll configure GraphJin to connect to your PostgreSQL database.
  594. >
  595. > *calls `update_current_config` with databases: {"main": {type: "postgres", host: "localhost", port: 5432, user: "postgres", dbname: "myapp"}}*
  596. >
  597. > Connected successfully! Let me discover the catalog surface.
  598. >
  599. > *calls `query_catalog` with `where: {kind: {eq: "table"}}`*
  600. >
  601. > Your database has these tables: `users`, `orders`, `products`, `reviews`. Want me to write a query?
  602. > **You:** Show me users with their orders.
  603. > **Claude:** *calls `query_catalog` with `search: "join users orders", where: {kind: {eq: "relationship"}}`, then `query_catalog(id: "<relationship_id>")`, then `execute_graphql` if raw execution is listed*
  604. > ```graphql
  605. > { users { id name email orders { id total status } } }
  606. > ```
  607. > Here are the results — 24 users returned, each with their associated orders.
  608. ### "I have a Docker Compose project with MySQL"
  609. > **You:** I'm running a Docker Compose stack with MySQL. Help me connect GraphJin to it.
  610. > **Claude:** Let me check what database containers you have running.
  611. >
  612. > *calls `discover_databases`*
  613. >
  614. > Found a MySQL Docker container:
  615. > - **MySQL** via Docker — container `myapp-db-1`, image `mysql:8.0`, port mapped to localhost:13306
  616. >
  617. > I'll configure GraphJin with the discovered connection details.
  618. >
  619. > *calls `update_current_config` with databases: {"main": {type: "mysql", host: "localhost", port: 13306, user: "root", dbname: ""}}*
  620. >
  621. > What's the database name and password for your MySQL instance?
  622. > **You:** Database is "shop_db", password is "secret123".
  623. > **Claude:** *calls `update_current_config` with the full credentials*
  624. >
  625. > Connected! Let me explore the catalog.
  626. >
  627. > *calls `query_catalog` with `where: {kind: {eq: "table"}}`*
  628. >
  629. > Tables found: `customers`, `products`, `orders`, `order_items`, `categories`. Let me check how they relate.
  630. >
  631. > *calls `query_catalog` with `search: "join orders customers order_items products", where: {kind: {eq: "relationship"}}`, then `query_catalog(id: "<relationship_id>")` for the relevant relationship items*
  632. >
  633. > `orders` connects to `customers` (via customer_id) and `order_items` (via order_id), and `order_items` links to `products`. Here's a nested query:
  634. >
  635. > ```graphql
  636. > { orders { id total customer { name email } order_items { quantity product { name price } } } }
  637. > ```
  638. ### "I want to query my SQLite app database"
  639. > **You:** I have a SQLite database file in my project. Can GraphJin work with it?
  640. > **Claude:** Absolutely! Let me scan your project directory for SQLite files.
  641. >
  642. > *calls `discover_databases` with scan_dir: "."*
  643. >
  644. > Found 1 SQLite database:
  645. > - **data/app.sqlite3** — file found
  646. >
  647. > I'll configure GraphJin to use it.
  648. >
  649. > *calls `update_current_config` with databases: {"main": {type: "sqlite", path: "data/app.sqlite3"}}*
  650. >
  651. > Connected! Let me see your tables.
  652. >
  653. > *calls `query_catalog` with `where: {kind: {eq: "table"}}`*
  654. >
  655. > Tables: `tasks`, `projects`, `tags`, `task_tags`. Want to query something?
  656. > **You:** Show me all tasks with their project name, sorted by due date.
  657. > **Claude:** *calls `query_catalog` with `search: "join tasks projects", where: {kind: {eq: "relationship"}}`, then `query_catalog(id: "<relationship_id>")`, then `execute_graphql` if raw execution is listed*
  658. > ```graphql
  659. > { tasks(order_by: {due_date: asc}) { id title due_date completed project { name } } }
  660. > ```
  661. > Here are your 12 tasks sorted by due date, each showing the parent project name.
  662. ## Database Support
  663. | Database | Queries | Mutations | Subscriptions | Full-Text | GIS | Schema DDL |
  664. |----------|---------|-----------|---------------|-----------|-----|------------|
  665. | PostgreSQL | Yes | Yes | Yes | Yes | PostGIS | Yes |
  666. | MySQL | Yes | Yes | Yes | Yes | 8.0+ | Yes |
  667. | MariaDB | Yes | Yes | Yes | Yes | Yes | Yes |
  668. | MSSQL | Yes | Yes | Yes | No | Yes | Yes |
  669. | Oracle | Yes | Yes | Yes | No | Yes | Yes |
  670. | SQLite | Yes | Yes | Yes | FTS5 | SpatiaLite | Yes |
  671. | MongoDB | Yes | Yes | Yes | Yes | Yes | No |
  672. | Cassandra / Keyspaces | CQL-native | Single-table PK | Partition-bound polling | No | No | No |
  673. | Snowflake | Yes | Yes | No | No | No | Yes |
  674. | Redshift | Experimental queries | Experimental PK writes | Experimental batched polling | Limited search | Limited | Experimental basic DDL |
  675. | BigQuery | Yes (experimental) | No | No | No | No | No |
  676. | CockroachDB | Yes | Yes | Yes | Yes | No | No |
  677. Also works with AWS Aurora/RDS, Google Cloud SQL, and YugabyteDB. Snowflake supports key pair (JWT) authentication and SHOW-based catalog discovery/paging. Redshift support is experimental: queries/discovery, single-table primary-key writes, batched polling subscriptions, limited `ILIKE` search over configured `full_text` columns, limited spatial filters, and basic generated DDL. Redshift subscriptions are polling-based warehouse queries, not native change streams. BigQuery support is experimental and query-focused. Cassandra / Keyspaces support CQL-native queries, partition-bound polling subscriptions, and single-table primary-key writes; aggregates, full scans, OR-style cross-partition filters, full-text, and GIS remain outside the generic surface.
  678. ## Production Security
  679. **Query allow-lists** - In production, only saved queries can run. AI models call `execute_saved_query` with pre-approved queries. No arbitrary SQL injection possible.
  680. **Source-mode access** - New multi-user deployments should use `sources:` with request-wide `identity` and source-level access defaults. GraphJin compiles those defaults into the existing qcode/SQL enforcement path, so account filters and trusted mutation presets are enforced by the generated database query.
  681. ```yaml
  682. identity:
  683. user_id_claim: sub
  684. role_claims: [role, roles]
  685. namespace_claim: account_id
  686. sources:
  687. - name: app
  688. kind: database
  689. access:
  690. read: account
  691. write: blocked
  692. delete: blocked
  693. namespace_column: account_id
  694. ```
  695. See [SECURITY.md](SECURITY.md) for the security model and [Source Mode Migration](docs/SOURCE-MODE-MIGRATION.md) for legacy `roles[].tables` migration steps. In source mode, user-written `roles[].tables` rules are rejected intentionally.
  696. **JWT authentication** - Supports Auth0, Firebase, JWKS endpoints.
  697. **Response caching** - Redis with in-memory fallback. Automatic cache invalidation on mutations. **Stale-while-revalidate** support: serve cached responses immediately while a background worker refreshes the entry — concurrent refreshes for the same key are deduplicated via singleflight, and the worker pool is bounded so a thundering herd can't spawn unbounded goroutines.
  698. ```yaml
  699. caching:
  700. ttl: 3600 # hard expiry in seconds
  701. fresh_ttl: 300 # soft expiry — entries past this trigger SWR refresh
  702. ```
  703. ## Also a GraphQL API
  704. GraphJin works as a traditional API too - use it from Go or as a standalone service.
  705. ### Go
  706. ```bash
  707. go get github.com/dosco/graphjin/core/v3
  708. ```
  709. ```go
  710. db, _ := sql.Open("pgx", "postgres://localhost/myapp")
  711. gj, _ := core.NewGraphJin(nil, db)
  712. res, _ := gj.GraphQL(ctx, `{ users { id email } }`, nil, nil)
  713. ```
  714. ### Standalone Service
  715. ```bash
  716. brew install dosco/graphjin/graphjin # Mac
  717. graphjin serve new myapp && cd myapp
  718. graphjin serve
  719. ```
  720. Built-in web UI at `http://localhost:8080` for query development.
  721. ## Documentation
  722. - [Configuration Reference](CONFIG.md)
  723. - [Feature Reference](FEATURES.md)
  724. - [Agent Environment](https://graphjin.com/environment/) — train and measure agents
  725. - [Agent Evaluation](https://graphjin.com/agentic/evaluation/) — gate a release
  726. - [Go Examples](https://pkg.go.dev/github.com/dosco/graphjin/core#pkg-examples)
  727. ## Get in Touch
  728. [Twitter @dosco](https://twitter.com/dosco) | [Discord](https://discord.gg/6pSWCTZ)
  729. ## License
  730. [Apache Public License 2.0](https://opensource.org/licenses/Apache-2.0)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.