shc export / import

The shc export and shc import commands provide app-defined, selective data extraction. Unlike backups which capture all DATA mounts, exports let apps define custom extraction logic for specific data items.

Overview

Exports are different from backups:

Feature	Backup	Export
Definition	Built into SHC	App-defined (`*.exporters.yaml`)
Granularity	All DATA mounts	Parameterized (one DB, one realm)
Execution	Converters (post-snapshot)	Jobs (live access)
Isolation	Network-isolated	Full stack access
Use case	Disaster recovery	Data migration, selective extract

Use Cases

Export one Keycloak realm (not all realms)
Export one PostgreSQL database (not all databases)
Export with custom format (JSON, CSV, custom dump)
Migrate specific data between environments

shc export

Export data using an app-defined exporter:

# Export a specific database
shc export postgres --export-stack mydb -p database=customers

# Export with custom format
shc export postgres --export-stack mydb -p database=orders -p format=plain

# Export to specific directory
shc export postgres --export-stack mydb -p database=mydb -d /tmp/mydb-export

# Export Keycloak realm
shc export realm --export-stack keycloak -p realm=my-realm

shc import

Import data using an app-defined importer:

# Import to a database
shc import postgres --stack mydb -p target_database=customers_copy

# Import with overwrite
shc import postgres --stack mydb -p target_database=staging -p overwrite=true

# Import from specific directory
shc import postgres --stack mydb -i /tmp/mydb-export

# Import Keycloak realm
shc import realm --stack keycloak -i /tmp/realm-export

Exporter Definition

Apps define exporters in *.exporters.yaml files:

schema:
  export:
    database:
      type: string
      required: true
    format:
      type: string
      default: "custom"
  import:
    target_database:
      type: string
      required: true
    overwrite:
      type: bool
      default: false

exporter_jobs:
  - name: dump-postgres
    context: container
    image: postgres:15-alpine
    command: |
      pg_dump -h {{ stack.host }} \
              -U {{ stack.username }} \
              -F {{ params.export.format }} \
              {{ params.export.database }} \
              > /output/{{ params.export.database }}.dump
    volumes:
      - output:/output
    environment:
      PGPASSWORD: !ref+vault://postgres_password

importer_jobs:
  - name: restore-postgres
    context: container
    image: postgres:15-alpine
    command: |
      pg_restore -h {{ stack.host }} \
                 -U {{ stack.username }} \
                 -d {{ params.import.target_database }} \
                 /input/*.dump
    volumes:
      - input:/input
    environment:
      PGPASSWORD: !ref+vault://postgres_password

Export Artifact Format (.exp)

Exports create .exp files using AR archive format:

export-{id}.exp (AR archive)
├── manifest.json     # Export manifest
└── data.tar.gz       # Exported data (compressed)

Manifest Structure

{
  "id": "exp-abc123",
  "timestamp": "2025-01-15T12:00:00Z",
  "version": "1",
  "tenant": "acme",
  "stack": "myapp",
  "environment": "production",
  "exporter": "postgres",
  "params": {
    "database": "mydb",
    "format": "custom"
  },
  "archives": {
    "data": { "size": 12345 }
  },
  "size": 12345
}

Examples

Export PostgreSQL Database

# Export a single database
$ shc export postgres --export-stack mydb -p database=customers

Exporting customers from mydb
  v Running dump-postgres job
  v Creating export artifact
Export complete: /var/lib/shc/exports/exp-20250115-abc123.exp (45 MB)

Import to Different Database

# Import to a new database name
$ shc import postgres --stack mydb -p target_database=customers_archive -i /tmp/customers-export

Importing to customers_archive
  v Running restore-postgres job
Import complete

Export Keycloak Realm

# Export specific realm configuration
$ shc export realm --export-stack keycloak -p realm=my-company

Exporting realm my-company from keycloak
  v Running export-realm job
Export complete: /var/lib/shc/exports/exp-20250115-def456.exp (2.3 MB)

Inspect Export

Read the manifest without extracting:

# Inspect export artifact
ar p export.exp manifest.json | jq .

# Output:
{
  "id": "exp-abc123",
  "exporter": "postgres",
  "params": {
    "database": "customers"
  },
  ...
}

Parameters

Export/import parameters are defined in the exporter’s schema:

Export Parameters (`-p` or `--param`)

# Single parameter
shc export postgres --export-stack mydb -p database=mydb

# Multiple parameters
shc export postgres --export-stack mydb -p database=mydb -p format=plain

# Using --param
shc export postgres --export-stack mydb --param database=mydb --param format=custom

Parameter Types

Type	Example
`string`	`-p database=mydb`
`bool`	`-p overwrite=true`
`int`	`-p limit=1000`

Flags

shc export

Flag	Default	Description
`<exporter>`	—	Exporter name (from app)
`--export-stack`	context	Source stack to export from
`-p, --param`	—	Parameter (can repeat)
`--output-dir`	auto	Output directory path
`-e`	default	Environment

shc import

Flag	Default	Description
`<exporter>`	—	Exporter name (from app)
`--stack`	—	Target stack (required)
`-i, --input`	—	Input directory or .exp file path
`-p, --param`	—	Parameter (can repeat)
`-e`	default	Environment

Available Exporters

List exporters available for a stack:

# Show exporters defined by an app
shc export --export-stack postgres --list

# Output:
Available exporters for postgres:
  postgres  - Export PostgreSQL database (params: database, format)

Creating Custom Exporters

Apps can define exporters in {app}.exporters.yaml:

schema:
  export:
    item_id:
      type: string
      required: true
  import:
    target_id:
      type: string
      required: true

exporter_jobs:
  - name: export-item
    context: container
    image: myapp-tools:latest
    command: myapp-cli export {{ params.export.item_id }} -o /output/
    volumes:
      - output:/output

importer_jobs:
  - name: import-item
    context: container
    image: myapp-tools:latest
    command: myapp-cli import {{ params.import.target_id }} -i /input/
    volumes:
      - input:/input

shc export / import

Overview

Use Cases

shc export

shc import

Exporter Definition

Export Artifact Format (.exp)

Manifest Structure

Examples

Export PostgreSQL Database

Import to Different Database

Export Keycloak Realm

Inspect Export

Parameters

Export Parameters (-p or --param)

Parameter Types

Flags

shc export

shc import

Available Exporters

Creating Custom Exporters

See Also

Export Parameters (`-p` or `--param`)