kamal-backup 0.2.10 → 0.3.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e3653f6bad9c7d736b7617e059bfd19263854ab96596bfb54191129a4b438fc
-  data.tar.gz: f3ecbde3269e9f3aee1c9bb227bce2b054abaddfa3c732c6aff4eecc24b1c8b6
+  metadata.gz: 55945234709fcf743588fe6fadf7873ff43dcc832a2bc8303e42ba67e15c13db
+  data.tar.gz: a3e05e3428bdcceafa37d2dc2f0cdea53d50e204f7c9345e38308be0085ba9ea
 SHA512:
-  metadata.gz: 4974fc0bea1a6b2212d0bf7a968fd2dbc993bfdfdeeb13ae37989ab8d43d7932ce3e20f691b62ce0c744e307b560da19ca4b169f935a8353ffa1317c270af919
-  data.tar.gz: 2904cb1a0481b49f61914d082ae2113358000abebe98ace0789c4eaf1993ed1102758030a58bf80c6afc61c7c79bc1da613749cbb5579a2ff584edaa2d2fa87e
+  metadata.gz: f23ce66cf13a8b420d6171e16489f2c4e2bc44c522b222637eac0ac809e1092e8634396589a1ea4b58c9f01e3ef446f57e4b8f38a157be3423e482cbe8bd2e9a
+  data.tar.gz: 103ff0d7ffb950b7f6927a8c22591e7f91c8cc06d5456bb04a6b119eda21f7198aa949375d19e3689040db34c8c2a4dc8ed4b2ab6e59911672e4b9033b700fe5

data/README.md

@@ -4,7 +4,7 @@
 
 <h1>kamal-backup</h1>
 
