Service: Hasura GraphQL Engine - EyevinnOSC/community GitHub Wiki
Hasura GraphQL Engine (serviceId hasura-graphql-engine) instantly gives your database a real-time GraphQL and REST API. Connect a database and Hasura generates queries, mutations and subscriptions with fine-grained access control, with no backend code required. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: Apache-2.0.
- Expose tables in a PostgreSQL database as a GraphQL API (queries, mutations, subscriptions) and as REST.
- Define row and column-level access control per role.
- Authenticate clients with the admin secret, with JWT, or allow anonymous access through an unauthorized role.
- Provide the Hasura Console (when enabled) to track tables, set permissions, run queries in the GraphiQL explorer and define relationships between tables.
Hasura stores its metadata in the database you give it and also uses it as the primary data source. Create the database first and confirm it is running:
- Create a PostgreSQL instance (
birme-osc-postgresql, see Service: PostgreSQL) with a password. Usedescribe-service-instanceto read its address and port. The connection string has the formpostgres://postgres:<password>@<host>:<port>/postgres. - Store the connection string as a service secret with
create-service-secret(serviceIdhasura-graphql-engine), for example nameddburl, and the admin secret asadminsecret. The admin secret can be any strong password. A{{secrets.NAME}}reference only works as the entire field value. - Create the instance with
create-service-instance,serviceId: "hasura-graphql-engine":
{
"name": "mygraphql",
"DatabaseUrl": "{{secrets.dburl}}",
"AdminSecret": "{{secrets.adminsecret}}",
"EnableConsole": true
}Use wait-for-service-ready or get-instance-status, then describe-service-instance for the instance URL. With the OSC CLI:
npx -y @osaas/cli create hasura-graphql-engine mygraphql \
-o DatabaseUrl="{{secrets.dburl}}" \
-o AdminSecret="{{secrets.adminsecret}}" \
-o EnableConsole=true| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| DatabaseUrl | Yes | string, sensitive | Connection string for the primary database. Used for Hasura's metadata and as a data source for GraphQL operations. Hasura supports several database types and the connection string format varies by type; the OSC PostgreSQL service is the documented setup. |
| AdminSecret | Yes | string, sensitive | Secret that gives admin access: managing metadata, schema changes and the Hasura Console. Admin access bypasses all permission rules, so keep it secret. Sent in the x-hasura-admin-secret header. |
| EnableConsole | No | boolean | Enables the Hasura Console web interface (default: disabled). Useful for development and administration; consider disabling in production. |
| JwtSecret | No | string, sensitive | JWT authentication configuration: a JSON object with the key, algorithm and other JWT settings used to verify tokens sent by clients. |
| UnauthorizedRole | No | string | Role used for unauthenticated requests. When set, anonymous users can access the GraphQL API with the permissions of this role. The role must be defined in your permission system. |
Sensitive options should be stored as secrets and passed as {{secrets.NAME}}.
The PostgreSQL service (birme-osc-postgresql) has the following options. It is associated with Hasura through DatabaseUrl.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. |
| PostgresPassword | Yes | string, sensitive | Password for the PostgreSQL superuser account. Example secret reference: {{secrets.postgrespwd}}. |
| PostgresUser | No | string | Superuser name. Defaults to postgres. |
| PostgresDb | No | string | Name of the default database created at start. Defaults to the same name as the user. |
| PostgresInitDbArgs | No | string | Extra arguments passed to initdb during cluster initialization. |
| PostgresInitDbSql | No | string | SQL executed during database initialization. |
Open the instance URL and, if the console is enabled, enter the admin secret to use the Hasura Console. Query the GraphQL endpoint with the admin secret header:
curl -X POST \
https://<instance>.hasura-graphql-engine.auto.prod-se.osaas.io/v1/graphql \
-H "x-hasura-admin-secret: <your-admin-secret>" \
-H "Content-Type: application/json" \
-d '{"query": "{ users { id name email } }"}'