litestream 0.13.0-x86_64-darwin → 0.14.0-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 884d1c34c9ed520b94a279d5b74eb81334e6c86ff32355c71f6b7c46513ca69e
-  data.tar.gz: 3d9b814d3e87afda563ecb17c6458bdb2525c014e9a86337a493cb9ade0b0d69
+  metadata.gz: 1bf4ecef5154a30f83749368b3120b9aa925cf3a75bee03e54086ddec25c27db
+  data.tar.gz: 436704c8aad09afa36147cef521c9882eadf6c4badb68d4635b695d69d4631a4
 SHA512:
-  metadata.gz: 8f6a700b9ddcca9ccfbdbf507a6c34c71c027197271903f41f0cc43c83c4ec646c86d6749a6df12bff138074481f109e39321dda7600e41da7ac2352e60fb123
-  data.tar.gz: 6169ff6ea2fc1e1b7eff96278cd59a21efdb2505cd0423384c47654e36af446bdf0a5957bb973ede31a118544d1756ee262fc35ecfbe14f142b61d3730be309c
+  metadata.gz: 33c8b011eb9d012585d4c94cea5e560ab3da96c6dec4b07561f5390ef78e679ba338ec044429cac10cb08f0a3eb2961568cfdf04133858cce572617e4a69ec2b
+  data.tar.gz: d5c44ae0fcb94ac747522880eb6e4adbc102bde7b285bc90e79bfb92f1104224d5fff1c12c4a90fc13f248281a58f6631387b97d1352f4fce481220a0a642bff

data/README.md

