litestream 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3437fcda9be45b8f50a4fcae89e6cc07d3ea590d7e3f0d2f10e50c9f8c6058b6
-  data.tar.gz: f53e83796ed362491b50929d2924d070b6efa166830f7de6195e39300121be81
+  metadata.gz: 8da245a396bc819cf0aa9bfae9a87f65a92047fd45a96bd8f8602eee6248adb6
+  data.tar.gz: 4bee567fab0ad7ab71d72c36091be4a32c4685ddfe1b69f6403c36ea927af437
 SHA512:
-  metadata.gz: d8731b80f97dee5bc512e4f4acd58aebb63a435379736d281edc8bd2b42e6cc524c2eb7a55fefc2cf93218b91b2fb12c4fe180685031c9924dacd73a918fe344
-  data.tar.gz: 209fec5c3e355675feeee661ca64194cae370b85cbe90e162aaa2df059b2ccc5806b44e94daf706c29140e106e716eb1d3505a5efeeec65dfecbe4ee763ece09
+  metadata.gz: 5b1ba5a3de6be15243513f10f37657c940cbd59471ae008434c73aa0a09b62869b7e940388003a254431ab503fafdc891f7cffcc95afcfa61c07e1f657617225
+  data.tar.gz: 34410a43ee4ab617e160a76989d4721d7c6b1861aa15d623602a7088d1b561266e40f2243e7c0a1d880778031d15b9ce71384ae1cf4a245494f21d2ea93426fc

data/README.md

