bard-backup 0.11.4 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78996cfc76728d6202bd4836681db28779460fce707fdf73ddffda233589289
-  data.tar.gz: ed49a1090e5ea87065e09c4567bbe81d19a500b92c1151e76bb9f8150095a61f
+  metadata.gz: f051915564aff1edf80617a2f83d6eb0c5fbf392ef0f68b5cd4d082c9d0a6450
+  data.tar.gz: 274a30cc6ac3579045ffb1c7be96a62016f63497e177fc09483122535c72329a
 SHA512:
-  metadata.gz: e738f2af35ce1b1459c07e747a0e7d89f0298daa22df4bfabfdff88273545adc1b0c8909f0207d2197027d6ca7a1ada0d6243a4ac91b51f076852487796c3d2f
-  data.tar.gz: 9bd09e3d8355bc921d489f606b422c748ec5e2b042550d96c58d22259518a5c2f455774e33f85b92c38fcebacf9edc3a3dd0cb35356229c9eef36df35c860f3e
+  metadata.gz: 998e90d23806ee850d5440b7e63c89ef357749697dae25f5cb89b20c77b32ccb644da5c232ecebdbdc57d7e4a2b53562acdb9c081d02b34624ce533d03efb29f
+  data.tar.gz: bd5eb49fa3a1676ea5f1c6805450f0146c0d18b9ee26139fcee74314d0bfcb9984d27076b7af510ff959f5fa4c7e1eb31d157e7be52795c20e138be75551a4fb

data/CLAUDE.md

@@ -45,8 +45,9 @@ Tests require AWS credentials at `spec/support/credentials.json`. In CI, this is
 **Entry points**:
 - `Bard::Backup.create!` accepts destination configs (or reads from `Bard::Config`) and delegates to destination strategies. Returns a `Bard::Backup` instance with timestamp/size/destinations.
 - `Bard::Backup::FileTree.create!` syncs configured data directories to S3.
+- `Bard::Backup.restore!(at:)` downloads the backup nearest `at` (or the latest when omitted), decrypts it if necessary, and loads it into the local database via `backhoe` (drop-and-create). `Bard::Backup.available` lists the available backup timestamps.
 
-**Destination strategy pattern**: `Destination.build(config)` is a factory that picks the right class based on `:type`:
+**Destination strategy pattern**: `Destination.build(config)` is a factory that picks the right class based on `:type`. `Destination.resolve(hashes)` is the single entry point both `Database.create!` and `Finder` use — it falls back to the configured destinations, normalizes a lone Hash/Array, and builds them. Each destination resolves its own `encryption_key` (explicit config, falling back to `Bard::Config.current.backup.encryption_key`), so callers never inject it.
 - `S3Destination` — dumps DB locally via backhoe, uploads to S3, runs `Deleter` for retention, verifies previous hour's backup
 - `UploadDestination` — dumps DB and uploads to presigned URLs (multi-threaded)
 
@@ -64,6 +65,8 @@ end
 - `Encryptor` — AES-256-GCM with HKDF-derived keys and a deterministic IV (HMAC of plaintext), enabling content-addressable encryption
 - `Deleter` — implements the retention policy via `Filter` structs that check time-based granularities
 - `LocalBackhoe` / `CachedLocalBackhoe` — database dump strategies (cached variant avoids conflicts when running parallel destinations)
-- `LatestFinder` — finds the most recent backup across all configured destinations
+- `Finder` — lists backups across destinations and selects one: by timestamp (nearest match), the latest, or the most-recent as a `Bard::Backup` (with size + destination info). Backs `Bard::Backup.available`/`.latest` and `Restore`
+- `Restore` — downloads the backup selected by `Finder`, decrypts it via `S3Tree#get`, and loads it into the local database via backhoe (drop-and-create). Backs `Bard::Backup.restore!`
 - `BackupConfig` — the `backup do ... end` DSL surface (`bard`, `disabled`, `s3 name, **kwargs`); `create!` reads `bard_config.backup.destinations` from it
