hasura-docker-cli

What this skill does

# Hasura Docker CLI Skill

This skill guides you through using Hasura CLI in a self-hosted Docker Compose environment where the Hasura CLI runs inside a container.

## When This Skill Activates

Claude automatically uses this skill when you:

- Need to run Hasura CLI commands in self-hosted Docker environment
- Want to access Hasura console for schema changes
- Are managing database migrations via Hasura CLI
- Need to apply or rollback migrations
- Want to export or apply Hasura metadata
- Are troubleshooting Hasura configuration issues

## Self-Hosted Docker Architecture

In a self-hosted setup, the Hasura CLI runs inside a Docker container rather than on your host machine.

```
Self-Hosted Docker Stack:
┌──────────────────────────────────────────────────┐
│ console service (hasura/graphql-engine)          │
│ • Runs hasura-cli console command               │
│ • Port 9695: Hasura Console UI                  │
│ • Has hasura-cli installed                      │
│ • Working dir: /app (mounted nhost/ directory)  │
└──────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
│ graphql service (hasura/graphql-engine)         │
│ • Main Hasura GraphQL Engine                    │
│ • Port 8080: GraphQL API                        │
└──────────────────────────────────────────────────┘
```

## CRITICAL: Use Docker Exec for CLI Commands

**❌ TRADITIONAL HASURA CLI DOES NOT WORK DIRECTLY:**

```bash
# ❌ These fail because CLI is inside container
hasura-cli migrate status
hasura-cli metadata export
```

**✅ INSTEAD, USE DOCKER EXEC:**

```bash
# ✅ Correct way to access Hasura CLI in Docker
docker exec {console-container-name} hasura-cli [command]

# Example:
docker exec backend-console-1 hasura-cli version
docker exec backend-console-1 hasura-cli migrate status
```

## Finding Your Console Container Name

```bash
# List all containers to find the console
docker ps | grep console

# Common naming patterns:
# - backend-console-1
# - nhost-console-1
# - hasura-console-1
# - {project}-console-1
```

## Hasura Console Access

### Method 1: Web Browser (Recommended)

The Hasura Console is typically already running when your Docker stack is up:

```bash
# Console URL (configure in docker-compose.yaml)
http://localhost:9695

# Or via environment variable:
https://${CONSOLE_URL}
```

**Docker Compose Configuration:**

```yaml
services:
  console:
    image: hasura/graphql-engine:{version}
    entrypoint: ["hasura-cli"]
    command: ["console", "--no-browser", "--endpoint=http://graphql:8080"]
    ports:
      - "9695:9695"
    volumes:
      - ./nhost:/app  # Mount nhost directory
    working_dir: /app
```

This means:
- ✅ Console is always running when Docker stack is up
- ✅ Automatically tracks schema changes as migrations
- ✅ Accessible via browser at port 9695

### Method 2: Direct CLI Access

```bash
# Access the console container shell
docker exec -it {console-container-name} bash

# Inside container, run hasura-cli commands directly
hasura-cli migrate status
hasura-cli metadata export
```

## Common Hasura CLI Commands

All commands must be prefixed with `docker exec {container-name}`:

### Migration Management

```bash
# Set your container name as environment variable for convenience
export CONSOLE_CONTAINER={your-console-container-name}
export HASURA_ADMIN_SECRET={your-admin-secret}

# Check migration status
docker exec $CONSOLE_CONTAINER hasura-cli migrate status \
  --database-name default \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Apply pending migrations
docker exec $CONSOLE_CONTAINER hasura-cli migrate apply \
  --database-name default \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Create new migration
docker exec $CONSOLE_CONTAINER hasura-cli migrate create "add_users_table" \
  --database-name default \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Rollback last migration
docker exec $CONSOLE_CONTAINER hasura-cli migrate apply \
  --down 1 \
  --database-name default \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Rollback to specific version
docker exec $CONSOLE_CONTAINER hasura-cli migrate apply \
  --version {timestamp} \
  --database-name default \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET
```

### Metadata Management

```bash
# Export metadata
docker exec $CONSOLE_CONTAINER hasura-cli metadata export \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Apply metadata
docker exec $CONSOLE_CONTAINER hasura-cli metadata apply \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Reload metadata (refresh GraphQL schema)
docker exec $CONSOLE_CONTAINER hasura-cli metadata reload \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Check metadata inconsistencies
docker exec $CONSOLE_CONTAINER hasura-cli metadata inconsistency list \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET
```

### Seed Data Management

```bash
# Apply seed data
docker exec $CONSOLE_CONTAINER hasura-cli seed apply \
  --database-name default \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET

# Apply specific seed file
docker exec $CONSOLE_CONTAINER hasura-cli seed apply \
  --file seeds/default/1234_initial_data.sql \
  --database-name default \
  --endpoint http://graphql:8080 \
  --admin-secret $HASURA_ADMIN_SECRET
```

## Environment Variables

The Hasura CLI typically needs these environment variables:

```bash
# Inside the console container (configured in docker-compose.yaml)
HASURA_GRAPHQL_ADMIN_SECRET=${GRAPHQL_ADMIN_SECRET}
HASURA_GRAPHQL_DATABASE_URL=postgres://${PGUSER}:${PGPASSWORD}@${PGHOST}:${PGPORT}/${PGDATABASE}
```

## Working Directory

The console container should mount your project directory:

```yaml
# In docker-compose.yaml
volumes:
  - ./nhost:/app
working_dir: /app
```

This means the CLI can find:
- `/app/config.yaml` - Hasura config
- `/app/migrations/` - Migration files
- `/app/metadata/` - Metadata files
- `/app/seeds/` - Seed files

## Simplified Helper Aliases (Optional)

Create shell aliases for convenience:

```bash
# Add to ~/.bashrc or ~/.zshrc
export CONSOLE_CONTAINER={your-container-name}
export HASURA_ADMIN_SECRET=${GRAPHQL_ADMIN_SECRET}

alias hasura='docker exec $CONSOLE_CONTAINER hasura-cli'

# Then use like:
hasura migrate status --database-name default
hasura metadata export
```

## Complete Migration Workflow

**Scenario: Add a new database table**

```bash
# 1. Open Hasura Console in browser
open http://localhost:9695

# 2. Make schema changes via UI
#    - Go to DATA tab
#    - Click "Create Table"
#    - Define columns, constraints, relationships
#    - Save

# 3. Console automatically creates migration files in:
#    nhost/migrations/default/{timestamp}_{operation}/
#    ├── up.sql    (forward migration)
#    └── down.sql  (rollback migration)

# 4. Check migration status
docker exec $CONSOLE_CONTAINER hasura-cli migrate status \
  --database-name default \
  --endpoint http://graphql:8080

# 5. If needed, manually apply migrations
docker exec $CONSOLE_CONTAINER hasura-cli migrate apply \
  --database-name default \
  --endpoint http://graphql:8080

# 6. Export metadata to sync permissions
docker exec $CONSOLE_CONTAINER hasura-cli metadata export \
  --endpoint http://graphql:8080

# 7. Reload Hasura metadata
docker exec $CONSOLE_CONTAINER hasura-cli metadata reload \
  --endpoint http://graphql:8080

# 8. Commit migration files
git add nhost/migrations/
git add nhost/metadata/
git commit -m "feat(db): add users table"
```

## Troubleshooting

### Issue: Cannot connect to Hasura

**Symptoms:**
- `docker exec` commands fail
- "No such container" error

**Solutions:**

```bash
# 1. Check if console container is running
docker ps | grep console

# 2. If not running, start Docker stack
docker compose up -d

# 3. Wait f