kamal-backup 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30f7bd9a81da2eaaa2a67c9b7a91b125c4aeb94262e95b5e1b38494a9701ca75
-  data.tar.gz: fac65cc0dc3d2f5de582fac9e32def041f8f8e815427f6c378e6adb69f858b98
+  metadata.gz: 8322ff9eeead7c145127274766d96c54677333fafd7a94b57c6eb7b395cfeae6
+  data.tar.gz: b9b1d442c93b808b4d0e04c9fdd3eb757ff97df2470610769bd7e430836107e9
 SHA512:
-  metadata.gz: 5d9eb3a42e57cf756bced50de85c6d183209219624c95e4cdfd26ab25fe5236edcc2c08b193062100669eb2355eaae68cc1afb0b82d3a6838d3f2322d7f34de9
-  data.tar.gz: 7f248053459259bb4fd80f281e3f828a3caa2964e49f6bcf6855f55ec152b439533586d3dc971aecdd3e57e7e6d3cac1b464dde554acd40a08064c407c6b248b
+  metadata.gz: 4d4031c8ffaa652db3f151c3b21cbf2e170571278a57d815880fa4bbe5a06d6dfce9690d9f59fbe5e68de77c97c6e1ac6a1da90c4c400ccb8af2acaf7d18cec7
+  data.tar.gz: f037233779d710baadf2c6c5e4100b8caccda9069d95b781411fbe35f5c8e4b93899c41d0652f6baa69f38f7e8107c83b65ef19d3ee988397067e5c40e0ae0b7

data/README.md

@@ -30,7 +30,7 @@ Most self-hosted Rails apps need the same things:
 - file-backed Active Storage backups from mounted volumes
 - a fast way to restore production data locally
 - restore drills that do not touch the live production database
-- evidence that says more than "the backup job is green"
+- 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.
 
@@ -93,12 +93,12 @@ bin/kamal accessory boot backup
 bin/kamal accessory logs backup
 ```
 
-Run the first backup and print evidence:
+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:
 
 ```sh
-bundle exec kamal-backup -d production backup
-bundle exec kamal-backup -d production list
-bundle exec kamal-backup -d production evidence
+bundle exec kamal-backup backup
+bundle exec kamal-backup list
+bundle exec kamal-backup evidence
 ```
 
 ## What you get

data/lib/kamal_backup/cli.rb

@@ -77,11 +77,7 @@ module KamalBackup
         File.file?(File.expand_path(KamalBridge::DEFAULT_CONFIG_FILE))
       end
 
-      def version_remote_mode?
-        deployment_mode? || default_deploy_config?
-      end
-
-      def validate_deploy_mode?
+      def remote_command_mode?
         deployment_mode? || default_deploy_config?
       end
 
@@ -362,7 +358,7 @@ module KamalBackup
 
     desc "backup", "Run one database and Active Storage backup immediately"
     def backup
-      if deployment_mode?
+      if remote_command_mode?
         exec_remote(["kamal-backup", "backup"])
       else
         direct_app.backup
@@ -371,7 +367,7 @@ module KamalBackup
 
     desc "list", "List matching restic snapshots"
     def list
-      if deployment_mode?
+      if remote_command_mode?
         exec_remote(["kamal-backup", "list"])
       else
         puts(direct_app.snapshots)
@@ -380,7 +376,7 @@ module KamalBackup
 
     desc "check", "Run restic check and record the latest result"
     def check
-      if deployment_mode?
+      if remote_command_mode?
         exec_remote(["kamal-backup", "check"])
       else
         puts(direct_app.check)
@@ -389,7 +385,7 @@ module KamalBackup
 
     desc "evidence", "Print redacted backup, check, and restore-drill evidence as JSON"
     def evidence
-      if deployment_mode?
+      if remote_command_mode?
         exec_remote(["kamal-backup", "evidence"])
       else
         puts(direct_app.evidence)
@@ -398,7 +394,7 @@ module KamalBackup
 
     desc "validate", "Validate backup configuration without running a backup"
     def validate
-      if validate_deploy_mode?
+      if remote_command_mode?
         validate_deploy_config
       else
         direct_app.validate
@@ -433,7 +429,7 @@ module KamalBackup
 
     desc "version", "Print the running kamal-backup version"
     def version
-      if version_remote_mode?
+      if remote_command_mode?
         print_remote_version_status
       else
         puts(VERSION)

data/lib/kamal_backup/databases/sqlite.rb

@@ -1,5 +1,6 @@
 require "fileutils"
 require "tempfile"
+require "uri"
 require_relative "base"
 
 module KamalBackup
@@ -17,10 +18,7 @@ module KamalBackup
         source = sqlite_source
         Tempfile.create(["kamal-backup-", ".sqlite3"]) do |tempfile|
           tempfile.close
-          Command.capture(
-            CommandSpec.new(argv: ["sqlite3", source, ".backup #{sqlite_literal(tempfile.path)}"]),
-            redactor: redactor
-          )
+          backup_to_file(source, tempfile.path)
           restic.backup_file(
             tempfile.path,
             filename: database_filename(timestamp),
@@ -55,6 +53,40 @@ module KamalBackup
           config.required_value("SQLITE_DATABASE_PATH")
         end
 
+        def backup_to_file(source, target)
+          run_backup(source, target)
+        rescue CommandError => e
+          raise unless immutable_retry_safe?(source, e)
+
+          # Immutable mode skips WAL change detection, so only use it when no WAL sidecar exists.
+          run_backup(sqlite_immutable_uri(source), target)
+        end
+
+        def run_backup(source, target)
+          Command.capture(
+            CommandSpec.new(argv: ["sqlite3", source, ".backup #{sqlite_literal(target)}"]),
+            redactor: redactor
+          )
+        end
+
+        def immutable_retry_safe?(source, error)
+          readonly_database_error?(error) &&
+            !File.exist?("#{source}-wal") &&
+            !File.exist?("#{source}-shm")
+        end
+
+        def readonly_database_error?(error)
+          error.stderr.include?("readonly database") || error.message.include?("readonly database")
+        end
+
+        def sqlite_immutable_uri(source)
+          path = File.expand_path(source).split("/").map do |part|
+            URI.encode_www_form_component(part).gsub("+", "%20")
+          end.join("/")
+
+          "file:#{path}?immutable=1"
+        end
+
         def validate_scratch_restore_target(target)
           if File.expand_path(sqlite_source) == File.expand_path(target)
             raise ConfigurationError, "scratch SQLite path must differ from SQLITE_DATABASE_PATH"

data/lib/kamal_backup/version.rb

@@ -1,3 +1,3 @@
 module KamalBackup
-  VERSION = "0.2.5"
+  VERSION = "0.2.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kamal-backup
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - crmne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor