Getting Started

Hasura GraphQL Engine is an open-source service that instantly gives your PostgreSQL database a real-time GraphQL and REST API. Connect your database, and Hasura auto-generates queries, mutations, and subscriptions with fine-grained access control — no backend code required. Available as a managed service in Eyevinn Open Source Cloud.

Prerequisites

Step 1: Create a PostgreSQL database

Hasura uses PostgreSQL for storing its internal metadata and as the primary data source for GraphQL operations. Navigate to the PostgreSQL service in the OSC web console, click Create psql-db, and enter a name and password.

Once the instance is running, note the external IP and port. Your connection string will be:

postgres://postgres:<password>@<IP>:<PORT>/postgres

Step 2: Store the database URL as a secret

Store the connection string as an OSC service secret so it is never visible in plain text. Navigate to the Hasura GraphQL Engine service page, open the Service Secrets tab, and click New Secret. Name it dburl and paste the connection string as the value.

Step 3: Choose an admin secret

Hasura requires you to set an admin secret to protect the console and admin API. This can be any strong password of your choice. You can also store it as an OSC service secret (e.g. adminsecret) and reference it with {{secrets.adminsecret}}.

Step 4: Create a Hasura instance

Navigate to the My graphql-engines tab and click Create graphql-engine. Fill in the fields:

Field Value
Name A short alphanumeric identifier (e.g. mygraphql)
DatabaseUrl {{secrets.dburl}}
AdminSecret Your chosen admin secret (or {{secrets.adminsecret}})
EnableConsole true for development (optional, can be disabled in production)

Click Create and wait for the instance status to turn green.

Step 5: Access the Hasura Console

Click the instance card to open it, then click Open to access the Hasura Console web UI. When prompted, enter the admin secret you set in Step 3.

From the console you can:

  • Track tables — make existing PostgreSQL tables available via GraphQL
  • Set permissions — define row and column-level access control per role
  • Run queries — use the built-in GraphiQL explorer to test queries and mutations
  • Set up relationships — define foreign-key relationships between tables

Configuration Options

Option Required Description
name Yes Alphanumeric instance name
DatabaseUrl Yes PostgreSQL connection string
AdminSecret Yes Admin password for the console and API
EnableConsole No Enable the web console UI (default: disabled)
JwtSecret No JSON config for JWT-based authentication
UnauthorizedRole No Default role for unauthenticated requests (enables public access)

Usage Example

Query your database via the GraphQL endpoint using the x-hasura-admin-secret header:

curl -X POST \
  https://<instance>.hasura-graphql-engine.auto.prod.osaas.io/v1/graphql \
  -H "x-hasura-admin-secret: <your-admin-secret>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users { id name email } }"}'

CLI Usage

# Create a Hasura GraphQL Engine instance
osc create hasura-graphql-engine mygraphql \
  -o DatabaseUrl="{{secrets.dburl}}" \
  -o AdminSecret="{{secrets.adminsecret}}" \
  -o EnableConsole=true

Resources