litestream 0.4.0-x86_64-darwin → 0.5.1-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd21647849c87548da000c229642c5a9ee15acf7943fce4f3feb66a8bbef56aa
-  data.tar.gz: 46b7d1ca27b77e9d80aea932d4c079fc09a79c72dacaa504c1f0ddd90b2fd443
+  metadata.gz: 49adc00f53f6eed0427ea5a203c31bfc5e952b09315f1c6efdacaa063e039f0c
+  data.tar.gz: 462d08c90c1845f3dcb910c032859fef21c2cec4fc0320c3ef92035299dabeb3
 SHA512:
-  metadata.gz: 9fe4001f2e83c2ec1f81c05f328b69e5bf480ea8fe68faf19f7ba289e4551748ec2a21ca2791c2a00def8d24622d7207964557210763cc715acd1b05323eeed5
-  data.tar.gz: 23e4f6a6dec9e1936120ac4b6e3ff34c602da447848434442a49cb40b955325a62ca0cb57c96f21f020adcdae7a921b6978cd7a27da68d0976b8eec5ea02e528
+  metadata.gz: 536cc43c37f5cd2ccf37a562b44f90ce5b639d0c709bc641bca26c3e96d68426756b8f3749394dbb0039728a8be5c37b52d4345184a1c9a29bf272dd1e82b872
+  data.tar.gz: 369f08b98c04530f3fb46951b79f88054f7a7c8dc6737b62231df685aed59d6a6eb106bdaae69d28cbc0082a727c0e1a0bf12df8308cd8e997340a9864b49447

data/README.md

@@ -165,6 +165,47 @@ You can forward arguments in whatever order you like, you simply need to ensure
     Disables environment variable expansion in configuration file.
 ```
 
+### Introspection
+
+Litestream offers a handful of commands that allow you to introspect the state of your replication. The gem provides a few rake tasks that wrap these commands for you. For example, you can list the databases that Litestream is configured to replicate:
+
+```shell
+bin/rails litestream:databases
+```
+
+This will return a list of databases and their configured replicas:
+
+```
+path                                                 replicas
+/Users/you/Code/your-app/storage/production.sqlite3  s3
+```
+
+You can also list the generations of a specific database:
+
+```shell
+bin/rails litestream:generations -- --database=storage/production.sqlite3
+```
+
+This will list all generations for the specified database, including stats about their lag behind the primary database and the time range they cover.
+
+```
+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:
+
+```shell
+bin/rails litestream:snapshots -- --database=storage/production.sqlite3
+```
+
+This command lists snapshots available for that specified database:
+
+```
+replica  generation        index  size     created
+s3       a295b16a796689f3  1      4645465  2024-04-17T00:01:19Z
+```
+
 ### 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`.

data/lib/litestream/commands.rb

@@ -14,106 +14,120 @@ module Litestream
     # raised when LITESTREAM_INSTALL_DIR does not exist
     DirectoryNotFoundException = Class.new(StandardError)
 
