litestream 0.12.0-x86_64-linux → 0.14.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f2c8d8359a3818741a4a97cc4840cb406cf2d116fc95fe23aadec7b6292b1a0
-  data.tar.gz: 5ee9cd65c126f969a556628b07caf024b7938b48da911f3c2d2076c817c81a2c
+  metadata.gz: f5472149be2f48a05e36c2e2f1c3feb212355100f4e3085f90ed821559d49200
+  data.tar.gz: 7d745ffdd094a4148b7660f7ec32c531c125279ecb8d78ceef72bdea149f5394
 SHA512:
-  metadata.gz: '08acb5e98da7842a3ee74e577aa6bab79eb87a72f15e794774e7e6526793a9eb5e3b917f0a6f8d1ce511f409be8123deac69cab0dd0e37f44c280ac202b6e38f'
-  data.tar.gz: 76f9b61337e208e41dfc29e916d71a4610e0f55f548370541f753a6ca8e8af6b90817dae3902a97cd66440e0c7be55841c21be47a5a304695c014bf848871620
+  metadata.gz: a5ef0cfce7f7fd68d235f873882f8651c9141bb5fabf7b9a4d2b8f5144de4f0658e741f2a3c0e7f09ef381b4016f897673c5b2d80064dad58c6d4778647f801c
+  data.tar.gz: a959c042fd3c62118cad6976ce554c014ecf6259ca62e1949c398f4cd5697d6ebe0aaa4121f7fd108bcfbdfee8facb9a0cd6391f4024e982116f9a5ed52adaf2

data/README.md

@@ -54,6 +54,7 @@ Supported platforms are:
 
 - arm64-darwin (macos-arm64)
 - x86_64-darwin (macos-x64)
+- aarch64-linux (linux-aarch64)
 - arm64-linux (linux-arm64)
 - x86_64-linux (linux-x64)
 
@@ -79,22 +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
 ```
 
-The gem also provides a default initializer file at `config/initializers/litestream.rb` that allows you to configure these four 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:
+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 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
 
@@ -104,20 +110,33 @@ 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/).
+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
 
 In order to stream changes to your configured replicas, you need to start the Litestream replication process.
 
-The simplest way to run the Litestream replication process is use the Puma plugin provided by the gem. This allows you to run the Litestream replication process together with Puma and have Puma monitor and manage it. You just need to add
+The simplest way to run the Litestream replication process is use the Puma plugin provided by the gem. This allows you to run the Litestream replication process together with Puma and have Puma monitor and manage it. You just need to add the following to your `puma.rb` configuration:
 
 ```ruby
-plugin :litestream
+# Run litestream only in production.
+plugin :litestream if ENV.fetch("RAILS_ENV", "production") == "production"
 ```
 
-to your `puma.rb` configuration.
-
 If you would prefer to run the Litestream replication process separately from Puma, you can use the provided `litestream:replicate` rake task. This rake task will automatically load the configuration file and set the environment variables before starting the Litestream process.
 
 The simplest way to spin up a Litestream process separately from your Rails application is to use a `Procfile`:
@@ -155,20 +174,32 @@ The Litestream `replicate` command supports the following options, which can be
 
 ### Restoration
 
-You can restore any replicated database at any point using the gem's provided `litestream:restore` rake task. This rake task requires that you specify which specific database you want to restore. As with the `litestream:replicate` task, you pass arguments to the rake task via argument forwarding. For example, to restore the production database, you would run:
+You can restore any replicated database at any point using the gem's provided `litestream:restore` rake task. This rake task requires that you specify which specific database you want to restore. As with the `litestream:replicate` task, you pass arguments to the rake task via argument forwarding. For example, to restore the production database, you would do the following:
 
-```shell
-bin/rails litestream:restore -- --database=storage/production.sqlite3
-# or
-bundle exec rake litestream:restore -- --database=storage/production.sqlite3
-```
+> [!NOTE]  
+> During the restoration process, you need to prevent any interaction with ActiveRecord/SQLite, such as from a running `rails server` or `rails console` instance. If there is any interaction, Rails might regenerate the production database and prevent restoration via litestream. If this happens, you might get a "cannot restore, output path already exists" error.
+
+1. Rename the production (`production.sqlite3`, `production.sqlite3-shm`, and `production.sqlite3-wal`) databases (**recommended**) or alternatively delete. To delete the production databases locally, you can run the following at your own risk:
+   ```shell
+   # DANGEROUS OPERATION, consider renaming database files instead
+   bin/rails db:drop DISABLE_DATABASE_ENVIRONMENT_CHECK=1
+   ```
+
+2. Run restore command:
+   ```shell
+   bin/rails litestream:restore -- --database=storage/production.sqlite3
+   # or
+   bundle exec rake litestream:restore -- --database=storage/production.sqlite3
+   ```
+
+3. Restart your Rails application or Docker container if applicable.
 
 You can restore any of the databases specified in your `config/litestream.yml` file. The `--database` argument should be the path to the database file you want to restore and must match the value for the `path` key of one of your configured databases. The `litestream:restore` rake task will automatically load the configuration file and set the environment variables before calling the Litestream executable.
 
 If you need to pass arguments through the rake task to the underlying `litestream` command, that can be done with additional forwarded arguments:
 
 ```shell
