shc job
Jobs in SHC execute commands at specific points during stack lifecycle operations or on-demand. The shc job commands let you list, run, and monitor jobs.
Overview
Section titled “Overview”Jobs execute commands with full access to stack mounts and networking. They are used when operations need to interact with running services or access live data.
Job Contexts
Section titled “Job Contexts”| Context | Description | Use Case |
|---|---|---|
service | Execute in an existing running service | CHECKPOINT on running DB |
container | Spin up ephemeral container with stack access | Migration scripts, data jobs |
http | Make HTTP request to a service | Health checks, API calls |
Jobs vs Converters
Section titled “Jobs vs Converters”| Aspect | Jobs | Converters |
|---|---|---|
| When runs | While deployment is running | After snapshot, deployment resumed |
| Network | Full stack network access | network_mode: none (isolated) |
| Mounts | Live volumes (read/write) | Snapshot (read-only) + output dir |
| Purpose | Interact with services | Transform data into backup format |
| Used by | Hooks, restore, integrations | Backups only |
shc job ls
Section titled “shc job ls”List jobs defined for a stack:
# List all jobs for a stackshc job ls -s myapp
# Machine-readable, or a chosen column setshc job ls -s myapp -o jsonshc job ls -s myapp --fields name,hook,contextOutput
Section titled “Output”$ shc job ls -s postgres
Jobs for postgres:
Name Context Hook Description ──────────────────────────────────────────────────────── flush_checkpoint service pre_backup Flush DB checkpoint create_database service integration Create user database migrate container post_install Run database migrations health_check http - Check service healthshc job run
Section titled “shc job run”Run a job manually:
The job name is a positional argument, and the run is queued
asynchronously unless you pass -w/--wait:
# Run a specific jobshc job run migrate --stack myapp
# Run with variable overridesshc job run migrate --stack myapp --var FORCE=true
# Block until the run finishes and print its outputshc job run long_task --stack myapp --waitshc job run takes no timeout or dry-run flag: a job’s timeout is
declared in the app’s jobs.yaml, and there is no preview mode.
Output
Section titled “Output”$ shc job run flush_checkpoint --stack postgres --wait
Running job: flush_checkpoint Context: service (postgres) Command: psql -c "CHECKPOINT"
Output:CHECKPOINT
Job completed successfully (0.3s)shc job status
Section titled “shc job status”Show one job run, addressed by the numeric run ID that shc job run
printed. It takes no --job name, because a job name does not identify a run:
# Show one job runshc job status 4213
# As JSONshc -o json job status 4213To find a run ID, list runs instead: shc job ps (running) and
shc job history (completed and failed) both take --job to filter by
job name and inherit -s/--stack:
shc job ps --stack myapp --job migrateshc job history --stack myapp --job migrate --limit 5Output
Section titled “Output”$ shc job status --stack myapp
Recent jobs for myapp:
Job Started Duration Status ──────────────────────────────────────────────── migrate 2025-01-15 12:30:00 2.3s success migrate 2025-01-14 10:15:00 2.1s success seed 2025-01-14 10:15:05 0.8s successJob Definition
Section titled “Job Definition”Jobs are defined in *.job.yaml files within the app directory:
Service Context
Section titled “Service Context”Runs command inside an existing running container:
name: flush_checkpointcontext: serviceservice: postgrescommand: psql -c "CHECKPOINT"timeout: 60Properties:
| Property | Type | Description |
|---|---|---|
service | string | Service name from compose (required) |
command | string | Command to execute (required) |
user | string | Run as specific user |
working_dir | string | Working directory inside container |
Container Context
Section titled “Container Context”Spins up an ephemeral container with stack network access:
name: migratecontext: containerimage: myapp:latestcommand: python manage.py migrate --noinputvolumes: - app_data:/app/dataenvironment: DATABASE_URL: "{{ integrations.postgres.socket.url }}"timeout: 300Properties:
| Property | Type | Description |
|---|---|---|
image | string | Docker image to use (required) |
command | string | Command to execute (required) |
volumes | list[string] | Volume mounts |
environment | dict | Environment variables |
networks | list[string] | Networks to attach (defaults to stack networks) |
user | string | Run as specific user |
working_dir | string | Working directory |
labels | dict | Container labels |
HTTP Context
Section titled “HTTP Context”Makes HTTP request to a service (no container created):
name: health_checkcontext: httpurl: http://web:8080/healthmethod: GETtimeout: 30name: notify_slackcontext: httpurl: "{{ vars.slack_webhook }}"method: POSTheaders: Content-Type: application/jsonbody: text: "Deployment of {{ stack }} complete"retry: 3Properties:
| Property | Type | Default | Description |
|---|---|---|---|
url | string | none | URL to request (required) |
method | string | GET | HTTP method |
headers | dict | none | Request headers |
body | string/dict/list | none | Request body (JSON) |
retry | integer | 0 | Retry attempts |
Common Job Properties
Section titled “Common Job Properties”All job contexts share these properties:
| Property | Type | Default | Description |
|---|---|---|---|
name | string | none | Job name (required) |
context | string | none | service, container, http |
timeout | integer | 300 | Timeout in seconds |
retry | integer | 0 | Number of retries (with exponential backoff) |
Lifecycle Hooks
Section titled “Lifecycle Hooks”Jobs are commonly referenced in lifecycle hooks:
hooks: post_install: - migrate - seed_data post_upgrade: - migrate pre_backup: - flush_checkpoint post_restore: - rebuild_indexesSupported Hooks
Section titled “Supported Hooks”| Hook | When | Stack State | Use Case |
|---|---|---|---|
pre_install | Before deployment | Not running | Validation |
post_install | After containers healthy | Running | Migrations, initial setup |
pre_upgrade | Before upgrade starts | Running | Pre-flight checks |
post_upgrade | After upgrade completes | Running | Schema migrations |
pre_uninstall | Before containers stop | Running | Graceful shutdown |
post_uninstall | After containers removed | Not running | External cleanup |
pre_backup | Before snapshot | Running (paused) | Quiesce writes |
post_backup | After backup completes | Running | Resume operations |
pre_restore | Before the stack stops | Running | Refuse a restore |
post_restore | After restore completes | Running | Rebuild indexes |
Examples
Section titled “Examples”Database Migration Job
Section titled “Database Migration Job”name: migratecontext: serviceservice: webcommand: python manage.py migrate --noinputhooks: post_install: - migrate post_upgrade: - migratePre-Backup Checkpoint
Section titled “Pre-Backup Checkpoint”name: checkpointcontext: serviceservice: postgrescommand: psql -c "CHECKPOINT"hooks: pre_backup: - checkpointNotification Webhook
Section titled “Notification Webhook”name: notifycontext: httpurl: "{{ vars.webhook_url }}"method: POSTheaders: Content-Type: application/jsonbody: event: "deployment_complete" stack: "{{ stack }}" environment: "{{ environment }}"retry: 3Data Seeding Job
Section titled “Data Seeding Job”name: seedcontext: containerimage: myapp:latestcommand: python manage.py seed_datavolumes: - seed_data:/app/seeds:roenvironment: DATABASE_URL: "{{ integrations.postgres.socket.url }}"Failure Behavior
Section titled “Failure Behavior”If a job fails, SHC logs a warning and continues to the next job. Use retry for jobs with transient failures:
name: notify_webhookcontext: httpurl: "{{ vars.webhook_url }}"retry: 3 # Retry up to 3 times with exponential backoffFor critical jobs that must succeed, the operation will fail if the job fails (e.g., pre_install hooks failing will abort installation).