-- `Railtie` — loads `tasks.rake` which provides `bard:backup` (DB + data) and `bard:backup:data` (data only) rake tasks in Rails apps
+- `Railtie` — loads `tasks.rake` which provides `bard:backup` (DB + data), `bard:backup:data` (data only), and `bard:backup:restore[at]` (restore/list) rake tasks in Rails apps
+- `bard/plugins/backup_restore.rb` — registers the `bard backup restore [TIMESTAMP]` CLI subcommand (loaded by the `bard` CLI via `Gem.find_files`); shells out to the `bard:backup:restore` rake task

data/README.md

@@ -42,6 +42,39 @@ rake bard:backup        # database backup + data file-tree sync
 rake bard:backup:data   # data file-tree sync only
 ```
 
+## Restoring
+
+Restore a database backup from S3 into the local database. The backup nearest the
+requested timestamp is selected (backups run hourly, so an exact match isn't
+guaranteed), downloaded, decrypted if necessary, and loaded via `backhoe`,
+dropping and recreating the local database.
+
+From the `bard` CLI:
+
+```bash
+bard backup restore                       # list the available backup timestamps
+bard backup restore 2026-06-05T16:00:00Z  # restore the backup nearest this UTC time
+```
+
+Or via the rake task directly:
+
+```bash
+rake "bard:backup:restore"                       # list available backups
+rake "bard:backup:restore[2026-06-05T16:00:00Z]" # restore nearest this time
+```
+
+Or programmatically:
+
+```ruby
+Bard::Backup.available                            # => [Time, Time, ...]
+Bard::Backup.restore!                             # restore the latest backup
+Bard::Backup.restore!(at: "2026-06-05T16:00:00Z") # restore nearest this time
+```
+
+Timestamps are UTC (the `Z`-suffixed ISO-8601 form the backups are named with).
+Restore requires self-managed destinations configured via the `backup do ... end`
+DSL; bard-managed backups are not yet supported.
+
 Or call programmatically:
 
 ```ruby

data/lib/bard/backup/database.rb

@@ -8,25 +8,15 @@ module Bard
           destination_hashes = [config]
         end
 
-        bard_config = defined?(Bard::Config) ? Bard::Config.current : nil
-        destination_hashes ||= bard_config&.backup&.destinations || []
+        now = Time.now.utc
+        backups = Destination.resolve(destination_hashes, now: now).map(&:call)
+        return nil if backups.empty?
 
-        destinations = if destination_hashes.is_a?(Hash)
-          [destination_hashes]
-        else
-          Array(destination_hashes)
-        end
-
-        encryption_key = bard_config&.backup&.encryption_key
-        if encryption_key
-          destinations = destinations.map { |h| { encryption_key: encryption_key, **h } }
-        end
-
-        result = nil
-        destinations.each do |hash|
-          result = Backup::Destination.build(hash).call
-        end
-        result
+        Bard::Backup.new(
+          timestamp: backups.first.timestamp,
+          size: backups.first.size,
+          destinations: backups.flat_map(&:destinations),
+        )
       end
     end
   end

data/lib/bard/backup/destination/s3_destination.rb

@@ -14,28 +14,30 @@ module Bard
       end
 
       def s3_tree
-        @s3_tree ||= S3Tree.new(**config.slice(:endpoint, :path, :access_key_id, :secret_access_key, :session_token, :region, :encryption_key))
+        @s3_tree ||= S3Tree.new(**resolved_config.slice(:endpoint, :path, :access_key_id, :secret_access_key, :session_token, :region, :encryption_key).compact)
       end
 
       def info
-        config.slice(:name, :type, :path, :region)
+        resolved_config.slice(:name, :type, :path, :region)
       end
 
       private
 
-      def config
-        @config ||= begin
-          explicit = super
-          credentials = RailsCredentials.find(name: explicit[:name])
-          config = { type: :s3, region: "us-west-2" }.merge(credentials).merge(explicit)
-          config[:endpoint] ||= "https://s3.#{config[:region]}.amazonaws.com"
-          config
+      # The raw config enriched with Rails credentials (by name), defaults, the
+      # computed endpoint, and the resolved encryption key.
+      def resolved_config
+        @resolved_config ||= begin
+          credentials = RailsCredentials.find(name: config[:name])
+          resolved = { type: :s3, region: "us-west-2" }.merge(credentials).merge(config)
+          resolved[:endpoint] ||= "https://s3.#{resolved[:region]}.amazonaws.com"
+          resolved[:encryption_key] ||= Bard::Config.current.backup.encryption_key
+          resolved
         end
       end
 
       def strategy
         return @strategy if @strategy
