Quick Start
On Excalibase Cloud
You need a project, its id and a publishable key. Connect to your project has the variables and the token exchange; the examples below run against the public demo project.
BASE=https://api.excalibase.io
PROJECT_ID=proj-jfp7kx46kb
KEY=esk_pub_live_Tb2pe6iauenJiWtTdBDMbeMp
TOKEN=$(curl -s -X POST "$BASE/auth/$PROJECT_ID/$PROJECT_ID/token" \
-H "Content-Type: application/json" \
-d "{\"grant_type\":\"api_key\",\"api_key\":\"$KEY\"}" | jq -r .accessToken)
Your first query
curl -s -X POST "$BASE/$PROJECT_ID/graphql" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"{ publicLivePollPolls(limit: 1) { question publicLivePollOptions(orderBy: { position: ASC }) { label } } }"}'
The same query, as you would write it in a client:
{
publicLivePollPolls(limit: 1) {
question
publicLivePollOptions(orderBy: { position: ASC }) {
label
}
}
}
publicLivePollOptions nests inside the poll because live_poll_options has a foreign key to
live_poll_polls: no join to write.
Schema prefix. Every type and field starts with the schema name. The default PostgreSQL schema is
public, solive_poll_optionsbecomespublicLivePollOptions. For MySQL the prefix is the database name.
From the SDK
import { createClient } from '@excalibase/sdk'
// A publishable key (esk_pub_...) is safe in pages and browser bundles.
const PUBLISHABLE_KEY = 'esk_pub_live_Tb2pe6iauenJiWtTdBDMbeMp'
const db = createClient({
url: 'https://api.excalibase.io',
projectId: 'proj-jfp7kx46kb',
key: PUBLISHABLE_KEY,
})
await db.auth.signInWithApiKey()
console.log(await db.graphql.query('{ publicLivePollOptions(limit: 2) { id label } }'))
What gets generated
Given a table film in public, and a role allowed to read and write it:
type Query {
publicFilm(where: PublicFilmFilter, orderBy: PublicFilmOrderBy, limit: Int, offset: Int): [PublicFilm]
publicFilmConnection(first: Int, after: String): PublicFilmConnection
publicFilmAggregate(where: PublicFilmFilter): PublicFilmAggregate
}
type Mutation {
createPublicFilm(input: PublicFilmInput!): PublicFilm
updatePublicFilm(input: PublicFilmInput!): PublicFilm
deletePublicFilm(input: PublicFilmPkInput!): PublicFilm
createManyPublicFilm(inputs: [PublicFilmInput!]!): [PublicFilm]
}
type Subscription {
publicFilmChanges: ChangeEvent
}
Each field exists only when the caller's role has that permission, so your list may be shorter.
...Aggregate needs allowAggregations; totalCount on a connection does too.
Create, update, delete
The demo project lets anon insert feedback posts (kind, body, author_name) and nothing else.
This mutation is shown, not run: a GraphQL mutation cannot be rolled back the way a REST write can
(Prefer: tx=rollback), so the docs check does not send it.
curl -s -X POST "$BASE/$PROJECT_ID/graphql" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"mutation { createPublicFeedbackPosts(input: { kind: \"idea\", body: \"Dark mode\", author_name: \"Ada\" }) { id kind } }"}'
mutation {
updatePublicFilm(input: { film_id: 1001, rental_rate: 1.99 }) { film_id rental_rate }
deletePublicFilm(input: { film_id: 1001 }) { film_id title }
}
update takes the primary key inside input; delete returns the deleted row. A refused write
answers an errors entry with a code such as unique_violation or permission_denied; see
Errors.
Self-hosting
This section is for running the engine yourself. Everything above works against your own stack once
you replace https://api.excalibase.io and the token exchange with your own. GraphiQL is
self-hosted only: a cloud project's GET /graphql answers 405.
Get a full GraphQL API running in under 2 minutes.
Prerequisites
- Docker and Docker Compose installed
Start with PostgreSQL
git clone https://github.com/excalibase/excalibase-graphql.git
cd excalibase-graphql
docker-compose up -d
This starts PostgreSQL, NATS, excalibase-watcher, the GraphQL server on port 10000, and GraphiQL on port 20000.
Open http://localhost:20000 for the GraphiQL playground, or send requests directly to http://localhost:10000/graphql.
Start with MySQL
docker-compose -f docker-compose.mysql.yml up -d
MySQL starts on the default port, GraphQL server on port 10001.
In the standalone Docker setup the first query is the same as above with the film schema:
{
publicFilm(where: { rating: { eq: "PG" } }, orderBy: { rental_rate: ASC }, limit: 5) {
title
rental_rate
publicActor { first_name last_name }
}
}
Configuration
Docker / environment variables
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/yourdb
SPRING_DATASOURCE_USERNAME=youruser
SPRING_DATASOURCE_PASSWORD=yourpass
APP_SCHEMAS=public
application.yaml
spring:
datasource:
url: jdbc:postgresql://localhost:5432/yourdb
username: youruser
password: yourpass
app:
schemas: public
Configuration reference
| Key | Default | Description |
|---|---|---|
app.schemas | public | Comma-separated list of schemas to expose, or ALL for auto-discovery |
app.database-type | postgresql | postgresql or mysql |
server.port | 10000 | HTTP port |
All tables in the configured schemas are automatically exposed. There is no include/exclude list — control access at the database level with views or RLS policies.