Works Background:
Hasura metadata management is not-easy:
-Version mismatches → broken deploys
-Manual sync → config drift
-No clear flow for New vs Existing Projects
This fixes it with a lightweight, self-healing, version-locked framework.
Core Principles
- Version-lock engine & CLI
- Idempotent, delta-driven
- Self-contained, no pre-mounts
How It Works
1. init.sh – Service Bootstrap
-Dependency & version check
-Self-heal: checksums itself + metadata-manager.sh
-Starts Hasura → waits for /healthz
2. metadata-manager.sh – Metadata Lifecycle
-New Project with no metadata: Export & apply canonical template.
-Existing Project with metadata: diff → validate → apply.
-Only apply to changed metadata,if no change=skip.
3.Overview
3.1 Workflow/Logic
3.2 FileFolders
Decide your Hasura metadata working folders on Day 0 — future-you (and your team) will thank present-you.
P.S.All paths in scripts & below table are EXAMPLE conventions,Do Use environment variables in actual deployment.
| Path | Source or Purpose | Description of Features |
|---|---|---|
/hasura-project/06-data/hasura/metadata/ |
Persistent directory (from host) | The original version of metadata written by the user, synchronized into the container by default from the local machine (i.e I use D:\canvas_envs\06-data\hasura\metadata). |
/hasura-project/user_metadata/ |
Temporary processing directory | All validation and apply operations are performed here, used as a staging area, cleared before each use to avoid contamination. |
/hasura-project/metadata/ |
Directory applied by Hasura | This is the path where hasura metadata apply is executed; must be non-existent before hasura init and cleared before apply operations. |
/hasura-project/01-config/hasura/metadata/ |
Standard template directory |
Read-only reference generated during initialization. Do not edit here — place your metadata in 06-data instead. |
P.S. ACTIVE_META_DIR="$ACTIVE_META/metadata" No List Above as Hasura CLI owns the folder,don’t pre-create or mount.
3.3 logs/Error Code Reference
Structure your logs and error codes early — especially in production and team(s) environment.
| Code | Meaning | Source Function | Suggested Action |
|---|---|---|---|
| 101 | Failed to remove existing directory | prepare_directory |
Check permissions / disk space |
| 102 | Failed to create directory | prepare_directory |
Check permissions / disk space |
| 103 | Directory creation validation failed | prepare_directory |
Filesystem inconsistency |
| 104 | Failed to purge mount-point content | prepare_directory |
Ensure mount is writable |
| 201 |
yq installation failed |
ensure_dependencies |
Check APT sources / network |
| 202 |
yamllint installation failed |
ensure_dependencies |
Check APT sources / network |
| 203 |
hasura CLI not found |
ensure_dependencies |
Install Hasura CLI |
| 301 | Failed to remove existing ACTIVE_META
|
initialize_template |
Check permissions |
| 302 |
hasura init failed |
initialize_template |
Ensure CLI works and directory is clean |
| 303 | Template version.yaml missing |
initialize_template |
Re-run init |
| 304 | Failed to prepare template repository | initialize_template |
Check TEMPLATE_DIR
|
| 305 | Template copy to TEMPLATE_DIR failed |
initialize_template |
Check permissions |
| 306 | Template archive validation failed | initialize_template |
Re-run init |
| 401 |
version.yaml missing |
validate_metadata |
Add version.yaml with "version": 3
|
| 402 | Invalid version in version.yaml
|
validate_metadata |
Set version to 3
|
| 410 | YAML syntax errors |
validate_metadata (yamllint) |
Fix YAML syntax |
| 420 | Invalid metadata structure |
validate_metadata (hasura metadata lint) |
Fix relationships / permissions |
| 430 | Metadata inconsistency with DB |
validate_metadata (hasura metadata inconsistency) |
Align DB schema with metadata |
| 501 | Failed to create runtime root | apply_metadata |
Check disk space |
| 502 | CLI workspace creation failed | apply_metadata |
Ensure ACTIVE_META is writable |
| 503 | Failed to clean CLI workspace | apply_metadata |
Check permissions |
| 504 | Copy from staging to workspace failed.document | apply_metadata |
Check source files / permissions |
| 505 |
hasura metadata apply failed |
apply_metadata |
Review Hasura logs |
| 506 | Persistent storage directory prep failed | apply_metadata |
Check SOURCE_DIR
|
| 507 | Snapshot copy to persistent storage failed | apply_metadata |
Check permissions |
| 508 | Persistent snapshot validation failed | apply_metadata |
Ensure version.yaml exists |
Results
Theory is gray,Implementation makes it green,Adopt and adapt your own version!
If this sparked an idea or saved you a debug session — a ⭐ means the world (and helps the next dev find it).
Interested in source code?
check Github:Free-to-download
Top comments (0)