百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
L

litestream-ruby

> 编程语言
开源

litestream-ruby Litestream 是一个用于 SQLite 的独立流式复制工具。此 gem 提供了 Litestream 的 Ruby 接口。安装…

276 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

litestream-ruby Litestream 是一个用于 SQLite 的独立流式复制工具。此 gem 提供了 Litestream 的 Ruby 接口。安装…

litestream-ruby

Litestream is a standalone streaming replication tool for SQLite. This gem provides a Ruby interface to Litestream.

Installation

Install the gem and add to the application's Gemfile by executing:

bash
bundle add litestream

If bundler is not being used to manage dependencies, install the gem by executing:

bash
gem install litestream

After installing the gem, run the installer:

bash
rails generate litestream:install

The installer will create a configuration file at config/litestream.yml and an initializer file for configuring the gem at config/initializers/litestream.rb.

This gem wraps the standalone executable version of the Litestream utility. These executables are platform specific, so there are actually separate underlying gems per platform, but the correct gem will automatically be picked for your platform. Litestream itself doesn't support Windows, so this gem doesn't either.

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)

Using a local installation of litestream

If you are not able to use the vendored standalone executables (for example, if you're on an unsupported platform), you can use a local installation of the litestream executable by setting an environment variable named LITESTREAM_INSTALL_DIR to the directory containing the executable.

For example, if you've installed litestream so that the executable is found at /usr/local/bin/litestream, then you should set your environment variable like so:

bash
LITESTREAM_INSTALL_DIR=/usr/local/bin

This also works with relative paths. If you've installed into your app's directory at ./.bin/litestream:

bash
LITESTREAM_INSTALL_DIR=.bin

Usage

Configuration

You configure the Litestream executable through the config/litestream.yml file, 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. 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
        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.

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

  config.litestream.replica_bucket = litestream_credentials&.replica_bucket
  config.litestream.replica_key_id = litestream_credentials&.replica_key_id
  config.litestream.replica_access_key = litestream_credentials&.replica_access_key
end

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.

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 following to your puma.rb configuration:

ruby
# Run litestream only in production.
plugin :litestream if ENV.fetch("RAILS_ENV", "production") == "production"

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:

yaml
# Procfile
rails: bundle exec rails server --port $PORT
litestream: bin/rails litestream:replicate

Alternatively, you could setup a systemd service to manage the Litestream replication process, but setting this up is outside the scope of this README.

If you need to pass arguments through the rake task to the underlying litestream command, that can be done with argument forwarding:

bash
bin/rails litestream:replicate -- -exec "foreman start"

This example utilizes the -exec option available on the replicate command which provides basic process management, since Litestream will exit when the child process exits. In this example, we only launch our collection of Rails application processes (like Rails and SolidQueue, for example) after the Litestream replication process is ready.

The Litestream replicate command supports the following options, which can be passed through the rake task:

bash
-config PATH
    Specifies the configuration file.
    Defaults to /etc/litestream.yml

-exec CMD
    Executes a subcommand. Litestream will exit when the child
    process exits. Useful for simple process management.

-no-expand-env
    Disables environment variable expansion in configuration file.

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 do the following:

[!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:

    bash
    # DANGEROUS OPERATION, consider renaming database files instead
    bin/rails db:drop DISABLE_DATABASE_ENVIRONMENT_CHECK=1
  2. Run restore command:

    bash
    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:

bash
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:

…

Verification

You can verify the integrity of your backed-up databases using the gem's provided Litestream.verify! method. The method takes the path to a database file that you have configured Litestream to backup; that is, it takes one of the path values under the dbs key in your litestream.yml configuration file. For example, to verify the production database, you would run:

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:

  1. exists,
  2. can be opened by SQLite, and
  3. has up-to-date data.

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

ruby
authenticate :user, -> (user) { user.admin? } do
  mount Litestream::Engine, at: "/litestream"
end

[!NOTE] Be sure to secure the dashboard in production.

Authentication

Litestream Rails does not restrict access out of the box. You must secure the dashboard yourself. However, it does provide basic HTTP authentication that can be used with basic authentication or Devise. All you need to do is setup a username and

Issues· 20 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言