Excalibase GraphQL

Instant GraphQL + REST APIs on your existing Postgres or MySQL. Introspects the schema at startup, compiles each GraphQL request into one SQL statement, enforces per-role permissions in the engine (the same rules on MySQL, which has no row-level security), streams realtime changes over WebSocket, and ships a 134 MB native binary.

This is the API engine of Excalibase, an open-source platform as a service: databases, generated APIs, permissions, end-user auth, functions and app hosting in one project. Hosted beta at excalibase.io.

📘 Full documentation →

---

Features

	Feature	Docs
🔄	Auto schema generation — GraphQL types + REST endpoints from your tables, zero config	GraphQL · REST
🔍	Rich filtering — eq/neq/gt/lt/in, regex, FTS, JSON paths, vectors, arrays — per your DB	Filtering · DB compat
🧭	Vector k-NN search — pgvector-backed, cosine/L2/IP distance, HNSW indexes	Search & Vector
📡	Realtime subscriptions — WebSocket, backed by WAL (Postgres) or binlog (MySQL) via NATS CDC, filtered by the subscriber's permissions	Subscriptions
🔐	API permissions — Hasura-style, one object per table, role and operation: rows, columns and write checks	Permissions
🗄️	Tracked functions — Postgres functions returning table rows, per-role, results filtered by the return table's permissions	Functions
🔑	Composite keys, FK relations, views — forward + reverse FK fields auto-wired	GraphQL
📄	Cursor pagination — Relay-spec GraphQL connections + PostgREST-style REST	GraphQL · REST
🏢	Multi-schema — all schemas auto-discovered (except pg_* and information_schema)	Multi-schema
⚡	Native image — GraalVM 25 AOT, ~134 MB binary, starts in <100 ms	Install
📦	TypeScript SDK — @excalibase/sdk: auth + GraphQL + REST in one client, codegen types	SDK

Quickstart

# 1. Start Postgres (with sample data), the engine, auth and a mock control plane
docker compose up -d
until curl -sf http://localhost:10000/actuator/health >/dev/null; do sleep 3; done

# 2. GraphQL: routes are per project; the sample project is `e2e-test`, whose
#    permissions (served by the mock control plane) let anonymous callers read `hana.customer`
curl -s -X POST http://localhost:10000/e2e-test/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ hanaCustomer(limit: 2) { customer_id first_name last_name } }"}'
echo

# 3. REST: the same table and the same permissions
curl -s 'http://localhost:10000/e2e-test/api/v1/customer?limit=2' -H 'Accept-Profile: hana'
echo

A table with no permission for a role is invisible to it: try /e2e-test/api/v1/rls_team_orders (404). Permissions per role, table and operation are described in Permissions.

Full install guide (JVM, native image, K8s): docs/quickstart →

The platform

This repo is one service in a larger stack. Each piece runs independently:

Repo	Purpose
excalibase-graphql (this)	GraphQL + REST engine on your DB
excalibase-auth	JWT/JWKS auth with email/password + API keys
excalibase-watcher	Postgres WAL / MySQL binlog → NATS CDC for realtime + cache invalidation
excalibase	Control plane and Studio: projects, provisioning, backups, functions, app hosting
excalibase-sdk-js	TypeScript SDK (dual-protocol, auth, codegen)

Development

# Run the full test suite (unit + IT + E2E)
make e2e

# Build the native image (requires GraalVM 25)
make build-native

# Run the local dev stack with observability (Grafana, Prometheus, Tempo, Loki)
make up

See Testing for the full workflow and Contributing if you're opening a PR.

Architecture (60 seconds)

• Modules: starter (shared SPI + CDC) · postgres + mysql (dialect impls) · rest-api · rls-core + rls-jdbc (permissions) · graphql-api (composes everything)
• SqlDialect SPI: each DB declares which operators it supports; schema is built dynamically from that. Adding a new DB = implementing one dialect interface
• CDC path: Watcher tails WAL → publishes to NATS JetStream → NatsCDCService → SubscriptionService (reactor sinks per table) → WebSocket out
• Permissions: per role, table and operation (row filters, column lists, write checks), compiled into the same SQL statement; checked on MySQL against native Postgres RLS by a differential test suite

License

Apache 2.0 — see LICENSE.