litestream 0.5.3-arm64-darwin → 0.5.4-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e62818c3cd5758ff7ff63831ff5e9196ba6734cd8bdbbbf828b1593dce48ac6
-  data.tar.gz: f0fc37c1a8f1723b880500307ba0b1ec79f620971be1dc7eadd888e5787ec247
+  metadata.gz: fea17404f07d31435edecb439529500b8beecb4b89726de3eaa1d7cf865c075e
+  data.tar.gz: 2abba49dd1dfb0cfdf95ae60e9df0cd85f8ae06b711a832d11fc50914b35a064
 SHA512:
-  metadata.gz: 7b8bb348df79657ff336e98733185ee7cc9dab56957890a27eb0fe257b6bf6b09300fa40f9264c384277a63310e3f91dc53990df190da719303d91b7ab92b2ab
-  data.tar.gz: c97a8ac25384e8993733bfd9abfd6b9b6658bfaa35fb0aaf081eda3473c7a2425ac9c35f6aae56d0c2a3afad58d3526a0321246b1f9f2dfa49d5c804b301f612
+  metadata.gz: 24cc852dd7b4d1cf19d6f72006b3c26cd1e9770ed3a06b5cfd0aad14d5a72311c1ecf410adb83e4cdfefefac641ab014376244e49995b5f4434e96ddd2657c03
+  data.tar.gz: 0d7c51ccb9e53a30ee0fb803aa11d4e62d96d923639b61710cb0dfd7dfecb08bf0732e51010093a9600f88840882414b960c60e0e5cff48027ef3e8b79759cfc

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-darwin
 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