Add wal command

Author: alxvernier

README.md

@@ -368,7 +368,7 @@ name  generation        lag     start                 end
 s3    a295b16a796689f3  -156ms  2024-04-17T00:01:19Z  2024-04-17T00:01:19Z
 ```
 
-Finally, you can list the snapshots available for a database:
+You can list the snapshots available for a database:
 
 ```shell
 bin/rails litestream:snapshots -- --database=storage/production.sqlite3
@@ -381,6 +381,19 @@ replica  generation        index  size     created
 s3       a295b16a796689f3  1      4645465  2024-04-17T00:01:19Z
 ```
 
+Finally, you can list the wal files available for a database:
+
+```shell
+bin/rails litestream:wal -- --database=storage/production.sqlite3
+```
+
+This command lists wal files available for that specified database:
+
+```
+replica  generation        index  offset    size     created
+s3       a295b16a796689f3  1      0         2036     2024-04-17T00:01:19Z
+```
+
 ### Running commands from Ruby
 
 In addition to the provided rake tasks, you can also run Litestream commands directly from Ruby. The gem provides a `Litestream::Commands` module that wraps the Litestream CLI commands. This is particularly useful for the introspection commands, as you can use the output in your Ruby code.
@@ -406,7 +419,14 @@ Litestream::Commands.snapshots('storage/production.sqlite3')
 # => [{"replica"=>"s3", "generation"=>"5f4341bc3d22d615", "index"=>"0", "size"=>"4645465", "created"=>"2024-04-17T19:48:09Z"}]
 ```
 