-        @strategy = config.fetch(:strategy, LocalBackhoe)
+        @strategy = resolved_config.fetch(:strategy, LocalBackhoe)
         @strategy = Bard::Backup.const_get(@strategy) if @strategy.is_a?(String)
         @strategy
       end

data/lib/bard/backup/destination/upload_destination.rb

@@ -55,8 +55,8 @@ module Bard
 
         File.open(file_path, "rb") do |file|
           body = file.read
-          if config[:encryption_key]
-            body = Encryptor.new(config[:encryption_key]).encrypt(body)
+          if (key = encryption_key)
+            body = Encryptor.new(key).encrypt(body)
           end
           request = Net::HTTP::Put.new(uri)
           request.body = body

data/lib/bard/backup/destination.rb

@@ -1,3 +1,5 @@
+require "bard/config"
+
 module Bard
   class Backup
     class Destination < Struct.new(:config)
@@ -6,12 +8,28 @@ module Bard
         klass.new(config)
       end
 
+      # Normalizes destination config into built destinations: falls back to the
+      # configured destinations when none are given, and accepts a lone Hash or
+      # an Array. A +now+ stamps every destination with one run timestamp (an
+      # explicit per-destination +now+ still wins). Each destination resolves its
+      # own encryption key (see #encryption_key), so callers don't have to inject it.
+      def self.resolve(destination_hashes = nil, now: nil)
+        hashes = destination_hashes || Bard::Config.current.backup.destinations
+        hashes = hashes.is_a?(Hash) ? [hashes] : Array(hashes)
+        hashes = hashes.map { |hash| { now:, **hash } } if now
+        hashes.map { |hash| build(hash) }
+      end
+
       def call
         raise NotImplementedError
       end
 
       private
 
+      def encryption_key
+        config[:encryption_key] || Bard::Config.current.backup.encryption_key
+      end
+
       def now
         @now ||= config.fetch(:now, Time.now.utc)
       end

data/lib/bard/backup/finder.rb

@@ -0,0 +1,68 @@
+require "time"
+require "bard/config"
+require "bard/backup/destination"
+
+module Bard
+  class Backup
+    class NotFound < StandardError; end
+
+    # Locates database backups across the configured destinations and selects one by timestamp.
+    class Finder
+      def initialize(destinations = nil)
+        @destinations = Destination.resolve(destinations)
+      end
+
+      def all
+        @destinations.flat_map do |destination|
+          destination.s3_tree.list_objects.keys.filter_map do |filename|
+            timestamp = parse_timestamp(filename)
+            next unless timestamp
+            { timestamp:, destination:, filename: }
+          end
+        end
+      end
+
+      def timestamps
+        all.map { |backup| backup[:timestamp] }.uniq.sort
+      end
+
+      def find(at: nil)
+        backups = all
+        raise NotFound, "No backups found" if backups.empty?
+
+        if at.nil?
+          backups.max_by { |backup| backup[:timestamp] }
+        else
+          # returns nearest backup (exact timestamp match is not guaranteed)
+          target = at.is_a?(Time) ? at : Time.parse(at.to_s)
+          backups.min_by { |backup| (backup[:timestamp] - target).abs }
+        end
+      end
+
+      def latest
+        backups = all
+        raise NotFound, "No backups found" if backups.empty?
+
+        newest = backups.max_by { |backup| backup[:timestamp] }
+        Bard::Backup.new(
+          timestamp: newest[:timestamp],
+          size: file_size(newest[:destination].s3_tree, newest[:filename]),
+          destinations: backups
+            .select { |backup| backup[:timestamp] == newest[:timestamp] }
+            .map { |backup| backup[:destination].info },
+        )
+      end
+
+      private
+
+      def file_size(s3_tree, filename)
+        key = [s3_tree.folder_prefix, filename].compact.join("/")
+        s3_tree.send(:client).head_object(bucket: s3_tree.bucket_name, key: key).content_length
+      end
+
+      def parse_timestamp(filename)
+        filename =~ /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)/ ? Time.parse($1) : nil
+      end
+    end
+  end
+end