@@ -80,24 +80,27 @@ LITESTREAM_INSTALL_DIR=.bin
 
 You configure the Litestream executable through the [`config/litestream.yml` file](https://litestream.io/reference/config/), which is a standard Litestream configuration file as if Litestream was running in a traditional installation.
 
-The gem streamlines the configuration process by providing a default configuration file for you. This configuration file will backup all SQLite databases defined in your `config/database.yml` file to one replication bucket. In order to ensure that no secrets are stored in plain-text in your repository, this configuration file leverages Litestream's support for environment variables. The default configuration file looks like this if you only have one SQLite database:
+The gem streamlines the configuration process by providing a default configuration file for you. This configuration file will backup all SQLite databases defined in your `config/database.yml` file to one replication bucket. In order to ensure that no secrets are stored in plain-text in your repository, this configuration file leverages Litestream's support for environment variables. Inspect which environment variables are available by running the `bin/rails litestream:env` command.
+
+The default configuration file looks like this if you only have one SQLite database:
 
 ```yaml
 dbs:
   - path: storage/production.sqlite3
     replicas:
       - type: s3
-        bucket: $LITESTREAM_REPLICA_BUCKET
         path: storage/production.sqlite3
+        bucket: $LITESTREAM_REPLICA_BUCKET
         access-key-id: $LITESTREAM_ACCESS_KEY_ID
         secret-access-key: $LITESTREAM_SECRET_ACCESS_KEY
 ```
 
 This is the default for Amazon S3. The full range of possible replica types (e.g. other S3-compatible object storage servers) are covered in Litestream's [replica guides](https://litestream.io/guides/#replica-guides).
 
-The gem also provides a default initializer file at `config/initializers/litestream.rb` that allows you to configure these three environment variables referenced in the configuration file in Ruby. By providing a Ruby interface to these environment variables, you can use any method of storing secrets that you prefer. For example, the default generated file uses Rails' encrypted credentials to store your secrets:
+The gem also provides a default initializer file at `config/initializers/litestream.rb` that allows you to configure various variables referenced in the configuration file in Ruby. By providing a Ruby interface to these environment variables, you can use your preferred method of storing secrets. For example, the default generated file uses Rails' encrypted credentials to store your secrets.
 
 ```ruby
+# config/initializers/litestream.rb
 Rails.application.configure do
   litestream_credentials = Rails.application.credentials.litestream
 
@@ -107,7 +110,21 @@ Rails.application.configure do
 end
 ```
 
-However, if you need manual control over the Litestream configuration, you can manually edit the `config/litestream.yml` file. The full range of possible configurations are covered in Litestream's [configuration reference](https://litestream.io/reference/config/).  NB: If you configure a longer `sync-interval`, you may need to adjust `replication_sleep` when calling `Litestream.verify!`.
+Outside of configuring Litestream's replication, you may also configure various other aspects of `litestream-ruby` itself. 
+
+```ruby
+# config/initializers/litestream.rb
+Rails.application.configure do
+  # ...
+
+  # Base controller used for Litestream dashboard
+  config.litestream.base_controller_class = "MyApplicationController"
+  # Set the location of the Litestream config
+  config.litestream.config_path = "config/litestream.yml"
+end
+```
+
+However, if you need manual control over the Litestream configuration, you can edit the `config/litestream.yml` file. The full range of possible configurations are covered in Litestream's [configuration reference](https://litestream.io/reference/config/).  
 
 ### Replication
 
@@ -232,6 +249,7 @@ You can verify the integrity of your backed-up databases using the gem's provide
 
 ```ruby
 Litestream.verify! "storage/production.sqlite3"
+Litestream.verify!(replication_sleep: 10) "storage/production.sqlite3"
 ```
 
 In order to verify that the backup for that database is both restorable and fresh, the method will add a new row to that database under the `_litestream_verification` table, which it will create if needed. It will then wait `replication_sleep` seconds (defaults to 10) to give the Litestream utility time to replicate that change to whatever storage providers you have configured. After that, it will download the latest backup from that storage provider and ensure that this verification row is present in the backup. If the verification row is _not_ present, the method will raise a `Litestream::VerificationFailure` exception. This check ensures that the restored database file:
@@ -242,6 +260,9 @@ In order to verify that the backup for that database is both restorable and fres
 
 After restoring the backup, the `Litestream.verify!` method will delete the restored database file. If you need the restored database file, use the `litestream:restore` rake task or `Litestream::Commands.restore` method instead.
 
+> [!NOTE]
+> If you configure Litestream's [`sync-interval`](https://litestream.io/reference/config/#replica-settings) to be longer than the default `replication_sleep` value of 10 seconds, you will need to adjust `replication_sleep` to a value larger than `sync-interval`; otherwise, `Litestream.verify!` may appear to fail where it actually simply didn't wait long enough for replication. 
+
 ### Dashboard
 
 The gem provides a web dashboard for monitoring the status of your Litestream replication. To mount the dashboard in your Rails application, add the following to your `config/routes.rb` file:
@@ -506,7 +527,7 @@ time=YYYY-MM-DDTHH:MM:SS level=INFO msg="replicating to" name=s3 type=s3 sync-in
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+To install this gem onto your local machine, run `bundle exec rake install`. To download the Litestream binaries run `bundle exec rake download`.
 
 For maintainers, to release a new version, run `bin/release $VERSION`, which will create a git tag for the version, push git commits and tags, and push all of the platform-specific `.gem` files to [rubygems.org](https://rubygems.org).
 

data/app/controllers/litestream/restorations_controller.rb

@@ -9,7 +9,7 @@ module Litestream
       now = Time.now.utc.strftime("%Y%m%d%H%M%S")
       backup = File.join(dir, "#{base}-#{now}#{ext}")
 
-      Litestream::Commands.restore(database, async: false, **{"-o" => backup})
+      Litestream::Commands.restore(database, **{"-o" => backup})
 
       redirect_to root_path, notice: "Restored to <code>#{backup}</code>."
     end

data/lib/litestream/commands.rb

@@ -1,5 +1,4 @@
 require_relative "upstream"
-require "logfmt"
 
 module Litestream
   module Commands
@@ -21,6 +20,24 @@ module Litestream
     # raised when a litestream command fails
     CommandFailedException = Class.new(StandardError)
 
+    module Output
+      class << self
+        def format(data)
+          return "" if data.nil? || data.empty?
+
+          headers = data.first.keys.map(&:to_s)
+          widths = headers.map.with_index { |h, i|
+            [h.length, data.map { |r| r[data.first.keys[i]].to_s.length }.max].max
+          }
+
+          format_str = widths.map { |w| "%-#{w}s" }.join("  ")
+          ([headers] + data.map(&:values)).map { |row|
+            sprintf(format_str, *row.map(&:to_s))
+          }.join("\n")
+        end
+      end
+    end
+
     class << self
       def platform
         [:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
@@ -77,44 +94,49 @@ module Litestream
         exe_file
       end
 
+      # Replicate can be run either as a fork or in the same process, depending on the context.
+      # Puma will start replication as a forked process, while running replication from a rake
+      # tasks won't.
       def replicate(async: false, **argv)
-        execute("replicate", argv, async: async, tabled_output: false)
+        cmd = prepare("replicate", argv)
+        run_replicate(cmd, async: async)
+      rescue
+        raise CommandFailedException, "Failed to execute `#{cmd.join(" ")}`"
       end
 
-      def restore(database, async: false, **argv)
+      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?
-        argv.stringify_keys!
 
-        execute("restore", argv, database, async: async, tabled_output: false)
+        execute("restore", argv, database, tabled_output: false)
       end
 
-      def databases(async: false, **argv)
-        execute("databases", argv, async: async, tabled_output: true)
+      def databases(**argv)
+        execute("databases", argv)
       end
 
-      def generations(database, async: false, **argv)
+      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?
 
-        execute("generations", argv, database, async: async, tabled_output: true)
+        execute("generations", argv, database)
       end
 
-      def snapshots(database, async: false, **argv)
+      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, async: async, tabled_output: true)
+        execute("snapshots", argv, database)
       end
 
-      def wal(database, async: false, **argv)
+      def wal(database, **argv)
         raise DatabaseRequiredException, "database argument is required for wal command, e.g. litestream:wal -- --database=path/to/database.sqlite" if database.nil?
 
-        execute("wal", argv, database, async: async, tabled_output: true)
+        execute("wal", argv, database)
       end
 
       private
 
-      def execute(command, argv = {}, database = nil, async: false, tabled_output: false)
+      def execute(command, argv = {}, database = nil, tabled_output: true)
         cmd = prepare(command, argv, database)
-        results = run(cmd, async: async, tabled_output: tabled_output)
+        results = run(cmd, tabled_output: tabled_output)
 
         if Array === results && results.one? && results[0]["level"] == "ERROR"
           raise CommandFailedException, "Failed to execute `#{cmd.join(" ")}`; Reason: #{results[0]["error"]}"
@@ -139,21 +161,24 @@ module Litestream
         cmd
       end
 
-      def run(cmd, async: false, tabled_output: false)
+      def run(cmd, tabled_output:)
+        stdout = `#{cmd.join(" ")}`.chomp
+        return stdout unless tabled_output
+
+        keys, *rows = stdout.split("\n").map { _1.split(/\s+/) }
+        rows.map { keys.zip(_1).to_h }
+      end
+
+      def run_replicate(cmd, async:)
         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
-          stdout = `#{cmd.join(" ")}`.chomp
-          tabled_output ? text_table_to_hashes(stdout) : stdout.split("\n").map { Logfmt.parse(_1) }
+          # When running in-process, we capture output continuously and write to stdout.
+          IO.popen(cmd, err: [:child, :out]) do |io|
+            io.each_line { |line| puts line }
+          end
         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/generators/litestream/templates/initializer.rb

@@ -5,29 +5,41 @@
 # or some other mechanism where the values are only available at runtime.
 
 Rails.application.configure do
-  # An example of using Rails encrypted credentials to configure Litestream.
+  # Configure Litestream through environment variables. Use Rails encrypted credentials for secrets.
   # litestream_credentials = Rails.application.credentials.litestream
 
-  # Replica-specific bucket location.
-  # This will be your bucket's URL without the `https://` prefix.
+  # Replica-specific bucket location. This will be your bucket's URL without the `https://` prefix.
   # For example, if you used DigitalOcean Spaces, your bucket URL could look like:
+  #
   #   https://myapp.fra1.digitaloceanspaces.com
+  #
   # And so you should set your `replica_bucket` to:
+  #
   #   myapp.fra1.digitaloceanspaces.com
-  # Litestream supports Azure Blog Storage, Backblaze B2, DigitalOcean Spaces,
-  # Scaleway Object Storage, Google Cloud Storage, Linode Object Storage, and
-  # any SFTP server.
-  # In this example, we are using Rails encrypted credentials to store the URL to
-  # our storage provider bucket.
+  #
   # config.litestream.replica_bucket = litestream_credentials&.replica_bucket
-
-  # Replica-specific authentication key.
-  # Litestream needs authentication credentials to access your storage provider bucket.
-  # In this example, we are using Rails encrypted credentials to store the access key ID.
+  #
+  # Replica-specific authentication key. Litestream needs authentication credentials to access your storage provider bucket.
   # config.litestream.replica_key_id = litestream_credentials&.replica_key_id
-
-  # Replica-specific secret key.
-  # Litestream needs authentication credentials to access your storage provider bucket.
-  # In this example, we are using Rails encrypted credentials to store the secret access key.
+  #
+  # Replica-specific secret key. Litestream needs authentication credentials to access your storage provider bucket.
   # config.litestream.replica_access_key = litestream_credentials&.replica_access_key
+  #
+  # Replica-specific region. Set the bucket’s region. Only used for AWS S3 & Backblaze B2.
+  # config.litestream.replica_region = "us-east-1"
+  #
+  # Replica-specific endpoint. Set the endpoint URL of the S3-compatible service. Only required for non-AWS services.
+  # config.litestream.replica_endpoint = "endpoint.your-objectstorage.com"
+
+  # Configure the default Litestream config path
+  # config.config_path = Rails.root.join("config", "litestream.yml")
+
+  # Configure the Litestream dashboard
+  #
+  # Set the default base controller class
+  # config.litestream.base_controller_class = "MyApplicationController"
+  #
+  # Set authentication credentials for Litestream dashboard
+  # config.litestream.username = litestream_credentials&.username
+  # config.litestream.password = litestream_credentials&.password
 end

data/lib/litestream/version.rb

@@ -1,3 +1,3 @@
 module Litestream
-  VERSION = "0.13.0"
+  VERSION = "0.14.0"
 end

data/lib/litestream.rb

@@ -33,8 +33,7 @@ module Litestream
     end
   end
 
-  mattr_writer :username, :password, :queue, :replica_bucket, :replica_region, :replica_endpoint, :replica_key_id, :replica_access_key, :systemctl_command,
-    :config_path
+  mattr_writer :username, :password, :queue, :replica_bucket, :replica_region, :replica_endpoint, :replica_key_id, :replica_access_key, :systemctl_command, :config_path
   mattr_accessor :base_controller_class, default: "::ApplicationController"
 
   class << self

data/lib/tasks/litestream_tasks.rake

@@ -12,83 +12,61 @@ namespace :litestream do
 
   desc 'Monitor and continuously replicate SQLite databases defined in your config file, for example `rake litestream:replicate -- -exec "foreman start"`'
   task replicate: :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
-    options.symbolize_keys!
+    options = parse_argv_options
 
-    Litestream::Commands.replicate(async: true, **options)
+    Litestream::Commands.replicate(**options)
   end
 
   desc "Restore a SQLite database from a Litestream replica, for example `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
-    database = options.delete("--database") || options.delete("-database")
-    options.symbolize_keys!
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
 
-    Litestream::Commands.restore(database, async: true, **options)
+    puts Litestream::Commands.restore(database, **options)
   end
 
   desc "List all databases and associated replicas in the config file, for example `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
-    options.symbolize_keys!
+    options = parse_argv_options
 
-    Litestream::Commands.databases(async: true, **options)
+    puts Litestream::Commands::Output.format(Litestream::Commands.databases(**options))
   end
 
   desc "List all generations for a database or replica, for example `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
-    database = options.delete("--database") || options.delete("-database")
-    options.symbolize_keys!
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
 
-    Litestream::Commands.generations(database, async: true, **options)
+    puts Litestream::Commands::Output.format(Litestream::Commands.generations(database, **options))
   end
 
   desc "List all snapshots for a database or replica, for example `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
-    database = options.delete("--database") || options.delete("-database")
-    options.symbolize_keys!
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
 
-    Litestream::Commands.snapshots(database, async: true, **options)
+    puts Litestream::Commands::Output.format(Litestream::Commands.snapshots(database, **options))
   end
 
   desc "List all wal files for a database or replica, for example `rake litestream:wal -- -database=storage/production.sqlite3`"
   task wal: :environment do
+    options = parse_argv_options
+    database = options.delete(:"--database") || options.delete(:"-database")
+
+    puts Litestream::Commands::Output.format(
+      Litestream::Commands.wal(database, **options)
+    )
+  end
+
+  private
+
+  def parse_argv_options
     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
-    database = options.delete("--database") || options.delete("-database")
     options.symbolize_keys!
-
-    Litestream::Commands.wal(database, async: true, **options)
   end
 end

metadata

@@ -1,28 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: litestream
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: x86_64-darwin
 authors:
 - Stephen Margheim
 bindir: exe
 cert_chain: []
-date: 2025-06-03 00:00:00.000000000 Z
+date: 2025-06-13 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: logfmt
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.0.10
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.0.10
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -66,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: activejob
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -80,7 +66,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7.0'
 - !ruby/object:Gem::Dependency
-  name: activejob
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -107,20 +93,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-- !ruby/object:Gem::Dependency
-  name: rubyzip
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -136,7 +108,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="