-    def self.platform
-      [:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
-    end
+    # raised when a litestream command requires a database argument but it isn't provided
+    DatabaseRequiredException = Class.new(StandardError)
+
+    class << self
+      def platform
+        [:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
+      end
 
-    def self.executable(exe_path: DEFAULT_DIR)
-      litestream_install_dir = ENV["LITESTREAM_INSTALL_DIR"]
-      if litestream_install_dir
-        if File.directory?(litestream_install_dir)
-          warn "NOTE: using LITESTREAM_INSTALL_DIR to find litestream executable: #{litestream_install_dir}"
-          exe_path = litestream_install_dir
-          exe_file = File.expand_path(File.join(litestream_install_dir, "litestream"))
+      def executable(exe_path: DEFAULT_DIR)
+        litestream_install_dir = ENV["LITESTREAM_INSTALL_DIR"]
+        if litestream_install_dir
+          if File.directory?(litestream_install_dir)
+            warn "NOTE: using LITESTREAM_INSTALL_DIR to find litestream executable: #{litestream_install_dir}"
+            exe_path = litestream_install_dir
+            exe_file = File.expand_path(File.join(litestream_install_dir, "litestream"))
+          else
+            raise DirectoryNotFoundException, <<~MESSAGE
+              LITESTREAM_INSTALL_DIR is set to #{litestream_install_dir}, but that directory does not exist.
+            MESSAGE
+          end
         else
-          raise DirectoryNotFoundException, <<~MESSAGE
-            LITESTREAM_INSTALL_DIR is set to #{litestream_install_dir}, but that directory does not exist.
-          MESSAGE
-        end
-      else
-        if Litestream::Upstream::NATIVE_PLATFORMS.keys.none? { |p| Gem::Platform.match_gem?(Gem::Platform.new(p), GEM_NAME) }
-          raise UnsupportedPlatformException, <<~MESSAGE
-            litestream-ruby does not support the #{platform} platform
-            Please install litestream following instructions at https://litestream.io/install
-          MESSAGE
+          if Litestream::Upstream::NATIVE_PLATFORMS.keys.none? { |p| Gem::Platform.match_gem?(Gem::Platform.new(p), GEM_NAME) }
+            raise UnsupportedPlatformException, <<~MESSAGE
+              litestream-ruby does not support the #{platform} platform
+              Please install litestream following instructions at https://litestream.io/install
+            MESSAGE
+          end
+
+          exe_file = Dir.glob(File.expand_path(File.join(exe_path, "*", "litestream"))).find do |f|
+            Gem::Platform.match_gem?(Gem::Platform.new(File.basename(File.dirname(f))), GEM_NAME)
+          end
         end
 
-        exe_file = Dir.glob(File.expand_path(File.join(exe_path, "*", "litestream"))).find do |f|
-          Gem::Platform.match_gem?(Gem::Platform.new(File.basename(File.dirname(f))), GEM_NAME)
-        end
-      end
+        if exe_file.nil? || !File.exist?(exe_file)
+          raise ExecutableNotFoundException, <<~MESSAGE
+            Cannot find the litestream executable for #{platform} in #{exe_path}
 
-      if exe_file.nil? || !File.exist?(exe_file)
-        raise ExecutableNotFoundException, <<~MESSAGE
-          Cannot find the litestream executable for #{platform} in #{exe_path}
+            If you're using bundler, please make sure you're on the latest bundler version:
 
-          If you're using bundler, please make sure you're on the latest bundler version:
+                gem install bundler
+                bundle update --bundler
 
-              gem install bundler
-              bundle update --bundler
+            Then make sure your lock file includes this platform by running:
 
-          Then make sure your lock file includes this platform by running:
+                bundle lock --add-platform #{platform}
+                bundle install
 
-              bundle lock --add-platform #{platform}
-              bundle install
+            See `bundle lock --help` output for details.
+
+            If you're still seeing this message after taking those steps, try running
+            `bundle config` and ensure `force_ruby_platform` isn't set to `true`. See
+            https://github.com/fractaledmind/litestream-ruby#check-bundle_force_ruby_platform
+            for more details.
+          MESSAGE
+        end
 
-          See `bundle lock --help` output for details.
+        exe_file
+      end
 
-          If you're still seeing this message after taking those steps, try running
-          `bundle config` and ensure `force_ruby_platform` isn't set to `true`. See
-          https://github.com/fractaledmind/litestream-ruby#check-bundle_force_ruby_platform
-          for more details.
-        MESSAGE
+      def replicate(argv = {})
+        execute("replicate", argv)
       end
 
-      exe_file
-    end
+      def restore(database, argv = {})
+        raise DatabaseRequiredException, "database argument is required for restore command, e.g. litestream:restore -- --database=path/to/database.sqlite" if database.nil?
+
+        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 = {
+          "-o" => File.join(dir, "#{base}-#{now}#{ext}")
+        }.merge(argv)
 
-    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
+        execute("restore", args, database)
       end
 
-      args = {
-        "--config" => Rails.root.join("config", "litestream.yml").to_s
-      }.merge(argv).to_a.flatten.compact
+      def databases(argv = {})
+        execute("databases", argv)
+      end
 
-      command = [executable, "replicate", *args]
-      puts command.inspect
+      def generations(database, argv = {})
+        raise DatabaseRequiredException, "database argument is required for generations command, e.g. litestream:generations -- --database=path/to/database.sqlite" if database.nil?
 
-      # 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)
+        execute("generations", argv, database)
       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
+      def snapshots(database, argv = {})
+        raise DatabaseRequiredException, "database argument is required for snapshots command, e.g. litestream:snapshots -- --database=path/to/database.sqlite" if database.nil?
+
+        execute("snapshots", argv, database)
       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")
+      private
 
-      args = {
-        "--config" => Rails.root.join("config", "litestream.yml").to_s,
-        "-o" => File.join(dir, "#{base}-#{now}#{ext}")
-      }.merge(argv).to_a.flatten.compact
+      def execute(command, argv = {}, database = nil)
+        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
 
-      command = [executable, "restore", *args, database]
-      puts command.inspect
+        args = {
+          "--config" => Rails.root.join("config", "litestream.yml").to_s
+        }.merge(argv).to_a.flatten.compact
+        cmd = [executable, command, *args, database].compact
 
-      # 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)
+        # To release the resources of the Ruby process, just fork and exit.
+        # The forked process executes litestream and replaces itself.
+        if fork.nil?
+          puts cmd.inspect if ENV["DEBUG"]
+          exec(*cmd)
+        end
       end
     end
   end

data/lib/litestream/version.rb

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

data/lib/tasks/litestream_tasks.rake

@@ -36,4 +36,40 @@ namespace :litestream do
 
     Litestream::Commands.restore(options.delete("--database") || options.delete("-database"), options)
   end
+
+  desc "List all databases and associated replicas in the config file, e.g. rake litestream:databases -- -no-expand-env"
+  task databases: :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.databases(options)
+  end
+
+  desc "List all generations for a database or replica, e.g. rake litestream:generations -- -database=storage/production.sqlite3"
+  task generations: :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.generations(options.delete("--database") || options.delete("-database"), options)
+  end
+
+  desc "List all snapshots for a database or replica, e.g. rake litestream:snapshots -- -database=storage/production.sqlite3"
+  task snapshots: :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.snapshots(options.delete("--database") || options.delete("-database"), options)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: litestream
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: x86_64-darwin
 authors:
 - Stephen Margheim