-bin/rails litestream:replicate -- --database=storage/production.sqlite3 --if-db-not-exists
+bin/rails litestream:restore -- --database=storage/production.sqlite3 --if-db-not-exists
 ```
 
 You can forward arguments in whatever order you like, you simply need to ensure that the `--database` argument is present. You can also use either a single-dash `-database` or double-dash `--database` argument format. The Litestream `restore` command supports the following options, which can be passed through the rake task:
@@ -218,9 +249,10 @@ 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 10 seconds 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
+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:
 
 1. exists,
 2. can be opened by SQLite, and
@@ -228,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:
@@ -256,8 +291,8 @@ Second, you can configure the access credentials via the Rails configuration obj
 
 ```ruby
 # Set authentication credentials for Litestream
-config.litestream.username = Rails.application.credentials.litestream.username
-config.litestream.password = Rails.application.credentials.litestream.password
+config.litestream.username = Rails.application.credentials.dig(:litestream, :username)
+config.litestream.password = Rails.application.credentials.dig(:litestream, :password)
 ```
 
 Either way, if you have set a username and password, Litestream will use basic HTTP authentication.
@@ -269,7 +304,7 @@ If you use Devise for authentication in your app, you can also restrict access t
 
 ```ruby
 authenticate :user, -> (user) { user.admin? } do
-  mount LitestreamRails::Engine, at: "/litestream"
+  mount Litestream::Engine, at: "/litestream"
 end
 ```
 
@@ -294,7 +329,7 @@ config.middleware.use ActionDispatch::Flash
 
 ### Overwriting the views
 
-You can find the views in [`app/views`](https://github.com/fractaledmind/litestream/tree/main/app/views).
+You can find the views in [`app/views`](https://github.com/fractaledmind/litestream-ruby/tree/main/app/views).
 
 ```bash
 app/views/
@@ -362,7 +397,7 @@ You can also list the generations of a specific database:
 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.
+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
@@ -434,13 +469,6 @@ 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
@@ -461,7 +489,13 @@ litestream wal [arguments] DB_PATH|REPLICA_URL
 
 ### Using in development
 