@@ -92,9 +92,94 @@ bin/rails litestream:replicate -- -exec "foreman start"
 
 This example utilizes the `-exec` option available on [the `replicate` command](https://litestream.io/reference/replicate/) which provides basic process management, since Litestream will exit when the child process exits. In this example, we only launch our collection of Rails application processes (like Rails and SolidQueue, for example) after the Litestream replication process is ready.
 
-The rake task is the recommended way to interact with the Litestream replication process in your Rails application or Ruby project. But, you _can_ take full manual control over the replication process and simply run the `litestream replicate --config config/litestream.yml` command to start the Litestream process. Since the gem installs the native executable via Bundler, the `litestream` command will be available in your `PATH`.
+The Litestream `replicate` command supports the following options, which can be passed through the rake task:
+```shell
+-config PATH
+    Specifies the configuration file.
+    Defaults to /etc/litestream.yml
+
+-exec CMD
+    Executes a subcommand. Litestream will exit when the child
+    process exits. Useful for simple process management.
+
+-no-expand-env
+    Disables environment variable expansion in configuration file.
+```
+
+### Restoration
 
-The full set of commands available to the `litestream` executable are covered in Litestream's [command reference](https://litestream.io/reference/). Currently, only the `replicate` command is provided as a rake task by the gem.
+You can restore any replicated database at any point using the gem's provided `litestream:restore` rake task. This rake task requires that you specify which specific database you want to restore. As with the `litestream:replicate` task, you pass arguments to the rake task via argument forwarding. For example, to restore the production database, you would run:
+
+```shell
+bin/rails litestream:restore -- --database=storage/production.sqlite3
+# or
+bundle exec rake litestream:restore -- --database=storage/production.sqlite3
+```
+
+You can restore any of the databases specified in your `config/litestream.yml` file. The `--database` argument should be the path to the database file you want to restore and must match the value for the `path` key of one of your configured databases. The `litestream:restore` rake task will automatically load the configuration file and set the environment variables before calling the Litestream executable.
+
+If you need to pass arguments through the rake task to the underlying `litestream` command, that can be done with additional forwarded arguments:
+
+```shell
+bin/rails litestream:replicate -- --database=storage/production.sqlite3 --if-db-not-exists
+```
+
+You can forward arguments in whatever order you like, you simply need to ensure that the `--database` argument is present. You can also use either a single-dash `-database` or double-dash `--database` argument format. The Litestream `restore` command supports the following options, which can be passed through the rake task:
+
+```shell
+-o PATH
+    Output path of the restored database.
+    Defaults to original DB path.
+
+-if-db-not-exists
+    Returns exit code of 0 if the database already exists.
+
+-if-replica-exists
+    Returns exit code of 0 if no backups found.
+
+-parallelism NUM
+    Determines the number of WAL files downloaded in parallel.
+    Defaults to 8
+
+-replica NAME
+    Restore from a specific replica.
+    Defaults to replica with latest data.
+
+-generation NAME
+    Restore from a specific generation.
+    Defaults to generation with latest data.
+
+-index NUM
+    Restore up to a specific WAL index (inclusive).
+    Defaults to use the highest available index.
+
+-timestamp TIMESTAMP
+    Restore to a specific point-in-time.
+    Defaults to use the latest available backup.
+
+-config PATH
+    Specifies the configuration file.
+    Defaults to /etc/litestream.yml
+
+-no-expand-env
+    Disables environment variable expansion in configuration file.
+```
+
+### Additional commands
+
+The rake tasks are the recommended way to interact with the Litestream utility in your Rails application or Ruby project. But, you _can_ work directly with the Litestream CLI. Since the gem installs the native executable via Bundler, the `litestream` command will be available in your `PATH`.
+
+The full set of commands available to the `litestream` executable are covered in Litestream's [command reference](https://litestream.io/reference/), but can be summarized as:
+
+```shell
+litestream databases [arguments]
+litestream generations [arguments] DB_PATH|REPLICA_URL
+litestream replicate [arguments]
+litestream restore [arguments] DB_PATH|REPLICA_URL
+litestream snapshots [arguments] DB_PATH|REPLICA_URL
+litestream version
+litestream wal [arguments] DB_PATH|REPLICA_URL
+```
 
 ### Using in development
 

data/exe/litestream

@@ -5,7 +5,6 @@ require "litestream/commands"
 
 begin
   command = [Litestream::Commands.executable, *ARGV]
-  puts command.inspect
   exec(*command)
 rescue Litestream::Commands::UnsupportedPlatformException, Litestream::Commands::ExecutableNotFoundException => e
   warn("ERROR: " + e.message)

data/lib/litestream/commands.rb

@@ -6,16 +6,13 @@ module Litestream
     GEM_NAME = "litestream"
 
     # raised when the host platform is not supported by upstream litestream's binary releases
-    class UnsupportedPlatformException < StandardError
-    end
+    UnsupportedPlatformException = Class.new(StandardError)
 
     # raised when the litestream executable could not be found where we expected it to be
-    class ExecutableNotFoundException < StandardError
-    end
+    ExecutableNotFoundException = Class.new(StandardError)
 
     # raised when LITESTREAM_INSTALL_DIR does not exist
-    class DirectoryNotFoundException < StandardError
-    end
+    DirectoryNotFoundException = Class.new(StandardError)
 
     def self.platform
       [:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
@@ -74,9 +71,9 @@ module Litestream
 
     def self.replicate(argv = {})
       if Litestream.configuration
-        ENV["LITESTREAM_REPLICA_BUCKET"] = Litestream.configuration.replica_bucket
-        ENV["LITESTREAM_ACCESS_KEY_ID"] = Litestream.configuration.replica_key_id
-        ENV["LITESTREAM_SECRET_ACCESS_KEY"] = Litestream.configuration.replica_access_key
+        ENV["LITESTREAM_REPLICA_BUCKET"] ||= Litestream.configuration.replica_bucket
+        ENV["LITESTREAM_ACCESS_KEY_ID"] ||= Litestream.configuration.replica_key_id
+        ENV["LITESTREAM_SECRET_ACCESS_KEY"] ||= Litestream.configuration.replica_access_key
       end
 
       args = {
@@ -92,5 +89,32 @@ module Litestream
         exec(*command)
       end
     end
+
+    def self.restore(database, argv = {})
+      if Litestream.configuration
+        ENV["LITESTREAM_REPLICA_BUCKET"] ||= Litestream.configuration.replica_bucket
+        ENV["LITESTREAM_ACCESS_KEY_ID"] ||= Litestream.configuration.replica_key_id
+        ENV["LITESTREAM_SECRET_ACCESS_KEY"] ||= Litestream.configuration.replica_access_key
+      end
+
+      dir, file = File.split(database)
+      ext = File.extname(file)
+      base = File.basename(file, ext)
+      now = Time.now.utc.strftime("%Y%m%d%H%M%S")
+
+      args = {
+        "--config" => Rails.root.join("config", "litestream.yml").to_s,
+        "-o" => File.join(dir, "#{base}-#{now}#{ext}")
+      }.merge(argv).to_a.flatten.compact
+
+      command = [executable, "restore", *args, database]
+      puts command.inspect
+
+      # To release the resources of the Ruby process, just fork and exit.
+      # The forked process executes litestream and replaces itself.
+      if fork.nil?
+        exec(*command)
+      end
+    end
   end
 end

data/lib/litestream/version.rb

@@ -1,3 +1,3 @@
 module Litestream
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/litestream.rb

@@ -14,7 +14,6 @@ module Litestream
     attr_accessor :database_path, :replica_bucket, :replica_key_id, :replica_access_key
 
     def initialize
-      @mailer_sender = "donotreply@example.com"
     end
   end
 end

data/lib/tasks/litestream_tasks.rake

@@ -13,7 +13,7 @@ namespace :litestream do
     true
   end
 
-  desc "Start a process to monitor and continuously replicate the SQLite databases defined in your configuration file"
+  desc 'Monitor and continuously replicate SQLite databases defined in your config file, e.g. rake litestream:replicate -- -exec "foreman start"'
   task replicate: :environment do
     options = {}
     if (separator_index = ARGV.index("--"))
@@ -24,4 +24,16 @@ namespace :litestream do
 
     Litestream::Commands.replicate(options)
   end
+
+  desc "Restore a SQLite database from a Litestream replica, e.g. rake litestream:restore -- -database=storage/production.sqlite3"
+  task restore: :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
+
+    Litestream::Commands.restore(options.delete("--database") || options.delete("-database"), options)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: litestream
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Stephen Margheim
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-12 00:00:00.000000000 Z
+date: 2024-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip