Skip to content
excalibase
quickstart
GraphQL APIstable

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, so live_poll_options becomes publicLivePollOptions. 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

KeyDefaultDescription
app.schemaspublicComma-separated list of schemas to expose, or ALL for auto-discovery
app.database-typepostgresqlpostgresql or mysql
server.port10000HTTP 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.