Upgrading

This page collects version-specific upgrade notes. Read the section for every version newer than the one you currently run.

Upgrading to 0.3

0.3 changes the shape of config/kamal-backup.yml. The old flat YAML keys are no longer supported.

The goal is to make one Kamal deployment explicit: one app, multiple databases if needed, simple filesystem paths, restic settings, and one backup schedule.

Config shape

Before 0.3:

accessory: backup
app_name: chatwithwork
database_adapter: postgres
database_url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
backup_paths:
  - /data/storage
restic_repository: s3:https://s3.example.com/chatwithwork-backups
restic_init_if_missing: true
backup_schedule_seconds: 86400

In 0.3:

app: chatwithwork
accessory: backup

databases:
  - name: app
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
    password:
      secret: DATABASE_PASSWORD

paths:
  - /data/storage

restic:
  repository: s3:https://s3.example.com/chatwithwork-backups
  password:
    secret: RESTIC_PASSWORD
  init_if_missing: true

backup:
  schedule: 1d

Key mapping

  • app_name becomes app.
  • database_adapter and database_url move under databases.
  • sqlite_database_path becomes databases[].path.
  • backup_paths becomes paths.
  • restic_repository becomes restic.repository.
  • restic_init_if_missing becomes restic.init_if_missing.
  • backup_schedule_seconds: 86400 becomes backup.schedule: 1d.
  • state_dir becomes state.path.

Restic retention and check settings also move under restic:

restic:
  check_after_backup: true
  check_read_data_subset: 5%
  forget_after_backup: true
  retention:
    keep_last: 7
    keep_daily: 7
    keep_weekly: 4
    keep_monthly: 6
    keep_yearly: 2

Secrets

0.3 keeps secret values out of kamal-backup.yml. The YAML names the env var, and Kamal provides the value through env.secret.

For database passwords:

databases:
  - name: app
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
    password:
      secret: DATABASE_PASSWORD

Then pass that secret in Kamal:

accessories:
  backup:
    env:
      secret:
        - DATABASE_PASSWORD
        - RESTIC_PASSWORD
        - AWS_ACCESS_KEY_ID
        - AWS_SECRET_ACCESS_KEY

If the whole database URL is secret, use:

databases:
  - name: app
    adapter: postgres
    url:
      secret: DATABASE_URL

The same pattern works for restic:

restic:
  repository:
    secret: RESTIC_REPOSITORY
  password:
    secret: RESTIC_PASSWORD

Multiple databases

0.3 supports multiple databases within the same Kamal deployment:

databases:
  - name: app
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
    password:
      secret: APP_DATABASE_PASSWORD

  - name: solid_queue
    adapter: postgres
    url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_queue_production
    password:
      secret: SOLID_QUEUE_DATABASE_PASSWORD

This is for multiple databases or accessories inside one Kamal deployment. It is not intended for one backup accessory to cross into separate Kamal deployments.

Local overrides

If you had config/kamal-backup.local.yml, migrate it to the same shape:

databases:
  - name: app
    adapter: postgres
    url: postgres://localhost/chatwithwork_development

paths:
  - storage

state:
  path: tmp/kamal-backup

If production paths differ from local paths and you are not running through Kamal with -d or -c, set restore_from:

paths:
  - storage
restore_from:
  - /data/storage

Validate

After changing the config, run:

bundle exec kamal-backup validate

If validation reports a legacy key such as database_adapter, backup_paths, or restic_repository, that key still needs to be moved into the 0.3 shape.