-<strong>The easiest way to run scheduled backups for a Rails app deployed with Kamal.</strong>
+<strong>Add scheduled Rails backups to Kamal with one accessory.</strong>
 
 [![Gem Version](https://img.shields.io/gem/v/kamal-backup.svg)](https://rubygems.org/gems/kamal-backup)
 [![CI](https://github.com/crmne/kamal-backup/actions/workflows/ci.yml/badge.svg)](https://github.com/crmne/kamal-backup/actions/workflows/ci.yml)
@@ -20,7 +20,7 @@ Backups for Rails apps deployed with Kamal should not become a separate ops proj
 
 `kamal-backup` is one Kamal accessory that runs encrypted backups for your Rails database and file-backed Active Storage files on a schedule. It also gives you restore drills and redacted evidence for security reviews like CASA.
 
-If you already deploy with Kamal, backups should feel like adding one more accessory.
+Run `kamal-backup init`, fill in one config file, add the accessory, then boot it. If you already deploy with Kamal, backups should feel like adding one more accessory.
 
 ## Why Rails teams use it
 
@@ -28,11 +28,11 @@ Most self-hosted Rails apps need the same things:
 
 - scheduled backups for PostgreSQL, MySQL/MariaDB, or SQLite
 - file-backed Active Storage backups from mounted volumes
-- a fast way to restore production data locally
+- local restores for inspecting production data safely
 - restore drills that do not touch the live production database
 - evidence that says more than "the backup ran"
 
-`kamal-backup` packages that workflow into a small Ruby gem, a production accessory image, and a restic repository.
+`kamal-backup` wraps that workflow in a small Ruby gem and a production accessory image backed by a restic repository.
 
 ## Quick start
 
@@ -62,7 +62,7 @@ accessories:
       - config/kamal-backup.yml:/app/config/kamal-backup.yml:ro
     env:
       secret:
-        - PGPASSWORD
+        - DATABASE_PASSWORD
         - RESTIC_PASSWORD
         - AWS_ACCESS_KEY_ID
         - AWS_SECRET_ACCESS_KEY
@@ -76,15 +76,23 @@ For SQLite databases stored on the mounted storage volume, omit `:ro` from that
 Put the backup settings in `config/kamal-backup.yml`:
 
 ```yaml
+app: chatwithwork
 accessory: backup
-app_name: chatwithwork
-database_adapter: postgres
-database_url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
-backup_paths:
+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
-restic_init_if_missing: true
-backup_schedule_seconds: 86400
+restic:
+  repository: s3:https://s3.example.com/chatwithwork-backups
+  password:
+    secret: RESTIC_PASSWORD
+  init_if_missing: true
+backup:
+  schedule: 1d
 ```
 
 Boot it. The container runs `kamal-backup schedule` by default:
@@ -95,22 +103,23 @@ bin/kamal accessory boot backup
 bin/kamal accessory logs backup
 ```
 
-Run the first backup and print evidence. From an app checkout with `config/deploy.yml`, these commands shell out through Kamal to the backup accessory:
+Run the first backup, check the repository, and print evidence. From an app checkout with `config/deploy.yml`, these commands shell out through Kamal to the backup accessory:
 
 ```sh
 bundle exec kamal-backup backup
 bundle exec kamal-backup list
+bundle exec kamal-backup check
 bundle exec kamal-backup evidence
 ```
 
 ## What you get
 
-- **Scheduled backups:** the accessory runs continuously and backs up on `backup_schedule_seconds`.
+- **Scheduled backups:** the accessory runs continuously and backs up on `backup.schedule`.
 - **Database and Active Storage coverage:** database dumps plus file-backed Active Storage files from mounted volumes.
 - **Restic underneath:** encrypted, deduplicated snapshots in S3-compatible storage, a restic REST server, or a filesystem repository.
-- **Local restores:** pull production backups into your local Rails app when you need to inspect real data.
-- **Restore drills:** restore into scratch production-side targets and record the result.
-- **Security review evidence:** `kamal-backup evidence` prints redacted JSON with latest snapshots, checks, drills, retention, and tool versions.
+- **Local restores:** inspect production data safely in your local Rails app.
+- **Restore drills:** restore into scratch production-side targets, run verification commands, and record the result.
+- **Security review evidence:** `kamal-backup evidence` prints redacted JSON with latest snapshots, `kamal-backup check` results, drills, retention, and tool versions.
 
 ## Docs
 
@@ -132,9 +141,9 @@ Run the release helper from a clean `master` checkout:
 bin/release 0.2.9
 ```
 
-It updates `lib/kamal_backup/version.rb`, runs the test suite and docs build, commits `Release 0.2.9`, creates `v0.2.9`, and pushes `master` plus the tag. CI publishes the RubyGem, Docker image tags, GitHub release, and docs from that release commit.
+It updates `lib/kamal_backup/version.rb`, runs the test suite and docs build, commits `Release 0.2.9`, and pushes `master`. CI publishes the RubyGem and Docker image tags first, then creates `v0.2.9`, the GitHub release, and the docs deployment from the release commit.
 
-Use `bin/release 0.2.9 --no-push` to prepare the commit and tag locally without publishing.
+Use `bin/release 0.2.9 --no-push` to prepare the commit locally without publishing.
 
 ## License
 

data/lib/kamal_backup/app.rb

@@ -33,7 +33,7 @@ module KamalBackup
 
       timestamp = current_timestamp
       restic.ensure_repository
-      database.backup(restic, timestamp)
+      databases.each { |database| database.backup(restic, timestamp) }
       restic.backup_paths(config.backup_paths, tags: ["type:files", "run:#{timestamp}"])
 
       if config.forget_after_backup?
@@ -57,14 +57,10 @@ module KamalBackup
       require_restic!
 
       build_restore_result("local", snapshot) do |result|
-        adapter = database
-        validate_local_machine_database_target(adapter)
-        result[:database] = perform_database_restore_to_current(snapshot, adapter: adapter)
-        result[:files] = perform_replacement_file_restore(
-          snapshot,
-          source_paths: config.local_restore_source_paths,
-          target_paths: config.backup_paths
-        )
+        databases.each { |adapter| validate_local_machine_database_target(adapter) }
+        database_results = perform_database_restores_to_current(snapshot)
+        file_results = perform_replacement_file_restores(snapshot, production_source: false)
+        assign_restore_results(result, database_results, file_results)
       end
     end
 
@@ -73,13 +69,9 @@ module KamalBackup
       require_restic!
 
       build_restore_result("production", snapshot) do |result|
-        adapter = database
-        result[:database] = perform_database_restore_to_current(snapshot, adapter: adapter)
-        result[:files] = perform_replacement_file_restore(
-          snapshot,
-          source_paths: config.backup_paths,
-          target_paths: config.backup_paths
-        )
+        database_results = perform_database_restores_to_current(snapshot)
+        file_results = perform_replacement_file_restores(snapshot, production_source: true)
+        assign_restore_results(result, database_results, file_results)
       end
     end
 
@@ -88,14 +80,10 @@ module KamalBackup
       require_restic!
 
       run_drill("local", snapshot, check_command: check_command) do |result|
-        adapter = database
-        validate_local_machine_database_target(adapter)
-        result[:database] = perform_database_restore_to_current(snapshot, adapter: adapter)
-        result[:files] = perform_replacement_file_restore(
-          snapshot,
-          source_paths: config.local_restore_source_paths,
-          target_paths: config.backup_paths
-        )
+        databases.each { |adapter| validate_local_machine_database_target(adapter) }
+        database_results = perform_database_restores_to_current(snapshot)
+        file_results = perform_replacement_file_restores(snapshot, production_source: false)
+        assign_restore_results(result, database_results, file_results)
       end
     end
 
@@ -104,14 +92,16 @@ module KamalBackup
       require_restic!
 
       run_drill("production", snapshot, check_command: check_command) do |result|
-        adapter = database
-        result[:database] = perform_database_restore_to_scratch(
-          snapshot,
-          adapter: adapter,
-          database_name: database_name,
-          sqlite_path: sqlite_path
-        )
-        result[:files] = perform_file_restore(snapshot, target: file_target)
+        database_results = databases.map do |adapter|
+          perform_database_restore_to_scratch(
+            snapshot,
+            adapter: adapter,
+            database_name: database_name,
+            sqlite_path: sqlite_path
+          )
+        end
+        file_results = [perform_file_restore(snapshot, target: file_target)]
+        assign_restore_results(result, database_results, file_results)
       end
     end
 
@@ -160,7 +150,9 @@ module KamalBackup
           finished_at: nil,
           error: nil,
           database: nil,
-          files: nil
+          databases: [],
+          files: nil,
+          paths: nil
         )
         yield(result)
         result[:finished_at] = Time.now.utc.iso8601
@@ -179,7 +171,9 @@ module KamalBackup
           finished_at: nil,
           error: nil,
           database: nil,
+          databases: [],
           files: nil,
+          paths: nil,
           check: nil
         )
 
@@ -206,8 +200,8 @@ module KamalBackup
       end
 
       def perform_database_restore_to_current(snapshot, adapter:)
-        resolved_snapshot = resolve_snapshot(snapshot, tags: ["type:database", "adapter:#{adapter.adapter_name}"])
-        filename = restic.database_file(resolved_snapshot, adapter.adapter_name)
+        resolved_snapshot = resolve_snapshot(snapshot, tags: database_snapshot_tags(adapter))
+        filename = restic.database_file(resolved_snapshot, adapter.adapter_name, database_name: database_config_name(adapter))
 
         if filename
           adapter.restore_to_current(restic, resolved_snapshot, filename)
@@ -219,8 +213,8 @@ module KamalBackup
 
       def perform_database_restore_to_scratch(snapshot, adapter:, database_name:, sqlite_path:)
         target = scratch_database_target(adapter, database_name, sqlite_path)
-        resolved_snapshot = resolve_snapshot(snapshot, tags: ["type:database", "adapter:#{adapter.adapter_name}"])
-        filename = restic.database_file(resolved_snapshot, adapter.adapter_name)
+        resolved_snapshot = resolve_snapshot(snapshot, tags: database_snapshot_tags(adapter))
+        filename = restic.database_file(resolved_snapshot, adapter.adapter_name, database_name: database_config_name(adapter))
 
         if filename
           adapter.restore_to_scratch(restic, resolved_snapshot, filename, target: target)
@@ -230,6 +224,40 @@ module KamalBackup
         end
       end
 
+      def perform_database_restores_to_current(snapshot)
+        databases.map { |adapter| perform_database_restore_to_current(snapshot, adapter: adapter) }
+      end
+
+      def perform_replacement_file_restores(snapshot, production_source:)
+        source_paths = production_source ? config.backup_paths : config.local_restore_source_paths
+        [
+          perform_replacement_file_restore(
+            snapshot,
+            source_paths: source_paths,
+            target_paths: config.backup_paths
+          )
+        ]
+      end
+
+      def assign_restore_results(result, database_results, file_results)
+        result[:databases] = database_results
+        result[:database] = database_results.first
+        result[:paths] = file_results.first
+        result[:files] = file_results.size == 1 ? file_results.first : file_results
+      end
+
+      def database_snapshot_tags(adapter)
+        ["type:database", "database:#{database_config_name(adapter)}", "adapter:#{adapter.adapter_name}"]
+      end
+
+      def database_config_name(adapter)
+        if adapter.respond_to?(:config) && adapter.config.respond_to?(:database_name)
+          adapter.config.database_name
+        else
+          config.database_name
+        end
+      end
+
       def perform_file_restore(snapshot, target:)
         resolved_snapshot = resolve_snapshot(snapshot, tags: ["type:files"])
         validated_target = config.validate_file_restore_target(target)
@@ -290,9 +318,11 @@ module KamalBackup
       def scratch_database_target(adapter, database_name, sqlite_path)
         case adapter.adapter_name
         when "sqlite"
-          sqlite_path || raise(ConfigurationError, "scratch SQLite path is required")
+          target = sqlite_path || raise(ConfigurationError, "scratch SQLite path is required")
+          databases.size > 1 ? File.join(target, "#{database_config_name(adapter)}.sqlite3") : target
         else
-          database_name || raise(ConfigurationError, "scratch database name is required")
+          target = database_name || raise(ConfigurationError, "scratch database name is required")
+          databases.size > 1 ? "#{target}_#{database_config_name(adapter)}" : target
         end
       end
 
@@ -313,11 +343,13 @@ module KamalBackup
         config.validate_database_backup
         config.validate_file_restore_target(file_target)
 
-        case database.adapter_name
-        when "sqlite"
-          raise ConfigurationError, "scratch SQLite path is required" if sqlite_path.to_s.strip.empty?
-        else
-          raise ConfigurationError, "scratch database name is required" if database_name.to_s.strip.empty?
+        databases.each do |adapter|
+          case adapter.adapter_name
+          when "sqlite"
+            raise ConfigurationError, "scratch SQLite path is required" if sqlite_path.to_s.strip.empty?
+          else
+            raise ConfigurationError, "scratch database name is required" if database_name.to_s.strip.empty?
+          end
         end
       end
 
@@ -373,7 +405,17 @@ module KamalBackup
       end
 
       def database
-        @database ||= Databases::Base.build(config, redactor: redactor)
+        databases.first
+      end
+
+      def databases
+        @databases ||= begin
+          if @database
+            Array(@database)
+          else
+            config.databases.map { |database_config| Databases::Base.build(database_config, redactor: redactor) }
+          end
+        end
       end
 
       def resolve_snapshot(argument, tags:)

data/lib/kamal_backup/cli.rb

@@ -218,15 +218,23 @@ module KamalBackup
 
       def shared_config_template
         <<~YAML
+          app: your-app
           accessory: backup
-          app_name: your-app
-          database_adapter: postgres
-          database_url: postgres://your-app@your-db:5432/your_app_production
-          backup_paths:
+          databases:
+            - name: app
+              adapter: postgres
+              url: postgres://your-app@your-db:5432/your_app_production
+              password:
+                secret: DATABASE_PASSWORD
+          paths:
             - /data/storage
-          restic_repository: s3:https://s3.example.com/your-app-backups
-          restic_init_if_missing: true
-          backup_schedule_seconds: 86400
+          restic:
+            repository: s3:https://s3.example.com/your-app-backups
+            password:
+              secret: RESTIC_PASSWORD
+            init_if_missing: true
+          backup:
+            schedule: 1d
         YAML
       end
 
@@ -240,7 +248,7 @@ module KamalBackup
                 - config/kamal-backup.yml:/app/config/kamal-backup.yml:ro
               env:
                 secret:
-                  - PGPASSWORD
+                  - DATABASE_PASSWORD
                   - RESTIC_PASSWORD
                   - AWS_ACCESS_KEY_ID
                   - AWS_SECRET_ACCESS_KEY
@@ -450,7 +458,7 @@ module KamalBackup
       puts
       puts deploy_snippet
       puts
-      puts "The accessory runs scheduled database and Active Storage backups with backup_schedule_seconds."
+      puts "The accessory runs scheduled database and file backups with backup.schedule."
       puts "For most Rails apps, restore local and drill local can infer the development database, Active Storage path, and tmp state directory."
       puts "Local restore and drill also require the restic binary on your machine."
       puts "Create config/kamal-backup.local.yml only if you need to override those local defaults."

data/lib/kamal_backup/config.rb

@@ -17,42 +17,130 @@ module KamalBackup
     SHARED_CONFIG_PATH = "config/kamal-backup.yml"
     LOCAL_CONFIG_PATH = "config/kamal-backup.local.yml"
     DEFAULT_CONFIG_PATHS = [SHARED_CONFIG_PATH, LOCAL_CONFIG_PATH].freeze
-    YAML_KEY_ALIASES = {
-      "app_name" => "APP_NAME",
-      "database_adapter" => "DATABASE_ADAPTER",
-      "database_url" => "DATABASE_URL",
-      "sqlite_database_path" => "SQLITE_DATABASE_PATH",
-      "backup_paths" => "BACKUP_PATHS",
-      "local_restore_source_paths" => "LOCAL_RESTORE_SOURCE_PATHS",
-      "accessory" => "KAMAL_BACKUP_ACCESSORY",
-      "restic_repository" => "RESTIC_REPOSITORY",
-      "restic_repository_file" => "RESTIC_REPOSITORY_FILE",
-      "restic_password" => "RESTIC_PASSWORD",
-      "restic_password_file" => "RESTIC_PASSWORD_FILE",
-      "restic_password_command" => "RESTIC_PASSWORD_COMMAND",
-      "restic_init_if_missing" => "RESTIC_INIT_IF_MISSING",
-      "restic_check_after_backup" => "RESTIC_CHECK_AFTER_BACKUP",
-      "restic_check_read_data_subset" => "RESTIC_CHECK_READ_DATA_SUBSET",
-      "restic_forget_after_backup" => "RESTIC_FORGET_AFTER_BACKUP",
-      "restic_keep_last" => "RESTIC_KEEP_LAST",
-      "restic_keep_daily" => "RESTIC_KEEP_DAILY",
-      "restic_keep_weekly" => "RESTIC_KEEP_WEEKLY",
-      "restic_keep_monthly" => "RESTIC_KEEP_MONTHLY",
-      "restic_keep_yearly" => "RESTIC_KEEP_YEARLY",
-      "backup_schedule_seconds" => "BACKUP_SCHEDULE_SECONDS",
-      "backup_start_delay_seconds" => "BACKUP_START_DELAY_SECONDS",
-      "state_dir" => "KAMAL_BACKUP_STATE_DIR",
-      "allow_suspicious_paths" => "KAMAL_BACKUP_ALLOW_SUSPICIOUS_PATHS",
-      "pgpassword" => "PGPASSWORD",
-      "mysql_pwd" => "MYSQL_PWD"
-    }.freeze
+    TOP_LEVEL_YAML_KEYS = %w[app accessory databases paths restore_from restic backup state].freeze
+    LEGACY_YAML_KEYS = %w[
+      app_name
+      database_adapter
+      database_url
+      sqlite_database_path
+      backup_paths
+      local_restore_source_paths
+      restic_repository
+      restic_repository_file
+      restic_password
+      restic_password_file
+      restic_password_command
+      restic_init_if_missing
+      restic_check_after_backup
+      restic_check_read_data_subset
+      restic_forget_after_backup
+      restic_keep_last
+      restic_keep_daily
+      restic_keep_weekly
+      restic_keep_monthly
+      restic_keep_yearly
+      backup_schedule_seconds
+      backup_start_delay_seconds
+      state_dir
+      allow_suspicious_paths
+      pgpassword
+      mysql_pwd
+    ].freeze
+    ConfigData = Struct.new(:env, :database_definitions, :path_definitions, :restore_from_definitions, keyword_init: true) do
+      def self.empty
+        new(env: {}, database_definitions: nil, path_definitions: nil, restore_from_definitions: nil)
+      end
+    end
+
+    class DatabaseSource
+      CONNECTION_KEYS = %w[
+        DATABASE_URL
+        SQLITE_DATABASE_PATH
+        PGHOST
+        PGPORT
+        PGUSER
+        PGPASSWORD
+        PGDATABASE
+        PGSSLMODE
+        PGSSLROOTCERT
+        PGSSLCERT
+        PGSSLKEY
+        PGCONNECT_TIMEOUT
+        PGSERVICE
+        PGPASSFILE
+        MYSQL_HOST
+        MYSQL_PORT
+        MYSQL_USER
+        MYSQL_PWD
+        MYSQL_PASSWORD
+        MYSQL_DATABASE
+        MARIADB_HOST
+        MARIADB_PORT
+        MARIADB_USER
+        MARIADB_PASSWORD
+        MARIADB_DATABASE
+      ].freeze
+
+      attr_reader :missing_secrets, :name, :parent
+
+      def initialize(parent:, name:, adapter:, env:, structured:, missing_secrets: [])
+        @parent = parent
+        @name = name.to_s
+        @adapter = adapter
+        @env = env.transform_keys(&:to_s)
+        @structured = structured
+        @missing_secrets = Array(missing_secrets)
+      end
+
+      def app_name
+        parent.app_name
+      end
+
+      def database_name
+        name.empty? ? "app" : name
+      end
+
+      def database_adapter
+        @adapter || parent.send(:legacy_database_adapter)
+      end
+
+      def value(key)
+        raw =
+          if @env.key?(key)
+            @env[key]
+          elsif @structured && CONNECTION_KEYS.include?(key)
+            nil
+          else
+            parent.value(key)
+          end
+
+        stripped = raw.to_s.strip
+        stripped.empty? ? nil : stripped
+      end
+
+      def required_value(key)
+        value(key) || raise(ConfigurationError, "#{key} is required for database #{database_name}")
+      end
+
+      def validate_database_restore_target(target)
+        parent.validate_database_restore_target(target)
+      end
+
+      def validate_local_database_restore_target(target)
+        parent.validate_local_database_restore_target(target)
+      end
+    end
 
     attr_reader :env
 
     def initialize(env: ENV, cwd: Dir.pwd, defaults: {}, config_paths: nil, load_project_defaults: true)
       raw_env = env.to_h
       base = load_project_defaults ? project_defaults(cwd: cwd) : {}
-      @env = base.merge(defaults.to_h).merge(load_config_files(raw_env, cwd: cwd, paths: config_paths)).merge(raw_env)
+      config_data = load_config_files(raw_env, cwd: cwd, paths: config_paths)
+      @database_definitions = config_data.database_definitions
+      @path_definitions = config_data.path_definitions
+      @restore_from_definitions = config_data.restore_from_definitions
+      @env = base.merge(defaults.to_h).merge(config_data.env).merge(raw_env)
     end
 
     def app_name
@@ -132,14 +220,18 @@ module KamalBackup
     end
 
     def backup_paths
-      split_paths(value("BACKUP_PATHS"))
+      if path_definitions?
+        @path_definitions
+      else
+        legacy_backup_paths
+      end
     end
 
     def local_restore_source_paths
-      if raw = value("LOCAL_RESTORE_SOURCE_PATHS")
-        split_paths(raw)
+      if path_definitions?
+        @restore_from_definitions || legacy_local_restore_source_paths || backup_paths
       else
-        backup_paths
+        legacy_local_restore_source_paths || backup_paths
       end
     end
 
@@ -150,7 +242,7 @@ module KamalBackup
       if source_paths.size == target_paths.size
         source_paths.zip(target_paths)
       else
-        raise ConfigurationError, "LOCAL_RESTORE_SOURCE_PATHS must contain the same number of paths as BACKUP_PATHS"
+        raise ConfigurationError, "local restore source paths must contain the same number of paths as file paths"
       end
     end
 
@@ -160,12 +252,43 @@ module KamalBackup
     end
 
     def database_adapter
-      if explicit = value("DATABASE_ADAPTER")
-        normalize_adapter(explicit)
-      elsif adapter = adapter_from_database_url
-        adapter
-      elsif value("SQLITE_DATABASE_PATH")
-        "sqlite"
+      if database_definitions?
+        databases.first&.database_adapter
+      else
+        legacy_database_adapter
+      end
+    end
+
+    def database_name
+      "app"
+    end
+
+    def databases
+      @databases ||= begin
+        if database_definitions?
+          @database_definitions.map do |definition|
+            DatabaseSource.new(
+              parent: self,
+              name: definition.fetch(:name),
+              adapter: definition.fetch(:adapter),
+              env: definition.fetch(:env),
+              structured: true,
+              missing_secrets: definition.fetch(:missing_secrets, [])
+            )
+          end
+        elsif legacy_database_adapter
+          [
+            DatabaseSource.new(
+              parent: self,
+              name: database_name,
+              adapter: legacy_database_adapter,
+              env: {},
+              structured: false
+            )
+          ]
+        else
+          []
+        end
       end
     end
 
@@ -207,28 +330,33 @@ module KamalBackup
     end
 
     def validate_database_backup(check_files: true)
-      case database_adapter
-      when "postgres"
-        unless value("DATABASE_URL") || value("PGDATABASE")
-          raise ConfigurationError, "PostgreSQL backup requires DATABASE_URL or PGDATABASE/libpq environment"
+      raise ConfigurationError, "databases must contain at least one database" if databases.empty?
+
+      databases.each do |database|
+        unless database.missing_secrets.empty?
+          raise ConfigurationError, "database #{database.database_name} requires missing secret #{database.missing_secrets.join(", ")}"
         end
-      when "mysql"
-        unless value("DATABASE_URL") || value("MYSQL_DATABASE") || value("MARIADB_DATABASE")
-          raise ConfigurationError, "MySQL backup requires DATABASE_URL or MYSQL_DATABASE/MARIADB_DATABASE"
+
+        case database.database_adapter
+        when "postgres"
+          unless database.value("DATABASE_URL") || database.value("PGDATABASE")
+            raise ConfigurationError, "PostgreSQL database #{database.database_name} requires url or PGDATABASE/libpq environment"
+          end
+        when "mysql"
+          unless database.value("DATABASE_URL") || database.value("MYSQL_DATABASE") || database.value("MARIADB_DATABASE")
+            raise ConfigurationError, "MySQL database #{database.database_name} requires url or MYSQL_DATABASE/MARIADB_DATABASE"
+          end
+        when "sqlite"
+          path = database.required_value("SQLITE_DATABASE_PATH")
+          raise ConfigurationError, "SQLite database #{database.database_name} does not exist: #{path}" if check_files && !File.file?(path)
+        else
+          raise ConfigurationError, "database #{database.database_name} adapter is required and must be postgres, mysql, or sqlite"
         end
-      when "sqlite"
-        path = required_value("SQLITE_DATABASE_PATH")
-        raise ConfigurationError, "SQLITE_DATABASE_PATH does not exist: #{path}" if check_files && !File.file?(path)
-      else
-        raise ConfigurationError, "DATABASE_ADAPTER is required or must be detectable from DATABASE_URL/SQLITE_DATABASE_PATH"
       end
     end
 
     def validate_backup_paths(check_files: true)
-      paths = backup_paths
-      raise ConfigurationError, "BACKUP_PATHS must contain at least one path" if paths.empty?
-
-      paths.each do |path|
+      backup_paths.each do |path|
         expanded = File.expand_path(path)
         if SUSPICIOUS_BACKUP_PATHS.include?(expanded) && !allow_suspicious_backup_paths?
           raise ConfigurationError, "refusing suspicious backup path #{expanded}; set KAMAL_BACKUP_ALLOW_SUSPICIOUS_PATHS=true to override"
@@ -302,10 +430,14 @@ module KamalBackup
       end
 
       def load_config_files(raw_env, cwd:, paths:)
-        config_paths(raw_env, cwd: cwd, paths: paths).each_with_object({}) do |path, merged|
+        config_paths(raw_env, cwd: cwd, paths: paths).each_with_object(ConfigData.empty) do |path, merged|
           next unless File.file?(path)
 
-          merged.merge!(normalize_config_file(path))
+          data = normalize_config_file(path, raw_env: raw_env)
+          merged.env.merge!(data.env)
+          merged.database_definitions = data.database_definitions if data.database_definitions
+          merged.path_definitions = data.path_definitions if data.path_definitions
+          merged.restore_from_definitions = data.restore_from_definitions if data.restore_from_definitions
         end
       end
 
@@ -343,25 +475,51 @@ module KamalBackup
         raise ConfigurationError, "RESTIC_PASSWORD, RESTIC_PASSWORD_FILE, or RESTIC_PASSWORD_COMMAND is required"
       end
 
-      def normalize_config_file(path)
+      def normalize_config_file(path, raw_env:)
         data = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
-        return {} if data.nil?
+        return ConfigData.empty if data.nil?
 
         unless data.is_a?(Hash)
           raise ConfigurationError, "#{path} must contain a YAML mapping"
         end
 
-        data.each_with_object({}) do |(raw_key, raw_value), result|
-          key = normalize_yaml_key(raw_key)
-          result[key] = normalize_yaml_value(raw_value)
+        result = ConfigData.empty
+        data.each do |raw_key, raw_value|
+          key = raw_key.to_s
+          validate_top_level_yaml_key!(path, key)
+
+          case key
+          when "app"
+            result.env["APP_NAME"] = normalize_yaml_value(raw_value)
+          when "accessory"
+            result.env["KAMAL_BACKUP_ACCESSORY"] = normalize_yaml_value(raw_value)
+          when "databases"
+            result.database_definitions = normalize_yaml_databases(raw_value, raw_env: raw_env, path: path)
+          when "paths"
+            result.path_definitions = normalize_yaml_paths(raw_value, "#{path} paths")
+          when "restore_from"
+            result.restore_from_definitions = normalize_yaml_paths(raw_value, "#{path} restore_from")
+          when "restic"
+            result.env.merge!(normalize_yaml_restic(raw_value, raw_env: raw_env, path: path))
+          when "backup"
+            result.env.merge!(normalize_yaml_backup(raw_value, path: path))
+          when "state"
+            result.env.merge!(normalize_yaml_state(raw_value, path: path))
+          end
         end
+        result
       rescue Psych::SyntaxError => e
         raise ConfigurationError, "invalid YAML in #{path}: #{e.message}"
       end
 
-      def normalize_yaml_key(raw_key)
-        key = raw_key.to_s
-        YAML_KEY_ALIASES[key] || key.upcase
+      def validate_top_level_yaml_key!(path, key)
+        if LEGACY_YAML_KEYS.include?(key)
+          raise ConfigurationError, "#{path} uses legacy key #{key}; use databases, paths, restic, and backup instead. See the upgrading guide for the 0.3 config migration."
+        end
+
+        return if TOP_LEVEL_YAML_KEYS.include?(key)
+
+        raise ConfigurationError, "#{path} contains unknown key #{key.inspect}; expected #{TOP_LEVEL_YAML_KEYS.join(", ")}"
       end
 
       def normalize_yaml_value(raw_value)
@@ -375,6 +533,211 @@ module KamalBackup
         end
       end
 
+      def normalize_yaml_databases(raw_value, raw_env:, path:)
+        entries = require_array(raw_value, "#{path} databases")
+        entries.map.with_index(1) do |entry, index|
+          hash = require_mapping(entry, "#{path} databases[#{index}]")
+          name = required_yaml_scalar(hash, "name", "#{path} databases[#{index}]")
+          adapter = normalize_adapter(required_yaml_scalar(hash, "adapter", "#{path} databases[#{index}]"))
+          raise ConfigurationError, "#{path} databases[#{index}] adapter must be postgres, mysql, or sqlite" unless adapter
+
+          env = {}
+          missing_secrets = []
+          case adapter
+          when "postgres"
+            if hash.key?("url")
+              env["DATABASE_URL"] = resolve_yaml_value(hash["url"], raw_env: raw_env, context: "#{path} databases[#{index}].url")
+              missing_secrets.concat(missing_yaml_secrets(hash["url"], raw_env: raw_env))
+            end
+            if hash.key?("password")
+              env["PGPASSWORD"] = resolve_yaml_value(hash["password"], raw_env: raw_env, context: "#{path} databases[#{index}].password")
+              missing_secrets.concat(missing_yaml_secrets(hash["password"], raw_env: raw_env))
+            end
+          when "mysql"
+            if hash.key?("url")
+              env["DATABASE_URL"] = resolve_yaml_value(hash["url"], raw_env: raw_env, context: "#{path} databases[#{index}].url")
+              missing_secrets.concat(missing_yaml_secrets(hash["url"], raw_env: raw_env))
+            end
+            if hash.key?("password")
+              env["MYSQL_PWD"] = resolve_yaml_value(hash["password"], raw_env: raw_env, context: "#{path} databases[#{index}].password")
+              missing_secrets.concat(missing_yaml_secrets(hash["password"], raw_env: raw_env))
+            end
+          when "sqlite"
+            sqlite_path = hash.key?("path") ? hash["path"] : hash["database"]
+            if sqlite_path
+              env["SQLITE_DATABASE_PATH"] = resolve_yaml_value(sqlite_path, raw_env: raw_env, context: "#{path} databases[#{index}].path")
+              missing_secrets.concat(missing_yaml_secrets(sqlite_path, raw_env: raw_env))
+            end
+          end
+
+          {
+            name: name,
+            adapter: adapter,
+            env: env.compact,
+            missing_secrets: missing_secrets
+          }
+        end
+      end
+
+      def normalize_yaml_restic(raw_value, raw_env:, path:)
+        hash = require_mapping(raw_value, "#{path} restic")
+        env = {}
+
+        env["RESTIC_REPOSITORY"] = resolve_yaml_value(hash["repository"], raw_env: raw_env, context: "#{path} restic.repository") if hash.key?("repository")
+        env["RESTIC_REPOSITORY_FILE"] = normalize_yaml_value(hash["repository_file"]) if hash.key?("repository_file")
+
+        if hash.key?("password")
+          normalize_yaml_restic_password(hash["password"], raw_env: raw_env, path: path).each do |key, value|
+            env[key] = value
+          end
+        end
+
+        {
+          "init_if_missing" => "RESTIC_INIT_IF_MISSING",
+          "check_after_backup" => "RESTIC_CHECK_AFTER_BACKUP",
+          "check_read_data_subset" => "RESTIC_CHECK_READ_DATA_SUBSET",
+          "forget_after_backup" => "RESTIC_FORGET_AFTER_BACKUP"
+        }.each do |source, target|
+          env[target] = normalize_yaml_value(hash[source]) if hash.key?(source)
+        end
+
+        if hash.key?("retention")
+          retention = require_mapping(hash["retention"], "#{path} restic.retention")
+          {
+            "keep_last" => "RESTIC_KEEP_LAST",
+            "keep_daily" => "RESTIC_KEEP_DAILY",
+            "keep_weekly" => "RESTIC_KEEP_WEEKLY",
+            "keep_monthly" => "RESTIC_KEEP_MONTHLY",
+            "keep_yearly" => "RESTIC_KEEP_YEARLY"
+          }.each do |source, target|
+            env[target] = normalize_yaml_value(retention[source]) if retention.key?(source)
+          end
+        end
+
+        env.compact
+      end
+
+      def normalize_yaml_restic_password(raw_value, raw_env:, path:)
+        case raw_value
+        when Hash
+          hash = stringify_keys(raw_value)
+          if hash.key?("secret")
+            { "RESTIC_PASSWORD" => resolve_yaml_value(hash, raw_env: raw_env, context: "#{path} restic.password") }
+          elsif hash.key?("file")
+            { "RESTIC_PASSWORD_FILE" => normalize_yaml_value(hash["file"]) }
+          elsif hash.key?("command")
+            { "RESTIC_PASSWORD_COMMAND" => normalize_yaml_value(hash["command"]) }
+          else
+            raise ConfigurationError, "#{path} restic.password must use secret, file, or command"
+          end
+        else
+          { "RESTIC_PASSWORD" => normalize_yaml_value(raw_value) }
+        end
+      end
+
+      def normalize_yaml_backup(raw_value, path:)
+        hash = require_mapping(raw_value, "#{path} backup")
+        env = {}
+        env["BACKUP_SCHEDULE_SECONDS"] = normalize_duration(hash["schedule"], "#{path} backup.schedule") if hash.key?("schedule")
+        env.compact
+      end
+
+      def normalize_yaml_state(raw_value, path:)
+        hash = require_mapping(raw_value, "#{path} state")
+        env = {}
+        env["KAMAL_BACKUP_STATE_DIR"] = normalize_yaml_value(hash["path"]) if hash.key?("path")
+        env.compact
+      end
+
+      def normalize_yaml_paths(raw_value, context)
+        case raw_value
+        when Array
+          raw_value.map { |path| normalize_yaml_path(path, context) }.reject(&:empty?)
+        when NilClass
+          []
+        else
+          [normalize_yaml_path(raw_value, context)].reject(&:empty?)
+        end
+      end
+
+      def normalize_yaml_path(raw_value, context)
+        if raw_value.is_a?(Hash) || raw_value.is_a?(Array)
+          raise ConfigurationError, "#{context} entries must be path strings"
+        end
+
+        normalize_yaml_value(raw_value)
+      end
+
+      def resolve_yaml_value(raw_value, raw_env:, context:)
+        case raw_value
+        when Hash
+          hash = stringify_keys(raw_value)
+          unless hash.keys == ["secret"]
+            raise ConfigurationError, "#{context} must be a scalar value or { secret: NAME }"
+          end
+
+          secret_name = normalize_yaml_value(hash.fetch("secret"))
+          raw_env[secret_name]
+        else
+          normalize_yaml_value(raw_value)
+        end
+      end
+
+      def missing_yaml_secrets(raw_value, raw_env:)
+        return [] unless raw_value.is_a?(Hash)
+
+        hash = stringify_keys(raw_value)
+        return [] unless hash.key?("secret")
+
+        secret_name = normalize_yaml_value(hash.fetch("secret"))
+        raw_env[secret_name].to_s.strip.empty? ? [secret_name] : []
+      end
+
+      def normalize_duration(raw_value, context)
+        value = normalize_yaml_value(raw_value)
+        raise ConfigurationError, "#{context} is required" if value.to_s.empty?
+
+        return value if value.match?(/\A\d+\z/)
+
+        match = value.match(/\A(\d+)\s*([smhdw])\z/i)
+        unless match
+          raise ConfigurationError, "#{context} must be seconds or a duration like 30m, 6h, or 1d"
+        end
+
+        amount = match[1].to_i
+        multiplier = {
+          "s" => 1,
+          "m" => 60,
+          "h" => 3600,
+          "d" => 86_400,
+          "w" => 604_800
+        }.fetch(match[2].downcase)
+        (amount * multiplier).to_s
+      end
+
+      def require_array(value, context)
+        return value if value.is_a?(Array)
+
+        raise ConfigurationError, "#{context} must be a YAML sequence"
+      end
+
+      def require_mapping(value, context)
+        raise ConfigurationError, "#{context} must be a YAML mapping" unless value.is_a?(Hash)
+
+        stringify_keys(value)
+      end
+
+      def required_yaml_scalar(hash, key, context)
+        value = normalize_yaml_value(hash[key])
+        raise ConfigurationError, "#{context} #{key} is required" if value.to_s.empty?
+
+        value
+      end
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+      end
+
       def validate_local_machine_environment
         if environment = local_restore_environment
           key, value = environment
@@ -387,7 +750,6 @@ module KamalBackup
 
       def validate_local_machine_paths
         path_pairs = local_restore_path_pairs
-        raise ConfigurationError, "BACKUP_PATHS must contain at least one path" if path_pairs.empty?
 
         path_pairs.each do |_source_path, target_path|
           expanded = File.expand_path(target_path)
@@ -420,6 +782,24 @@ module KamalBackup
         end
       end
 
+      def database_definitions?
+        !@database_definitions.nil?
+      end
+
+      def path_definitions?
+        !@path_definitions.nil?
+      end
+
+      def legacy_database_adapter
+        if explicit = value("DATABASE_ADAPTER")
+          normalize_adapter(explicit)
+        elsif adapter = adapter_from_database_url
+          adapter
+        elsif value("SQLITE_DATABASE_PATH")
+          "sqlite"
+        end
+      end
+
       def adapter_from_database_url
         if url = value("DATABASE_URL")
           normalize_adapter(URI.parse(url).scheme)
@@ -436,13 +816,25 @@ module KamalBackup
       end
 
       def source_database_targets
-        [
-          value("DATABASE_URL"),
-          value("SQLITE_DATABASE_PATH"),
-          value("PGDATABASE"),
-          value("MYSQL_DATABASE"),
-          value("MARIADB_DATABASE")
-        ].compact
+        databases.flat_map do |database|
+          [
+            database.value("DATABASE_URL"),
+            database.value("SQLITE_DATABASE_PATH"),
+            database.value("PGDATABASE"),
+            database.value("MYSQL_DATABASE"),
+            database.value("MARIADB_DATABASE")
+          ]
+        end.compact
+      end
+
+      def legacy_backup_paths
+        split_paths(value("BACKUP_PATHS"))
+      end
+
+      def legacy_local_restore_source_paths
+        if raw = value("LOCAL_RESTORE_SOURCE_PATHS")
+          split_paths(raw)
+        end
       end
 
       def split_paths(raw)

data/lib/kamal_backup/databases/base.rb

@@ -43,11 +43,12 @@ module KamalBackup
 
       def database_filename(timestamp)
         app = config.app_name.gsub(/[^A-Za-z0-9_.-]+/, "-")
-        "databases-#{app}-#{adapter_name}-#{timestamp}.#{dump_extension}"
+        database = config.database_name.gsub(/[^A-Za-z0-9_.-]+/, "-")
+        "databases-#{app}-#{database}-#{adapter_name}-#{timestamp}.#{dump_extension}"
       end
 
       def backup_tags(timestamp)
-        ["type:database", "adapter:#{adapter_name}", "run:#{timestamp}"]
+        ["type:database", "database:#{config.database_name}", "adapter:#{adapter_name}", "run:#{timestamp}"]
       end
 
       def adapter_name

data/lib/kamal_backup/databases/mysql.rb

@@ -68,7 +68,9 @@ module KamalBackup
 
         def current_connection
           if value("DATABASE_URL")
-            parse_url(value("DATABASE_URL"))
+            parse_url(value("DATABASE_URL")).tap do |connection|
+              connection[:password] ||= value("MYSQL_PWD") || value("MYSQL_PASSWORD") || value("MARIADB_PASSWORD")
+            end
           else
             connection_from_env("")
           end

data/lib/kamal_backup/databases/postgres.rb

@@ -68,7 +68,9 @@ module KamalBackup
 
         def current_connection
           if value("DATABASE_URL")
-            connection_from_url(value("DATABASE_URL"), "DATABASE_URL")
+            connection_from_url(value("DATABASE_URL"), "DATABASE_URL").tap do |connection|
+              connection["PGPASSWORD"] ||= value("PGPASSWORD") if value("PGPASSWORD")
+            end
           else
             connection = prefixed_env("", SOURCE_ENV_KEYS)
             raise ConfigurationError, "DATABASE_URL or PGDATABASE is required for PostgreSQL restore" unless connection["PGDATABASE"]

data/lib/kamal_backup/evidence.rb

@@ -18,11 +18,14 @@ module KamalBackup
         app_name: @config.app_name,
         generated_at: Time.now.utc.iso8601,
         database_adapter: @config.database_adapter,
+        databases: @config.databases.map { |database| { name: database.database_name, adapter: database.database_adapter } },
         restic_repository: @redactor.redact_string(@config.restic_repository.to_s),
         backup_paths: @config.backup_paths,
+        paths: @config.backup_paths,
         forget_after_backup: @config.forget_after_backup?,
         retention: @config.retention,
         latest_database_backup: latest_snapshot_summary(["type:database"]),
+        latest_database_backups: latest_database_backups,
         latest_file_backup: latest_snapshot_summary(["type:files"]),
         last_restic_check: last_check,
         last_restore_drill: last_restore_drill,
@@ -50,6 +53,16 @@ module KamalBackup
         { error: @redactor.redact_string(e.message) }
       end
 
+      def latest_database_backups
+        @config.databases.each_with_object({}) do |database, backups|
+          backups[database.database_name] = latest_snapshot_summary([
+            "type:database",
+            "database:#{database.database_name}",
+            "adapter:#{database.database_adapter}"
+          ])
+        end
+      end
+
       def last_check
         if File.file?(@config.last_check_path)
           JSON.parse(File.read(@config.last_check_path))

data/lib/kamal_backup/kamal_bridge.rb

@@ -1,3 +1,4 @@
+require "shellwords"
 require "yaml"
 require_relative "command"
 
@@ -147,10 +148,15 @@ module KamalBackup
 
       def parse_secret_output(output)
         output.to_s.lines.each_with_object({}) do |line, secrets|
-          key, value = line.chomp.split("=", 2)
-          next if key.to_s.empty?
+          tokens = Shellwords.split(line.chomp)
+          tokens.shift if tokens.first == "export"
 
-          secrets[key] = value.to_s
+          tokens.each do |assignment|
+            key, value = assignment.split("=", 2)
+            next if key.to_s.empty? || value.nil?
+
+            secrets[key] = value.to_s
+          end
         end
       end
 

data/lib/kamal_backup/restic.rb

@@ -122,14 +122,19 @@ module KamalBackup
       end
     end
 
-    def database_file(snapshot, adapter)
+    def database_file(snapshot, adapter, database_name: nil)
       legacy_prefix = "databases/#{config.app_name}/#{adapter}/"
-      flat_prefix = "databases-#{config.app_name.gsub(/[^A-Za-z0-9_.-]+/, "-")}-#{adapter}-"
+      app = config.app_name.gsub(/[^A-Za-z0-9_.-]+/, "-")
+      database = database_name.to_s.gsub(/[^A-Za-z0-9_.-]+/, "-")
+      flat_prefix = "databases-#{app}-#{adapter}-"
+      named_flat_prefix = database.empty? ? nil : "databases-#{app}-#{database}-#{adapter}-"
       ls_json(snapshot).find do |entry|
         next false unless entry["type"] == "file"
 
         normalized = entry["path"].to_s.sub(%r{\A/+}, "")
-        normalized.start_with?(legacy_prefix) || File.basename(normalized).start_with?(flat_prefix)
+        normalized.start_with?(legacy_prefix) ||
+          File.basename(normalized).start_with?(flat_prefix) ||
+          (named_flat_prefix && File.basename(normalized).start_with?(named_flat_prefix))
       end&.fetch("path")
     end
 

data/lib/kamal_backup/version.rb

@@ -1,3 +1,3 @@
 module KamalBackup
-  VERSION = "0.2.10"
+  VERSION = "0.3.0.beta2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kamal-backup
 version: !ruby/object:Gem::Version
-  version: 0.2.10
+  version: 0.3.0.beta2
 platform: ruby
 authors:
 - crmne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -74,7 +74,13 @@ metadata:
   source_code_uri: https://github.com/crmne/kamal-backup
   changelog_uri: https://github.com/crmne/kamal-backup/releases
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: |
+  kamal-backup 0.3 changes config/kamal-backup.yml.
+
+  If you are upgrading from 0.2, migrate the old flat YAML keys to the new grouped shape:
+    https://kamal-backup.dev/upgrading/#upgrading-to-03
+
+  Run `bundle exec kamal-backup validate` before rebooting the backup accessory.
 rdoc_options: []
 require_paths:
 - lib