litestream 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213a742471df552871cb90f5f092a110491e618bea9036a3e206d46c68cd8593
-  data.tar.gz: cdf0264bcb4c20658e3a27636ea1e58ba42c50a0d184730acae7bee0cec65727
+  metadata.gz: 54afac4af36cb4d209c3794111131de4947b5744cb703eca6f13b1401721b516
+  data.tar.gz: 6b740f328b644690153d61ae83c895c773b2af47bbbc772cc69307624c2ab975
 SHA512:
-  metadata.gz: 4a09739e36c3811d424e25e3a3d5f1abe1c21771409dd8b8162893b4e92df8a3699fc8272ec01b85005553a9147c43e3745d2ad3f3a4a77346051be826ab6242
-  data.tar.gz: e1ae61215ca82f440f13653ff5c24de815cff766e70714aa53b477b2e2e64c52391ef47520668db216af8160f6192e9b7e7092984705f24f70df6395f8bf56b6
+  metadata.gz: 9213864ec337125ee7419b143e38a68c2e0e92610d6f68ce61c2ebb0c78180b422c95b5effbb7e79ec25338d750ef06a860d636e45e780cfb148fc22ba31d472
+  data.tar.gz: 26d80893a73ef2ad642c8ec693313383248ce46db89326c20bb3c051f7d5213afb74d6e64f3ea056ad6908e0e41bf8beccdfc5d3892024d6982caa9f7ac62dd1

data/README.md

@@ -53,9 +53,11 @@ The gem streamlines the configuration process by providing a default configurati
 
 ```yaml
 dbs:
-  - path: $LITESTREAM_DATABASE_PATH
+  - path: storage/production.sqlite3
     replicas:
-      - url: $LITESTREAM_REPLICA_BUCKET
+      - type: s3
+        bucket: $LITESTREAM_REPLICA_BUCKET
+        path: storage/production.sqlite3
         access-key-id: $LITESTREAM_ACCESS_KEY_ID
         secret-access-key: $LITESTREAM_SECRET_ACCESS_KEY
 ```
@@ -65,7 +67,6 @@ The gem also provides a default initializer file at `config/initializers/litestr
 ```ruby
 litestream_credentials = Rails.application.credentials.litestream
 Litestream.configure do |config|
-  config.database_path = ActiveRecord::Base.connection_db_config.database
   config.replica_bucket = litestream_credentials.replica_bucket
   config.replica_key_id = litestream_credentials.replica_key_id
   config.replica_access_key = litestream_credentials.replica_access_key
@@ -240,7 +241,48 @@ replica  generation        index  size     created
 s3       a295b16a796689f3  1      4645465  2024-04-17T00:01:19Z
 ```
 
-### Additional commands
+### 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.
+
+The `Litestream::Commands.databases` method returns an array of hashes with the "path" and "replicas" keys for each database:
+
+```ruby
+Litestream::Commands.databases
+# => [{"path"=>"/Users/you/Code/your-app/storage/production.sqlite3", "replicas"=>"s3"}]
+```
+
+The `Litestream::Commands.generations` method returns an array of hashes with the "name", "generation", "lag", "start", and "end" keys for each generation:
+
+```ruby
+Litestream::Commands.generations('storage/production.sqlite3')
+# => [{"name"=>"s3", "generation"=>"5f4341bc3d22d615", "lag"=>"3s", "start"=>"2024-04-17T19:48:09Z", "end"=>"2024-04-17T19:48:09Z"}]
+```
+
+The `Litestream::Commands.snapshots` method returns an array of hashes with the "replica", "generation", "index", "size", and "created" keys for each snapshot:
+
+```ruby
+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:
+
+```ruby
+Litestream::Commands.restore('storage/production.sqlite3')
+# => "storage/production-20240418090048.sqlite3"
+```
+
+Finally, you can verify the integrity of a restored database using the `Litestream::Commands.verify` method, which returns a hash with the "size" and "tables" keys for the original and restored databases:
+
+```ruby
+Litestream::Commands.verify('storage/production.sqlite3')
+# => {"size"=>{"original"=>21688320, "restored"=>21688320}, "tables"=>{"original"=>9, "restored"=>9}}
+```
+
+You _can_ start the replication process using the `Litestream::Commands.replicate` method, but this is not recommended. The replication process should be managed by Litestream itself, and you should not need to manually start it.
+
+### Running commands from CLI
 
 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`.
 
@@ -272,7 +314,6 @@ Once you have a MinIO server running, you can create a bucket for Litestream to
 
 ```ruby
 Litestream.configure do |config|
-  config.database_path = ActiveRecord::Base.connection_db_config.database
   config.replica_bucket = "s3://mybkt.localhost:9000/"
   config.replica_key_id = "minioadmin"
   config.replica_access_key = "minioadmin"

data/lib/litestream/commands.rb

@@ -76,11 +76,11 @@ module Litestream
         exe_file
       end
 
-      def replicate(async: true, **argv)
-        execute("replicate", argv, async: async)
+      def replicate(async: false, **argv)
+        execute("replicate", argv, async: async, hashify: false)
       end
 
-      def restore(database, async: true, **argv)
+      def restore(database, async: false, **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)
@@ -93,28 +93,12 @@ module Litestream
           "-o" => backup
         }.merge(argv)
 
-        execute("restore", args, database, async: async)
+        execute("restore", args, database, async: async, hashify: false)
 
         backup
       end
 
