# RelSpec job examples

Run these commands from this directory:

```bash
cd examples/jobs

# List every job from relspec.yml and the additional relspec.*.yml files.
relspec job list

# Validate a job and print its resolved plan without reading or writing data.
relspec job run build-schema --plan

# Build PostgreSQL DDL from the two DBML inputs.
relspec job run build-schema

# Run a job's dependency chain. This runs build-schema first, then build-json.
relspec job run build-json

# Inspect build-json's output. The from_job input adds the dependency automatically.
relspec job run lint-schema

# Extract only the posts table.
relspec job run posts-only

# List migration scripts in deterministic order without connecting to a database.
relspec job run migration-order

# Render one TypeScript file per table using the example template.
relspec job run generate-typescript

# Compare the two example schemas and write the summary to the logfile.
relspec job run compare-schemas

# Use an environment variable in an output path.
export VST=build/typescript
relspec job run generate-typescript --plan
relspec job run generate-typescript
```

Database jobs use environment variables for connection strings. Set them in
the shell before running the jobs; do not put connection strings in YAML:

```bash
export SOURCE_DB_URL='postgres://user:password@localhost/source_db'
export TARGET_DB_URL='postgres://user:password@localhost/target_db'

# Read the source database and write a local DBML snapshot.
relspec job run snapshot-database

# Preview migration execution without connecting to PostgreSQL.
relspec job run apply-migrations --plan

# Execute the migrations against TARGET_DB_URL.
relspec job run apply-migrations
```

The `apply-migrations` job demonstrates execution from multiple directories:

```yaml
script_dirs:
  - migrations/core
  - migrations/tenant
output:
  format: pgsql
  conn_env: TARGET_DB_URL
```

RelSpec combines the SQL files from both folders in deterministic order before
executing them against the configured PostgreSQL database.

To use a different directory or manifest, pass `--dir` or `--file`:

```bash
relspec job list --dir /path/to/project
relspec job run build-schema --file /path/to/project/relspec.yml --plan
```

See [../../docs/JOB_FILES.md](../../docs/JOB_FILES.md) for the complete job
file reference.