apply-hasura-metadata - SKILL.md Agent Skill

name: apply-hasura-metadata description: Apply local Hasura metadata changes (permissions, relationships, tracked tables) from nhost/metadata to the running Hasura instance. Use after editing files under nhost/metadata/ when the change must take effect without restarting the stack, or when a GraphQL error like "field 'X' not found in type 'Y_set_input'" means the live schema is out of sync with the YAML. user_invocable: true arguments:

name: env description: "Target environment: local (default) or prod" required: false

Apply Hasura metadata

Editing files under nhost/metadata/ does not change the running Hasura: metadata lives in the database and is only loaded at stack startup or when explicitly applied. After editing a nhost/metadata/**/*.yaml file (e.g. a table permission), apply it with one of the methods below, then verify.

Connection settings

Local (nhost dev stack):

ENDPOINT=https://local.hasura.local.nhost.run   # local.hasura.nhost.run also works
ADMIN_SECRET=nhost-admin-secret

Prod / other environments: never hardcode. Use the real endpoint and admin secret from the environment (e.g. $HASURA_GRAPHQL_ENDPOINT, $HASURA_GRAPHQL_ADMIN_SECRET) or your deploy pipeline. Prod metadata is normally applied through the deploy pipeline, not by hand. Confirm with the user before touching prod.

The local Hasura uses a self-signed cert. With hasura no extra flag is needed; with curl pass -k.

Method 1 — hasura CLI (preferred)

Applies the entire nhost/metadata directory in one shot. Must run from the nhost/ folder so it finds config.yaml (metadata_directory: metadata, version: 3) and the metadata/ dir.

cd nhost && hasura metadata apply \
  --endpoint https://local.hasura.nhost.run \
  --admin-secret nhost-admin-secret \
  --skip-update-check

Preview the parsed metadata without applying (sanity check):

cd nhost && hasura metadata apply --dry-run -o yaml \
  --endpoint https://local.hasura.nhost.run --admin-secret nhost-admin-secret --skip-update-check

Method 2 — curl fallback (no hasura CLI)

The metadata is split across many YAML files, so a raw replace_metadata curl is impractical. Instead apply the change for the single table you edited via the metadata API. The helper script reads the table's YAML and re-applies its *_permissions (drop + recreate) for every role:

python3 .claude/skills/apply-hasura-metadata/scripts/apply-table-metadata.py \
  nhost/metadata/databases/default/tables/public_role.yaml \
  --endpoint https://local.hasura.local.nhost.run \
  --admin-secret nhost-admin-secret

It only needs python3 (stdlib yaml + urllib) and reuses curl-equivalent HTTP calls to ${ENDPOINT}/v1/metadata. Pass --source if the DB source is not default.

If you only need Hasura to re-read DB columns/types after a schema change (not a permission edit), reload metadata directly:

curl -sk "${ENDPOINT}/v1/metadata" \
  -H "x-hasura-admin-secret: ${ADMIN_SECRET}" \
  -H 'content-type: application/json' \
  -d '{"type":"reload_metadata","args":{"reload_remote_schemas":false,"reload_sources":true}}'

Verify

Confirm the live schema matches the YAML. Introspect as the affected role (pass x-hasura-role), since Hasura generates a schema per role:

curl -sk "${ENDPOINT}/v1/graphql" \
  -H "x-hasura-admin-secret: ${ADMIN_SECRET}" \
  -H 'x-hasura-role: user' \
  -H 'content-type: application/json' \
  -d '{"query":"query{ __type(name:\"role_set_input\"){ inputFields{ name } } }"}'

Check that the expected field is present (or absent) for that role. Without the x-hasura-role header you get the admin schema, which always exposes every column and hides permission-scoped differences.

Notes

The YAML file under nhost/metadata/ is the source of truth and must be committed. Applying to the running instance is a separate step that does not modify the repo.
Do not commit without explicit user approval (project rule).
A permission's columns list controls which fields appear in <table>_set_input / <table>_insert_input for that role. A missing column there is the usual cause of field 'X' not found in type '<table>_set_input'.