-      def databases(async: true, **argv)
-        execute("databases", argv, async: async)
-      end
-
-      def generations(database, async: true, **argv)
-        raise DatabaseRequiredException, "database argument is required for generations command, e.g. litestream:generations -- --database=path/to/database.sqlite" if database.nil?
-
-        execute("generations", argv, database, async: async)
-      end
-
-      def snapshots(database, async: true, **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, async: async)
-      end
-
-      def verify(database, async: true, **argv)
+      def verify(database, async: false, **argv)
         raise DatabaseRequiredException, "database argument is required for verify command, e.g. litestream:verify -- --database=path/to/database.sqlite" if database.nil? || !File.exist?(database)
 
         backup = restore(database, async: false, **argv)
@@ -129,14 +113,35 @@ module Litestream
         Dir.glob(backup + "*").each { |file| File.delete(file) }
 
         {
-          size: {original: original_size, restored: restored_size},
-          tables: {original: original_tables_count, restored: restored_tables_count}
+          "size" => {"original" => original_size, "restored" => restored_size},
+          "tables" => {"original" => original_tables_count, "restored" => restored_tables_count}
         }
       end
 
+      def databases(async: false, **argv)
+        execute("databases", argv, async: async, hashify: true)
+      end
+
+      def generations(database, async: false, **argv)
+        raise DatabaseRequiredException, "database argument is required for generations command, e.g. litestream:generations -- --database=path/to/database.sqlite" if database.nil?
+
+        execute("generations", argv, database, async: async, hashify: true)
+      end
+
+      def snapshots(database, async: false, **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, async: async, hashify: true)
+      end
+
       private
 
-      def execute(command, argv = {}, database = nil, async: true)
+      def execute(command, argv = {}, database = nil, async: false, hashify: false)
+        cmd = prepare(command, argv, database)
+        run(cmd, async: async, hashify: hashify)
+      end
+
+      def prepare(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
@@ -149,14 +154,24 @@ module Litestream
         cmd = [executable, command, *args, database].compact
         puts cmd.inspect if ENV["DEBUG"]
 
+        cmd
+      end
+
+      def run(cmd, async: false, hashify: false)
         if async
           # To release the resources of the Ruby process, just fork and exit.
           # The forked process executes litestream and replaces itself.
           exec(*cmd) if fork.nil?
         else
-          system(*cmd)
+          out = `#{cmd.join(" ")}`
+          text_table_to_hashes(out) if hashify
         end
       end
+
+      def text_table_to_hashes(string)
+        keys, *rows = string.split("\n").map { _1.split(/\s+/) }
+        rows.map { keys.zip(_1).to_h }
+      end
     end
   end
 end

data/lib/litestream/version.rb

@@ -1,3 +1,3 @@
 module Litestream
-  VERSION = "0.5.3"
+  VERSION = "0.5.4"
 end

data/lib/litestream.rb

@@ -11,7 +11,7 @@ module Litestream
   end
 
   class Configuration
-    attr_accessor :database_path, :replica_bucket, :replica_key_id, :replica_access_key
+    attr_accessor :replica_bucket, :replica_key_id, :replica_access_key
 
     def initialize
     end

data/lib/tasks/litestream_tasks.rake

@@ -21,8 +21,9 @@ namespace :litestream do
         .map { |pair| pair.split("=") }
         .each { |opt| options[opt[0]] = opt[1] || nil }
     end
+    options.symbolize_keys!
 
-    Litestream::Commands.replicate(**options)
+    Litestream::Commands.replicate(async: true, **options)
   end
 
   desc "Restore a SQLite database from a Litestream replica, e.g. rake litestream:restore -- -database=storage/production.sqlite3"
@@ -33,8 +34,10 @@ namespace :litestream do
         .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.restore(options.delete("--database") || options.delete("-database"), **options)
+    Litestream::Commands.restore(database, async: true, **options)
   end
 
   desc "List all databases and associated replicas in the config file, e.g. rake litestream:databases -- -no-expand-env"
@@ -45,8 +48,9 @@ namespace :litestream do
         .map { |pair| pair.split("=") }
         .each { |opt| options[opt[0]] = opt[1] || nil }
     end
+    options.symbolize_keys!
 
-    Litestream::Commands.databases(**options)
+    Litestream::Commands.databases(async: true, **options)
   end
 
   desc "List all generations for a database or replica, e.g. rake litestream:generations -- -database=storage/production.sqlite3"
@@ -57,8 +61,10 @@ namespace :litestream do
         .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.generations(options.delete("--database") || options.delete("-database"), **options)
+    Litestream::Commands.generations(database, async: true, **options)
   end
 
   desc "List all snapshots for a database or replica, e.g. rake litestream:snapshots -- -database=storage/production.sqlite3"
@@ -69,8 +75,10 @@ namespace :litestream do
         .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.snapshots(options.delete("--database") || options.delete("-database"), **options)
+    Litestream::Commands.snapshots(database, async: true, **options)
   end
 
   desc "verify backup of SQLite database from a Litestream replica, e.g. rake litestream:verify -- -database=storage/production.sqlite3"
@@ -81,8 +89,10 @@ namespace :litestream do
         .map { |pair| pair.split("=") }
         .each { |opt| options[opt[0]] = opt[1] || nil }
     end
+    database = options.delete("--database") || options.delete("-database")
+    options.symbolize_keys!
 
-    result = Litestream::Commands.verify(options.delete("--database") || options.delete("-database"), **options)
+    result = Litestream::Commands.verify(database, async: true, **options)
 
     puts <<~TXT if result
 

metadata

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