data/lib/bard/backup/restore.rb

@@ -0,0 +1,36 @@
+require "backhoe"
+require "fileutils"
+require "bard/backup/finder"
+
+module Bard
+  class Backup
+    # Downloads a database backup from S3 and loads it into the local database.
+    # The backup nearest +at+ is selected, decrypted if necessary, and loaded
+    # via backhoe.
+    class Restore < Struct.new(:at, :drop_and_create, :destinations, keyword_init: true)
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(at:, drop_and_create: true, destinations: nil)
+        super
+      end
+
+      def call
+        backup = Finder.new(destinations).find(at: at)
+        body = backup[:destination].s3_tree.get(backup[:filename])
+        path = "/tmp/bard-backup-restore-#{File.basename(backup[:filename])}"
+        File.binwrite(path, body)
+        Backhoe.load(path, drop_and_create: drop_and_create)
+
+        Bard::Backup.new(
+          timestamp: backup[:timestamp],
+          size: body.bytesize,
+          destinations: [backup[:destination].info],
+        )
+      ensure
+        FileUtils.rm_f(path) if path
+      end
+    end
+  end
+end

data/lib/bard/backup/tasks.rake

@@ -1,9 +1,8 @@
-require "bard/backup/rails_credentials"
-
 namespace :bard do
   desc "Backup the database and file trees to configured destinations"
   task :backup => :environment do
     require "bard/backup"
+    require "bard/backup/rails_credentials"
 
     destinations = Bard::Config.current.backup.destinations.map do |dest|
       Bard::Backup::RailsCredentials.find(name: dest[:name]).merge(dest)
@@ -16,7 +15,24 @@ namespace :bard do
     desc "Backup file trees to S3"
     task :data => :environment do
       require "bard/backup"
+      require "bard/backup/rails_credentials"
       Bard::Backup::FileTree.create!(**Bard::Backup::RailsCredentials.find)
     end
+
+    desc "Restore the database backup nearest a timestamp (no timestamp lists available backups)"
+    task :restore, [:at] => :environment do |_task, args|
+      require "bard/backup"
+      require "bard/backup/rails_credentials"
+
+      destinations = Bard::Config.current.backup.destinations
+      if args[:at].to_s.strip.empty?
+        timestamps = Bard::Backup.available(destinations: destinations)
+        puts "Available backups:"
+        timestamps.each { |timestamp| puts "  #{timestamp.iso8601}" }
+      else
+        backup = Bard::Backup.restore!(at: args[:at], destinations: destinations)
+        puts "Restored database from backup #{backup.timestamp.iso8601}."
+      end
+    end
   end
 end

data/lib/bard/backup/version.rb

@@ -1,6 +1,6 @@
 module Bard
   class Backup
-    VERSION = "0.11.4"
+    VERSION = "0.12.0"
   end
 end
 

data/lib/bard/backup.rb

@@ -3,7 +3,8 @@ require "bard/plugins/backup"
 require "bard/plugins/encrypt"
 require "bard/backup/database"
 require "bard/backup/file_tree"
-require "bard/backup/latest_finder"
+require "bard/backup/finder"
+require "bard/backup/restore"
 require "bard/backup/railtie" if defined?(Rails)
 
 module Bard
@@ -17,7 +18,15 @@ module Bard
     end
 
     def self.latest
-      LatestFinder.new.call
+      Finder.new.latest
+    end
+
+    def self.available(destinations: nil)
+      Finder.new(destinations).timestamps
+    end
+
+    def self.restore!(at:, drop_and_create: true, destinations: nil)
+      Restore.call(at: at, drop_and_create: drop_and_create, destinations: destinations)
     end
 
     attr_reader :timestamp, :size, :destinations

data/lib/bard/plugins/backup_restore.rb