-By default, installing the gem does not update your `Procfile.dev` file, and so Litestream will not be started in development. If you would like to test that your configuration is properly setup, you can manually add the `litestream:replicate` rake task to your `Procfile.dev` file. Just copy the `litestream` definition from the production `Procfile`. Then, in order to have a replication bucket for Litestream to point to, you can use a Docker instance of [MinIO](https://min.io/). MinIO is an S3-compatible object storage server that can be run locally. You can run a MinIO server with the following command:
+By default, if you install the gem and configure via `puma.rb` or `Procfile`, Litestream will not start in development.
+
+If you setup via `puma.rb`, then remove the conditional statement.
+
+If you setup via `Procfile`, you will need to update your `Procfile.dev` file. If you would like to test that your configuration is properly setup, you can manually add the `litestream:replicate` rake task to your `Procfile.dev` file. Just copy the `litestream` definition from the production `Procfile`.
+
+In order to have a replication bucket for Litestream to point to, you can use a Docker instance of [MinIO](https://min.io/). MinIO is an S3-compatible object storage server that can be run locally. You can run a MinIO server with the following command:
 
 ```sh
 docker run -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address ":9001"
@@ -493,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/application_controller.rb

@@ -1,7 +1,6 @@
 module Litestream
-  class ApplicationController < ActionController::Base
+  class ApplicationController < Litestream.base_controller_class.constantize
     protect_from_forgery with: :exception
-    around_action :force_english_locale!
 
     if Litestream.password
       http_basic_authenticate_with(
@@ -9,11 +8,5 @@ module Litestream
         password: Litestream.password
       )
     end
-
-    private
-
-    def force_english_locale!(&action)
-      I18n.with_locale(:en, &action)
-    end
   end
 end

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/app/views/layouts/litestream/_style.html

@@ -801,4 +801,42 @@
   .hover\:underline:hover {
     text-decoration-line: underline;
   }
+  @media (prefers-color-scheme: dark) {
+    .dark\:border-gray-800 {
+      --tw-border-opacity: 1;
+      border-color: rgb(31 41 55 / var(--tw-border-opacity));
+    }
+    .dark\:bg-gray-900 {
+      --tw-bg-opacity: 1;
+      background-color: rgb(17 24 39 / var(--tw-bg-opacity));
+    }
+    .dark\:bg-green-900 {
+      --tw-bg-opacity: 1;
+      background-color: rgb(20 83 45 / var(--tw-bg-opacity));
+    }
+    .dark\:bg-red-900 {
+      --tw-bg-opacity: 1;
+      background-color: rgb(127 29 29 / var(--tw-bg-opacity));
+    }
+    .dark\:text-gray-100 {
+      --tw-text-opacity: 1;
+      color: rgb(243 244 246 / var(--tw-text-opacity));
+    }
+    .dark\:text-white {
+      --tw-text-opacity: 1;
+      color: rgb(255 255 255 / var(--tw-text-opacity));
+    }
+    .dark\:even\:bg-gray-800:nth-child(even) {
+      --tw-bg-opacity: 1;
+      background-color: rgb(31 41 55 / var(--tw-bg-opacity));
+    }
+    .dark\:hover\:bg-gray-900:hover {
+      --tw-bg-opacity: 1;
+      background-color: rgb(17 24 39 / var(--tw-bg-opacity));
+    }
+    .dark\:hover\:bg-gray-800:hover {
+      --tw-bg-opacity: 1;
+      background-color: rgb(31 41 55 / var(--tw-bg-opacity));
+    }
+  }
 </style>

data/app/views/layouts/litestream/application.html.erb

@@ -7,22 +7,22 @@
 
     <%= render "layouts/litestream/style" %>
   </head>
-  <body class="h-full flex flex-col">
+  <body class="h-full flex flex-col dark:bg-gray-900 dark:text-white">
     <main class="container mx-auto max-w-4xl mt-4 px-2 grow">
       <%= content_for?(:content) ? yield(:content) : yield %>
     </main>
 
-    <footer class="container mx-auto mt-24 flex items-center justify-between border-t px-2 py-4 text-base">
+    <footer class="container mx-auto mt-24 flex items-center justify-between border-t dark:border-gray-800 px-2 py-4 text-base">
       <p>
         <code><strong>Litestream</strong></code>&nbsp;&nbsp;|&nbsp;
-        Made by <a href="https://twitter.com/fractaledmind" class="text-blue-500 hover:underline decoration-blue-500">@fractaledmind</a> and <a href="https://github.com/fractaledmind/litestream/graphs/contributors" class="text-blue-500 hover:underline decoration-blue-500">friends</a>! Want to help? It's <a href="https://github.com/fractaledmind/litestream" class="text-blue-500 hover:underline decoration-blue-500">open source</a>!
+        Made by <a href="https://twitter.com/fractaledmind" class="text-blue-500 hover:underline decoration-blue-500">@fractaledmind</a> and <a href="https://github.com/fractaledmind/litestream-ruby/graphs/contributors" class="text-blue-500 hover:underline decoration-blue-500">friends</a>! Want to help? It's <a href="https://github.com/fractaledmind/litestream-ruby" class="text-blue-500 hover:underline decoration-blue-500">open source</a>!
       </p>
     </footer>
 
     <div class="fixed top-0 left-0 right-0 text-center py-2">
       <% if notice.present? %>
         <p id="notice"
-           class="py-2 px-3 bg-green-50 text-green-500 font-medium rounded-lg inline-block"
+           class="py-2 px-3 bg-green-50 dark:bg-green-900 text-green-500 font-medium rounded-lg inline-block"
            data-controller="fade">
           <%= notice.html_safe %>
         </p>
@@ -30,7 +30,7 @@
 
       <% if alert.present? %>
         <p id="alert"
-           class="py-2 px-3 bg-red-50 text-red-500 font-medium rounded-lg inline-block"
+           class="py-2 px-3 bg-red-50 dark:bg-red-900 text-red-500 font-medium rounded-lg inline-block"
            data-controller="fade">
           <%= alert.html_safe %>
         </p>

data/app/views/litestream/processes/show.html.erb

@@ -40,7 +40,7 @@
 <br>
 
 <section id="databases" class="">
-  <div class="mb-3 flex items-center justify-between border-b">
+  <div class="mb-3 flex items-center justify-between border-b dark:border-gray-800">
     <h2 class="text-2xl font-bold">Databases</h2>
     <p class="text-right">Total: <strong><%= @databases.size %></strong></p>
   </div>
@@ -59,7 +59,7 @@
         <section id="generations" class="ml-6">
           <% database['generations'].each do |generation| %>
             <details id="<%= generation['generation'] %>" open="open">
-              <summary class="cursor-pointer rounded p-2 hover:bg-gray-50">
+              <summary class="cursor-pointer rounded p-2 hover:bg-gray-50 dark:hover:bg-gray-800">
                 <code><%= generation['generation'] %></code>
                 (<em><%= generation['lag'] %> lag</em>)
               </summary>
@@ -85,24 +85,24 @@
                     <table class="min-w-full divide-y divide-gray-300">
                       <thead>
                         <tr>
-                          <th scope="col" class="whitespace-nowrap px-2 py-2 text-left text-sm font-semibold text-gray-900">Created at</th>
-                          <th scope="col" class="whitespace-nowrap px-2 py-2 text-right text-sm font-semibold text-gray-900">Index</th>
-                          <th scope="col" class="whitespace-nowrap px-2 py-2 text-right text-sm font-semibold text-gray-900">Size</th>
+                          <th scope="col" class="whitespace-nowrap px-2 py-2 text-left text-sm font-semibold text-gray-900 dark:text-gray-100">Created at</th>
+                          <th scope="col" class="whitespace-nowrap px-2 py-2 text-right text-sm font-semibold text-gray-900 dark:text-gray-100">Index</th>
+                          <th scope="col" class="whitespace-nowrap px-2 py-2 text-right text-sm font-semibold text-gray-900 dark:text-gray-100">Size</th>
                         </tr>
                       </thead>
 
-                      <tbody class="bg-white">
+                      <tbody class="bg-white dark:bg-gray-900">
                         <% generation['snapshots'].each do |snapshot| %>
-                          <tr class="align-top even:bg-gray-50">
-                            <td scope="col" class="whitespace-nowrap px-2 py-2 text-sm text-gray-900">
+                          <tr class="align-top even:bg-gray-50 dark:even:bg-gray-800">
+                            <td scope="col" class="whitespace-nowrap px-2 py-2 text-sm text-gray-900 dark:text-gray-100">
                               <abbr title="<%= snapshot['created'] %>" class="underline decoration-dashed decoration-gray-500 cursor-help">
                                 <time datetime="<%= snapshot['created'] %>"><%= DateTime.parse(snapshot['created']).to_formatted_s(:db) %></time>
                               </abbr>
                             </td>
-                            <td scope="col" class="whitespace-nowrap px-2 py-2 text-sm text-gray-900 text-right">
+                            <td scope="col" class="whitespace-nowrap px-2 py-2 text-sm text-gray-900 dark:text-gray-100 text-right">
                               <%= snapshot['index'] %>
                             </td>
-                            <td scope="col" class="whitespace-nowrap px-2 py-2 text-sm text-gray-900 text-right">
+                            <td scope="col" class="whitespace-nowrap px-2 py-2 text-sm text-gray-900 dark:text-gray-100 text-right">
                               <%= number_to_human_size snapshot['size'] %>
                             </td>
                           </tr>

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"]}"
@@ -125,11 +147,13 @@ module Litestream
 
       def prepare(command, argv = {}, database = nil)
         ENV["LITESTREAM_REPLICA_BUCKET"] ||= Litestream.replica_bucket
+        ENV["LITESTREAM_REPLICA_REGION"] ||= Litestream.replica_region
+        ENV["LITESTREAM_REPLICA_ENDPOINT"] ||= Litestream.replica_endpoint
         ENV["LITESTREAM_ACCESS_KEY_ID"] ||= Litestream.replica_key_id
         ENV["LITESTREAM_SECRET_ACCESS_KEY"] ||= Litestream.replica_access_key
 
         args = {
-          "--config" => Rails.root.join("config", "litestream.yml").to_s
+          "--config" => Litestream.config_path.to_s
         }.merge(argv.stringify_keys).to_a.flatten.compact
         cmd = [executable, command, *args, database].compact
         puts cmd.inspect if ENV["DEBUG"]
@@ -137,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

@@ -2,32 +2,44 @@
 # All configuration options will be available as environment variables, e.g.
 # config.replica_bucket becomes LITESTREAM_REPLICA_BUCKET
 # This allows you to configure Litestream using Rails encrypted credentials,
-# or some other mechanism where the values are only avaialble at runtime.
+# 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/upstream.rb

@@ -4,6 +4,7 @@ module Litestream
 
     # rubygems platform name => upstream release filename
     NATIVE_PLATFORMS = {
+      "aarch64-linux" => "litestream-#{VERSION}-linux-arm64.tar.gz",
       "arm64-darwin" => "litestream-#{VERSION}-darwin-arm64.zip",
       "arm64-linux" => "litestream-#{VERSION}-linux-arm64.tar.gz",
       "x86_64-darwin" => "litestream-#{VERSION}-darwin-amd64.zip",

data/lib/litestream/version.rb

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

data/lib/litestream.rb

@@ -33,16 +33,17 @@ module Litestream
     end
   end
 
-  mattr_writer :username, :password, :queue, :replica_bucket, :replica_key_id, :replica_access_key, :systemctl_command
+  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
-    def verify!(database_path)
+    def verify!(database_path, replication_sleep: 10)
       database = SQLite3::Database.new(database_path)
       database.execute("CREATE TABLE IF NOT EXISTS _litestream_verification (id INTEGER PRIMARY KEY, uuid BLOB)")
       sentinel = SecureRandom.uuid
       database.execute("INSERT INTO _litestream_verification (uuid) VALUES (?)", [sentinel])
       # give the Litestream replication process time to replicate the sentinel value
-      sleep 10
+      sleep replication_sleep
 
       backup_path = "tmp/#{Time.now.utc.strftime("%Y%m%d%H%M%S")}_#{sentinel}.sqlite3"
       Litestream::Commands.restore(database_path, **{"-o" => backup_path})
@@ -77,6 +78,14 @@ module Litestream
       @@replica_bucket || configuration.replica_bucket
     end
 
+    def replica_region
+      @@replica_region
+    end
+
+    def replica_endpoint
+      @@replica_endpoint
+    end
+
     def replica_key_id
       @@replica_key_id || configuration.replica_key_id
     end
@@ -89,55 +98,12 @@ module Litestream
       @@systemctl_command || "systemctl status litestream"
     end
 
+    def config_path
+      @@config_path || Rails.root.join("config", "litestream.yml")
+    end
+
     def replicate_process
-      info = {}
-      if !`which systemctl`.empty?
-        systemctl_status = `#{Litestream.systemctl_command}`.chomp
-        # ["● litestream.service - Litestream",
-        #  "     Loaded: loaded (/lib/systemd/system/litestream.service; enabled; vendor preset: enabled)",
-        #  "     Active: active (running) since Tue 2023-07-25 13:49:43 UTC; 8 months 24 days ago",
-        #  "   Main PID: 1179656 (litestream)",
-        #  "      Tasks: 9 (limit: 1115)",
-        #  "     Memory: 22.9M",
-        #  "        CPU: 10h 49.843s",
-        #  "     CGroup: /system.slice/litestream.service",
-        #  "             └─1179656 /usr/bin/litestream replicate",
-        #  "",
-        #  "Warning: some journal files were not opened due to insufficient permissions."]
-        systemctl_status.split("\n").each do |line|
-          line.strip!
-          if line.start_with?("Main PID:")
-            _key, value = line.split(":")
-            pid, _name = value.strip.split(" ")
-            info[:pid] = pid
-          elsif line.start_with?("Active:")
-            value, _ago = line.split(";")
-            status, timestamp = value.split(" since ")
-            info[:started] = DateTime.strptime(timestamp.strip, "%a %Y-%m-%d %H:%M:%S %Z")
-            status_match = status.match(%r{\((?<status>.*)\)})
-            info[:status] = status_match ? status_match[:status] : nil
-          end
-        end
-      else
-        litestream_replicate_ps = `ps -ax | grep litestream | grep replicate`.chomp
-        litestream_replicate_ps.split("\n").each do |line|
-          next unless line.include?("litestream replicate")
-          pid, * = line.split(" ")
-          info[:pid] = pid
-          state, _, lstart = `ps -o "state,lstart" #{pid}`.chomp.split("\n").last.partition(/\s+/)
-
-          info[:status] = case state[0]
-          when "I" then "idle"
-          when "R" then "running"
-          when "S" then "sleeping"
-          when "T" then "stopped"
-          when "U" then "uninterruptible"
-          when "Z" then "zombie"
-          end
-          info[:started] = DateTime.strptime(lstart.strip, "%a %b %d %H:%M:%S %Y")
-        end
-      end
-      info
+      systemctl_info || process_info || {}
     end
 
     def databases
@@ -157,6 +123,71 @@ module Litestream
         end
       end
     end
+
+    private
+
+    def systemctl_info
+      return if `which systemctl`.empty?
+
+      systemctl_output = `#{Litestream.systemctl_command}`
+      systemctl_exit_code = $?.exitstatus
+      return unless systemctl_exit_code.zero?
+
+      # ["● litestream.service - Litestream",
+      #  "     Loaded: loaded (/lib/systemd/system/litestream.service; enabled; vendor preset: enabled)",
+      #  "     Active: active (running) since Tue 2023-07-25 13:49:43 UTC; 8 months 24 days ago",
+      #  "   Main PID: 1179656 (litestream)",
+      #  "      Tasks: 9 (limit: 1115)",
+      #  "     Memory: 22.9M",
+      #  "        CPU: 10h 49.843s",
+      #  "     CGroup: /system.slice/litestream.service",
+      #  "             └─1179656 /usr/bin/litestream replicate",
+      #  "",
+      #  "Warning: some journal files were not opened due to insufficient permissions."]
+
+      info = {}
+      systemctl_output.chomp.split("\n").each do |line|
+        line.strip!
+        if line.start_with?("Main PID:")
+          _key, value = line.split(":")
+          pid, _name = value.strip.split(" ")
+          info[:pid] = pid
+        elsif line.start_with?("Active:")
+          value, _ago = line.split(";")
+          status, timestamp = value.split(" since ")
+          info[:started] = DateTime.strptime(timestamp.strip, "%a %Y-%m-%d %H:%M:%S %Z")
+          status_match = status.match(%r{\((?<status>.*)\)})
+          info[:status] = status_match ? status_match[:status] : nil
+        end
+      end
+      info
+    end
+
+    def process_info
+      litestream_replicate_ps = `ps -ax | grep litestream | grep replicate`
+      exit_code = $?.exitstatus
+      return unless exit_code.zero?
+
+      info = {}
+      litestream_replicate_ps.chomp.split("\n").each do |line|
+        next unless line.include?("litestream replicate")
+
+        pid, * = line.split(" ")
+        info[:pid] = pid
+        state, _, lstart = `ps -o "state,lstart" #{pid}`.chomp.split("\n").last.partition(/\s+/)
+
+        info[:status] = case state[0]
+        when "I" then "idle"
+        when "R" then "running"
+        when "S" then "sleeping"
+        when "T" then "stopped"
+        when "U" then "uninterruptible"
+        when "Z" then "zombie"
+        end
+        info[:started] = DateTime.strptime(lstart.strip, "%a %b %d %H:%M:%S %Y")
+      end
+      info
+    end
   end
 end
 

data/lib/tasks/litestream_tasks.rake

@@ -2,6 +2,8 @@ namespace :litestream do
   desc "Print the ENV variables needed for the Litestream config file"
   task env: :environment do
     puts "LITESTREAM_REPLICA_BUCKET=#{Litestream.replica_bucket}"
+    puts "LITESTREAM_REPLICA_REGION=#{Litestream.replica_region}"
+    puts "LITESTREAM_REPLICA_ENDPOINT=#{Litestream.replica_endpoint}"
     puts "LITESTREAM_ACCESS_KEY_ID=#{Litestream.replica_key_id}"
     puts "LITESTREAM_SECRET_ACCESS_KEY=#{Litestream.replica_access_key}"
 
@@ -10,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,29 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: litestream
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: x86_64-linux
 authors:
 - Stephen Margheim
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-22 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
@@ -67,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:
     - - ">="
@@ -81,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:
     - - ">="
@@ -108,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
@@ -137,7 +108,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -150,7 +121,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - stephen.margheim@gmail.com
 executables:
@@ -190,7 +160,6 @@ metadata:
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/fractaledmind/litestream-ruby
   changelog_uri: https://github.com/fractaledmind/litestream-ruby/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -205,8 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Integrate Litestream with the RubyGems infrastructure.
 test_files: []