Managing Hasura

Hasura Management Skill

Manage Hasura GraphQL Engine metadata, remote schemas, event triggers, actions, and permissions.

Core Helper Functions

#!/bin/bash

# Hasura endpoint configuration
HASURA_ENDPOINT="${HASURA_ENDPOINT:-http://localhost:8080}"
HASURA_ADMIN_SECRET="${HASURA_ADMIN_SECRET:-}"

# Hasura Metadata API wrapper
hasura_metadata() {
    local payload="$1"
    curl -s -X POST "${HASURA_ENDPOINT}/v1/metadata" \
        -H "Content-Type: application/json" \
        -H "X-Hasura-Admin-Secret: ${HASURA_ADMIN_SECRET}" \
        -d "$payload" | jq '.'
}

# Hasura Schema API wrapper
hasura_schema() {
    local payload="$1"
    curl -s -X POST "${HASURA_ENDPOINT}/v2/query" \
        -H "Content-Type: application/json" \
        -H "X-Hasura-Admin-Secret: ${HASURA_ADMIN_SECRET}" \
        -d "$payload" | jq '.'
}

# Health check
hasura_health() {
    curl -s "${HASURA_ENDPOINT}/healthz"
}

MANDATORY: Discovery-First Pattern

Always check Hasura health and inspect metadata before performing operations.

Phase 1: Discovery

#!/bin/bash

echo "=== Hasura Health ==="
hasura_health
echo ""

echo "=== Server Version ==="
curl -s "${HASURA_ENDPOINT}/v1/version" | jq '.'

echo ""
echo "=== Metadata Export Summary ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '{
    version: .version,
    sources: [.sources[] | {name, kind, tables_count: (.tables | length)}],
    remote_schemas: [(.remote_schemas // [])[] | .name],
    actions: [(.actions // [])[] | .name],
    custom_types: (.custom_types // {} | keys),
    cron_triggers: [(.cron_triggers // [])[] | .name],
    rest_endpoints: [(.rest_endpoints // [])[] | .name]
}'

echo ""
echo "=== Data Sources ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[.sources[] | {name, kind, tables: [.tables[] | .table.name]}]'

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Export metadata and filter with jq; never dump full metadata
• Summarize permission rules rather than listing every column

Common Operations

Metadata Management

#!/bin/bash

echo "=== Tracked Tables ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[.sources[] | {
    source: .name,
    tables: [.tables[] | {
        name: .table.name,
        schema: (.table.schema // "public"),
        relationships: ((.array_relationships // []) + (.object_relationships // []) | length),
        permissions: {
            select: (.select_permissions // [] | length),
            insert: (.insert_permissions // [] | length),
            update: (.update_permissions // [] | length),
            delete: (.delete_permissions // [] | length)
        }
    }]
}]'

echo ""
echo "=== Relationships ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[.sources[].tables[] | {
    table: .table.name,
    object_rels: [(.object_relationships // [])[] | .name],
    array_rels: [(.array_relationships // [])[] | .name]
}] | map(select((.object_rels | length > 0) or (.array_rels | length > 0)))'

echo ""
echo "=== Metadata Inconsistencies ==="
hasura_metadata '{"type": "get_inconsistent_metadata", "args": {}}' | jq '{
    is_consistent: .is_consistent,
    inconsistent_objects: [(.inconsistent_objects // [])[] | {type, reason: .reason, definition: .definition}]
}'

Remote Schema Management

#!/bin/bash

echo "=== Remote Schemas ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[(.remote_schemas // [])[] | {
    name,
    url: .definition.url,
    timeout_seconds: .definition.timeout_seconds,
    forward_client_headers: .definition.forward_client_headers,
    customization: (.definition.customization // "none")
}]'

echo ""
echo "=== Remote Schema Permissions ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[(.remote_schemas // [])[] | {
    name,
    permissions: [(.permissions // [])[] | {role: .role, allowed_types: (.definition.schema // "custom" | length)}]
}]'

Event Trigger Management

#!/bin/bash

echo "=== Event Triggers ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[.sources[].tables[] | select(.event_triggers) | .event_triggers[] | {
    name,
    table: .definition,
    webhook: .webhook,
    operations: [if .insert then "INSERT" else empty end, if .update then "UPDATE" else empty end, if .delete then "DELETE" else empty end],
    retry_conf: .retry_conf,
    headers_count: (.headers // [] | length)
}]'

echo ""
echo "=== Event Delivery Status ==="
hasura_schema '{"type": "run_sql", "args": {"sql": "SELECT trigger_name, status, count(*) as count FROM hdb_catalog.event_log GROUP BY trigger_name, status ORDER BY trigger_name, status", "source": "default"}}' 2>/dev/null \
    | jq '.result' || echo "Cannot query event log directly"

echo ""
echo "=== Pending Events ==="
hasura_schema '{"type": "run_sql", "args": {"sql": "SELECT trigger_name, count(*) FROM hdb_catalog.event_log WHERE delivered = false AND error = false AND archived = false GROUP BY trigger_name", "source": "default"}}' 2>/dev/null \
    | jq '.result' || echo "Cannot query pending events directly"

echo ""
echo "=== Cron Triggers ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[(.cron_triggers // [])[] | {name, webhook, schedule: .schedule, include_in_metadata: .include_in_metadata, retry_conf: .retry_conf}]'

Action Management

#!/bin/bash

echo "=== Actions ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[(.actions // [])[] | {
    name,
    kind: .definition.kind,
    handler: .definition.handler,
    type: .definition.type,
    forward_client_headers: .definition.forward_client_headers,
    permissions: [(.permissions // [])[] | .role],
    timeout: .definition.timeout
}]'

echo ""
echo "=== Custom Types ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '{
    input_objects: [(.custom_types.input_objects // [])[] | .name],
    objects: [(.custom_types.objects // [])[] | .name],
    scalars: [(.custom_types.scalars // [])[] | .name],
    enums: [(.custom_types.enums // [])[] | .name]
}'

echo ""
echo "=== REST Endpoints ==="
hasura_metadata '{"type": "export_metadata", "args": {}}' | jq '[(.rest_endpoints // [])[] | {name, url, methods: .methods, definition: .definition.query.query_name}]'

Safety Rules

• Read-only by default: Only use export_metadata, get_inconsistent_metadata, and read queries
• Never apply metadata changes without explicit user confirmation
• Never drop tracked tables or remove data sources without confirmation
• Never expose admin secrets, webhook URLs with embedded credentials, or database connection strings
• Test metadata changes: Use replace_metadata with allow_inconsistent_metadata: true to dry-run changes

Output Format

Present results as a structured report:

Managing Hasura Report
══════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Metadata inconsistencies: Adding tables that reference missing foreign keys causes inconsistent state; always check after changes
• Event trigger backlog: Undelivered events accumulate in hdb_catalog.event_log; monitor and clean up regularly
• Permission column sets: Forgetting to include new columns in select permissions means roles cannot see new data
• Remote schema conflicts: Naming collisions between remote schema types and local types cause build failures
• Migration ordering: Hasura migrations must be applied in order; out-of-order migrations cause metadata conflicts