litestream 0.5.3-arm64-linux → 0.5.4-arm64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 461ce8410dcec75959b08a1553b50c689183bc0b18423872a6cc56f237ac9f5f
-  data.tar.gz: 996a1f581cd30ec2df1e4aae99d6eea7507b6534d48288ef66c9a4612769398e
+  metadata.gz: 849776cf6f71d3d717bf74ab201bf5200b702ce4202b4bec140bea2f4cc35842
+  data.tar.gz: 807fcdfb94d05ae89a4d0435e454660d78eb77e021491deba18e5b767a25d6ba
 SHA512:
-  metadata.gz: 187c5d89f2effb432982d1b9e1313e7a08ca042bad35fdd56ec59487090f588bdaf5725a2a57f47bbed5599ade4011df48844e0d0fe56a08b02292f9764c5bcf
-  data.tar.gz: 70b6249a710ce7287ce59280d97afee71af1240b952d06e22e4328e07fb63e23fcfe60d9613c07641ec3457ee8865441250df305579db6bde3ba9ce5a2f73492
+  metadata.gz: f8a79526448d1eb7255d3021702cfd40e239722ea1e4bdc5f9e668cccf54f363f5e54c8eb36996d7ad95d3c79ee96d368f4b73c358d24b38492a0fab760fd786
+  data.tar.gz: a15b31993f0d690ae692313ed0329ebf60e9a60557d8513d258008900d91d251ee899216b9026e07502a8f34a1d8ef595c78fca0a19ac7da1f4b6c569d87bec4

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: arm64-linux
 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