-You can also restore a database programatically using the `Litestream::Commands.restore` method, which returns the path to the restored database:
+The `Litestream::Commands.wal` method returns an array of hashes with the "replica", "generation", "index", "offset","size", and "created" keys for each wal:
+
+```ruby
+Litestream::Commands.wal('storage/production.sqlite3')
+# => [{"replica"=>"s3", "generation"=>"5f4341bc3d22d615", "index"=>"0",  "offset"=>"0", "size"=>"2036", "created"=>"2024-04-17T19:48:09Z"}]
+```
+
+You can also restore a database programmatically using the `Litestream::Commands.restore` method, which returns the path to the restored database:
 
 ```ruby
 Litestream::Commands.restore('storage/production.sqlite3')

lib/litestream/commands.rb

@@ -104,6 +104,12 @@ def snapshots(database, async: false, **argv)
         execute("snapshots", argv, database, async: async, tabled_output: true)
       end
 
+      def wal(database, async: false, **argv)
+        raise DatabaseRequiredException, "database argument is required for wal command, e.g. litestream:wal -- --database=path/to/database.sqlite" if database.nil?
+
+        execute("wal", argv, database, async: async, tabled_output: true)
+      end
+
       private
 
       def execute(command, argv = {}, database = nil, async: false, tabled_output: false)

lib/tasks/litestream_tasks.rake

@@ -75,4 +75,18 @@ namespace :litestream do
 
     Litestream::Commands.snapshots(database, async: true, **options)
   end
+
+  desc "List all wal files for a database or replica, for example `rake litestream:wal -- -database=storage/production.sqlite3`"
+  task wal: :environment do
+    options = {}
+    if (separator_index = ARGV.index("--"))
+      ARGV.slice(separator_index + 1, ARGV.length)
+        .map { |pair| pair.split("=") }
+        .each { |opt| options[opt[0]] = opt[1] || nil }
+    end
+    database = options.delete("--database") || options.delete("-database")
+    options.symbolize_keys!
+
+    Litestream::Commands.wal(database, async: true, **options)
+  end
 end

test/litestream/test_commands.rb

@@ -689,4 +689,137 @@ def test_snapshots_does_not_set_env_var_from_config_when_env_vars_already_set
       assert_equal "original_access", ENV["LITESTREAM_SECRET_ACCESS_KEY"]
     end
   end
+
+  class TestWalCommand < TestCommands
+    def test_wal_with_no_options
+      stub = proc do |cmd, async|
+        executable, command, *argv = cmd
+        assert_match Regexp.new("exe/test/litestream"), executable
+        assert_equal "wal", command
+        assert_equal 3, argv.size
+        assert_equal "--config", argv[0]
+        assert_match Regexp.new("dummy/config/litestream.yml"), argv[1]
+        assert_equal "db/test.sqlite3", argv[2]
+      end
+      Litestream::Commands.stub :run, stub do
+        Litestream::Commands.wal("db/test.sqlite3")
+      end
+    end
+
+    def test_wal_with_boolean_option
+      stub = proc do |cmd, async|
+        executable, command, *argv = cmd
+        assert_match Regexp.new("exe/test/litestream"), executable
+        assert_equal "wal", command
+        assert_equal 4, argv.size
+        assert_equal "--config", argv[0]
+        assert_match Regexp.new("dummy/config/litestream.yml"), argv[1]
+        assert_equal "--if-db-not-exists", argv[2]
+        assert_equal "db/test.sqlite3", argv[3]
+      end
+      Litestream::Commands.stub :run, stub do
+        Litestream::Commands.wal("db/test.sqlite3", "--if-db-not-exists" => nil)
+      end
+    end
+
+    def test_wal_with_string_option
+      stub = proc do |cmd, async|
+        executable, command, *argv = cmd
+        assert_match Regexp.new("exe/test/litestream"), executable
+        assert_equal "wal", command
+        assert_equal 5, argv.size
+        assert_equal "--config", argv[0]
+        assert_match Regexp.new("dummy/config/litestream.yml"), argv[1]
+        assert_equal "--parallelism", argv[2]
+        assert_equal 10, argv[3]
+        assert_equal "db/test.sqlite3", argv[4]
+      end
+      Litestream::Commands.stub :run, stub do
+        Litestream::Commands.wal("db/test.sqlite3", "--parallelism" => 10)
+      end
+    end
+
+    def test_wal_with_config_option
+      stub = proc do |cmd, async|
+        executable, command, *argv = cmd
+        assert_match Regexp.new("exe/test/litestream"), executable
+        assert_equal "wal", command
+        assert_equal 3, argv.size
+        assert_equal "--config", argv[0]
+        assert_equal "CONFIG", argv[1]
+        assert_equal "db/test.sqlite3", argv[2]
+      end
+      Litestream::Commands.stub :run, stub do
+        Litestream::Commands.wal("db/test.sqlite3", "--config" => "CONFIG")
+      end
+    end
+
+    def test_wal_sets_replica_bucket_env_var_from_config_when_env_var_not_set
+      Litestream.replica_bucket = "mybkt"
+
+      Litestream::Commands.stub :run, nil do
+        Litestream::Commands.wal("db/test.sqlite3")
+      end
+
+      assert_equal "mybkt", ENV["LITESTREAM_REPLICA_BUCKET"]
+      assert_nil ENV["LITESTREAM_ACCESS_KEY_ID"]
+      assert_nil ENV["LITESTREAM_SECRET_ACCESS_KEY"]
+    end
+
+    def test_wal_sets_replica_key_id_env_var_from_config_when_env_var_not_set
+      Litestream.replica_key_id = "mykey"
+
+      Litestream::Commands.stub :run, nil do
+        Litestream::Commands.wal("db/test.sqlite3")
+      end
+
+      assert_nil ENV["LITESTREAM_REPLICA_BUCKET"]
+      assert_equal "mykey", ENV["LITESTREAM_ACCESS_KEY_ID"]
+      assert_nil ENV["LITESTREAM_SECRET_ACCESS_KEY"]
+    end
+
+    def test_wal_sets_replica_access_key_env_var_from_config_when_env_var_not_set
+      Litestream.replica_access_key = "access"
+
+      Litestream::Commands.stub :run, nil do
+        Litestream::Commands.wal("db/test.sqlite3")
+      end
+
+      assert_nil ENV["LITESTREAM_REPLICA_BUCKET"]
+      assert_nil ENV["LITESTREAM_ACCESS_KEY_ID"]
+      assert_equal "access", ENV["LITESTREAM_SECRET_ACCESS_KEY"]
+    end
+
+    def test_wal_sets_all_env_vars_from_config_when_env_vars_not_set
+      Litestream.replica_bucket = "mybkt"
+      Litestream.replica_key_id = "mykey"
+      Litestream.replica_access_key = "access"
+
+      Litestream::Commands.stub :run, nil do
+        Litestream::Commands.wal("db/test.sqlite3")
+      end
+
+      assert_equal "mybkt", ENV["LITESTREAM_REPLICA_BUCKET"]
+      assert_equal "mykey", ENV["LITESTREAM_ACCESS_KEY_ID"]
+      assert_equal "access", ENV["LITESTREAM_SECRET_ACCESS_KEY"]
+    end
+
+    def test_wal_does_not_set_env_var_from_config_when_env_vars_already_set
+      ENV["LITESTREAM_REPLICA_BUCKET"] = "original_bkt"
+      ENV["LITESTREAM_ACCESS_KEY_ID"] = "original_key"
+      ENV["LITESTREAM_SECRET_ACCESS_KEY"] = "original_access"
+
+      Litestream.replica_bucket = "mybkt"
+      Litestream.replica_key_id = "mykey"
+      Litestream.replica_access_key = "access"
+
+      Litestream::Commands.stub :run, nil do
+        Litestream::Commands.wal("db/test.sqlite3")
+      end
+
+      assert_equal "original_bkt", ENV["LITESTREAM_REPLICA_BUCKET"]
+      assert_equal "original_key", ENV["LITESTREAM_ACCESS_KEY_ID"]
+      assert_equal "original_access", ENV["LITESTREAM_SECRET_ACCESS_KEY"]
+    end
+  end
 end

test/tasks/test_litestream_tasks.rb

@@ -11,6 +11,7 @@ def setup
     Rake::Task["litestream:databases"].reenable
     Rake::Task["litestream:generations"].reenable
     Rake::Task["litestream:snapshots"].reenable
+    Rake::Task["litestream:wal"].reenable
   end
 
   def teardown
@@ -218,4 +219,46 @@ def test_snapshots_task_with_arguments_without_separator
       fake.verify
     end
   end
+
+  class TestWalTask < TestLitestreamTasks
+    def test_wal_task_with_only_database_using_single_dash
+      ARGV.replace ["--", "-database=db/test.sqlite3"]
+      fake = Minitest::Mock.new
+      fake.expect :call, nil, ["db/test.sqlite3"], async: true
+      Litestream::Commands.stub :wal, fake do
+        Rake.application.invoke_task "litestream:wal"
+      end
+      fake.verify
+    end
+
+    def test_wal_task_with_only_database_using_double_dash
+      ARGV.replace ["--", "--database=db/test.sqlite3"]
+      fake = Minitest::Mock.new
+      fake.expect :call, nil, ["db/test.sqlite3"], async: true
+      Litestream::Commands.stub :wal, fake do
+        Rake.application.invoke_task "litestream:wal"
+      end
+      fake.verify
+    end
+
+    def test_wal_task_with_arguments
+      ARGV.replace ["--", "-database=db/test.sqlite3", "--if-db-not-exists"]
+      fake = Minitest::Mock.new
+      fake.expect :call, nil, ["db/test.sqlite3"], async: true, "--if-db-not-exists": nil
+      Litestream::Commands.stub :wal, fake do
+        Rake.application.invoke_task "litestream:wal"
+      end
+      fake.verify
+    end
+
+    def test_wal_task_with_arguments_without_separator
+      ARGV.replace ["-database=db/test.sqlite3"]
+      fake = Minitest::Mock.new
+      fake.expect :call, nil, [nil], async: true
+      Litestream::Commands.stub :wal, fake do
+        Rake.application.invoke_task "litestream:wal"
+      end
+      fake.verify
+    end
+  end
 end