@@ -0,0 +1,35 @@
+# Registers the `bard backup restore` CLI subcommand. The actual work runs in
+# the `bard:backup:restore` rake task, which boots Rails so it has the AWS
+# credentials and database config it needs (mirroring how `bard data` shells out
+# to `bin/rake db:load`).
+require "bard/command"
+
+class Bard::CLI
+  class BackupCommands < Thor
+    desc "restore [TIMESTAMP]", "restore the database backup nearest TIMESTAMP into the local database"
+    long_desc <<~DESC
+      Restores the database backup nearest TIMESTAMP (ISO-8601 UTC, e.g.
+      2026-06-05T16:00:00Z) into the LOCAL database, dropping and recreating it.
+
+      With no TIMESTAMP, lists the available backups instead of restoring.
+    DESC
+    def restore(timestamp = nil)
+      if timestamp.nil?
+        Bard::Command.run! "bin/rake bard:backup:restore", verbose: true
+      else
+        say "This will DROP and reload your LOCAL database from the backup nearest #{timestamp}.", :yellow
+        unless yes?("Continue? (y/N)")
+          say "Aborted."
+          exit 1
+        end
+        Bard::Command.run! %(bin/rake "bard:backup:restore[#{timestamp}]"), verbose: true
+      end
+    rescue Bard::Command::Error => e
+      say "!!! Running command failed: #{e.message}", :red
+      exit 1
+    end
+  end
+
+  desc "backup SUBCOMMAND", "database backup operations"
+  subcommand "backup", BackupCommands
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bard-backup
 version: !ruby/object:Gem::Version
-  version: 0.11.4
+  version: 0.12.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-05-17 00:00:00.000000000 Z
+date: 2026-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: backhoe
@@ -103,14 +103,16 @@ files:
 - lib/bard/backup/destination/upload_destination.rb
 - lib/bard/backup/encryptor.rb
 - lib/bard/backup/file_tree.rb
-- lib/bard/backup/latest_finder.rb
+- lib/bard/backup/finder.rb
 - lib/bard/backup/local_backhoe.rb
 - lib/bard/backup/rails_credentials.rb
 - lib/bard/backup/railtie.rb
+- lib/bard/backup/restore.rb
 - lib/bard/backup/s3_tree.rb
 - lib/bard/backup/tasks.rake
 - lib/bard/backup/version.rb
 - lib/bard/plugins/backup.rb
+- lib/bard/plugins/backup_restore.rb
 - lib/bard/plugins/encrypt.rb
 - sig/bard/backup.rbs
 homepage: https://github.com/botandrose/bard-backup

data/lib/bard/backup/latest_finder.rb

@@ -1,47 +0,0 @@
-require "bard/config"
-
-module Bard
-  class Backup
-    class NotFound < StandardError; end
-
-    class LatestFinder
-      def call
-        destinations = Bard::Config.current.backup.destinations.map do |hash|
-          Destination.build(hash)
-        end
-
-        all_backups = destinations.flat_map do |dest|
-          dest.s3_tree.list_objects.keys.filter_map do |filename|
-            timestamp = parse_timestamp(filename)
-            next unless timestamp
-
-            { timestamp: timestamp, destination: dest, filename: filename }
-          end
-        end
-
-        raise NotFound, "No backups found" if all_backups.empty?
-
-        latest = all_backups.max_by { |b| b[:timestamp] }
-
-        Bard::Backup.new(
-          timestamp: latest[:timestamp],
-          size: get_file_size(latest[:destination].s3_tree, latest[:filename]),
-          destinations: all_backups
-            .select { |b| b[:timestamp] == latest[:timestamp] }
-            .map { |b| b[:destination].info }
-        )
-      end
-
-      private
-
-      def parse_timestamp(filename)
-        filename =~ /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)/ ? Time.parse($1) : nil
-      end
-
-      def get_file_size(s3_tree, filename)
-        key = [s3_tree.folder_prefix, filename].compact.join("/")
-        s3_tree.send(:client).head_object(bucket: s3_tree.bucket_name, key: key).content_length
-      end
-    end
-  end
-end