litestream-ruby Litestream 是一个用于 SQLite 的独立流式复制工具。此 gem 提供了 Litestream 的 Ruby 接口。安装…
litestream-ruby Litestream 是一个用于 SQLite 的独立流式复制工具。此 gem 提供了 Litestream 的 Ruby 接口。安装…
Litestream is a standalone streaming replication tool for SQLite. This gem provides a Ruby interface to Litestream.
Install the gem and add to the application's Gemfile by executing:
bundle add litestreamIf bundler is not being used to manage dependencies, install the gem by executing:
gem install litestreamAfter installing the gem, run the installer:
rails generate litestream:installThe 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:
litestreamIf 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:
LITESTREAM_INSTALL_DIR=/usr/local/binThis also works with relative paths. If you've installed into your app's directory at ./.bin/litestream:
LITESTREAM_INSTALL_DIR=.binYou 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:
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_KEYThis 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.
# 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
endOutside of configuring Litestream's replication, you may also configure various other aspects of litestream-ruby itself.
# 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"
endHowever, 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.
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:
# 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:
# Procfile
rails: bundle exec rails server --port $PORT
litestream: bin/rails litestream:replicateAlternatively, 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:
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:
-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.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 runningrails serverorrails consoleinstance. 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.
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:
# DANGEROUS OPERATION, consider renaming database files instead
bin/rails db:drop DISABLE_DATABASE_ENVIRONMENT_CHECK=1Run restore command:
bin/rails litestream:restore -- --database=storage/production.sqlite3
# or
bundle exec rake litestream:restore -- --database=storage/production.sqlite3Restart 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:
bin/rails litestream:restore -- --database=storage/production.sqlite3 --if-db-not-existsYou 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:
…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:
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:
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-intervalto be longer than the defaultreplication_sleepvalue of 10 seconds, you will need to adjustreplication_sleepto a value larger thansync-interval; otherwise,Litestream.verify!may appear to fail where it actually simply didn't wait long enough for replication.
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:
authenticate :user, -> (user) { user.admin? } do
mount Litestream::Engine, at: "/litestream"
end[!NOTE] Be sure to secure the dashboard in production.
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,或尚未同步最近议题。