@busflow/hasura

Hasura GraphQL Engine — metadata, migrations & seeds for the Busflow platform.

Prerequisites

• Docker stack running: pnpm docker:up (from repo root)
• Wait for Hasura healthcheck: docker ps → busflow-hasura should show healthy

Install

pnpm install

Dev Workflow

1. Start the console (CLI-tracked)

pnpm run console
# or from the repo root:
pnpm hasura:console

This opens the Hasura console at http://localhost:9695. All metadata changes made through this console (tracking tables, adding permissions, relationships, etc.) are automatically saved as YAML files in the metadata/ directory.

Important: Do NOT use http://localhost:8080/console — the Docker console is disabled so that all changes are tracked via the CLI.

2. Metadata hot-reload (dev mode)

pnpm run dev
# or from the repo root:
pnpm dev:hasura

Watches metadata/**/*.yaml and auto-applies changes to the running Hasura instance via nodemon.

3. Create a migration

pnpm run migrate:create -- --up-sql "CREATE TABLE ..." --down-sql "DROP TABLE ..."
# or interactively via the console

4. Apply everything (CI / fresh setup)

pnpm run apply-all

This runs the full apply cycle in the correct order:

1. metadata:apply — apply metadata YAML to Hasura
2. migrate:apply — apply pending SQL migrations
3. metadata:reload — reload metadata to pick up new tables
4. metadata:inconsistency:list — verify no inconsistencies

Available Scripts

Script	Description
dev	Watch metadata and auto-apply (nodemon)
console	Open CLI-tracked Hasura console
migrate:status	Show migration status
migrate:apply	Apply pending migrations
migrate:create	Create a new migration
metadata:apply	Apply local metadata to Hasura
metadata:export	Export Hasura metadata to local YAML
metadata:reload	Reload metadata on the server
metadata:diff	Diff local vs remote metadata
seed:apply	Apply seed data
apply-all	Full cycle: metadata → migrations → reload → check

Directory Structure

apps/hasura/
├── config.yaml          # Hasura CLI project config
├── nodemon.json         # Dev hot-reload config
├── package.json         # hasura-cli + nodemon deps
├── scripts/
│   └── hasura.sh        # CLI wrapper (loads .env, injects secrets)
├── metadata/            # Hasura metadata (tracked in git)
│   ├── version.yaml
│   ├── actions.yaml
│   ├── actions.graphql
│   ├── cron_triggers.yaml
│   ├── query_collections.yaml
│   ├── rest_endpoints.yaml
│   ├── remote_schemas.yaml
│   ├── allow_list.yaml
│   └── databases/
│       ├── databases.yaml
│       └── default/tables/tables.yaml
├── migrations/          # SQL migrations (tracked in git)
│   └── default/
└── seeds/               # Seed data (tracked in git)
    └── default/

Shell Wrapper

All scripts go through scripts/hasura.sh, which:

1. Loads .env if present (falls back to docker-compose defaults)
2. Injects --endpoint and --admin-secret automatically
3. Forwards all arguments to the local hasura-cli binary

To customize the endpoint or secret, copy .env.example to .env and edit.