litestream 0.4.0 → 0.5.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +87 -2
- data/exe/litestream +0 -1
- data/lib/litestream/commands.rb +33 -9
- data/lib/litestream/version.rb +1 -1
- data/lib/litestream.rb +0 -1
- data/lib/tasks/litestream_tasks.rake +13 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 8da245a396bc819cf0aa9bfae9a87f65a92047fd45a96bd8f8602eee6248adb6
|
4
|
+
data.tar.gz: 4bee567fab0ad7ab71d72c36091be4a32c4685ddfe1b69f6403c36ea927af437
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 5b1ba5a3de6be15243513f10f37657c940cbd59471ae008434c73aa0a09b62869b7e940388003a254431ab503fafdc891f7cffcc95afcfa61c07e1f657617225
|
7
|
+
data.tar.gz: 34410a43ee4ab617e160a76989d4721d7c6b1861aa15d623602a7088d1b561266e40f2243e7c0a1d880778031d15b9ce71384ae1cf4a245494f21d2ea93426fc
|
data/README.md
CHANGED
@@ -92,9 +92,94 @@ bin/rails litestream:replicate -- -exec "foreman start"
|
|
92
92
|
|
93
93
|
This example utilizes the `-exec` option available on [the `replicate` command](https://litestream.io/reference/replicate/) 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.
|
94
94
|
|
95
|
-
The
|
95
|
+
The Litestream `replicate` command supports the following options, which can be passed through the rake task:
|
96
|
+
```shell
|
97
|
+
-config PATH
|
98
|
+
Specifies the configuration file.
|
99
|
+
Defaults to /etc/litestream.yml
|
100
|
+
|
101
|
+
-exec CMD
|
102
|
+
Executes a subcommand. Litestream will exit when the child
|
103
|
+
process exits. Useful for simple process management.
|
104
|
+
|
105
|
+
-no-expand-env
|
106
|
+
Disables environment variable expansion in configuration file.
|
107
|
+
```
|
108
|
+
|
109
|
+
### Restoration
|
96
110
|
|
97
|
-
|
111
|
+
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:
|
112
|
+
|
113
|
+
```shell
|
114
|
+
bin/rails litestream:restore -- --database=storage/production.sqlite3
|
115
|
+
# or
|
116
|
+
bundle exec rake litestream:restore -- --database=storage/production.sqlite3
|
117
|
+
```
|
118
|
+
|
119
|
+
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.
|
120
|
+
|
121
|
+
If you need to pass arguments through the rake task to the underlying `litestream` command, that can be done with additional forwarded arguments:
|
122
|
+
|
123
|
+
```shell
|
124
|
+
bin/rails litestream:replicate -- --database=storage/production.sqlite3 --if-db-not-exists
|
125
|
+
```
|
126
|
+
|
127
|
+
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:
|
128
|
+
|
129
|
+
```shell
|
130
|
+
-o PATH
|
131
|
+
Output path of the restored database.
|
132
|
+
Defaults to original DB path.
|
133
|
+
|
134
|
+
-if-db-not-exists
|
135
|
+
Returns exit code of 0 if the database already exists.
|
136
|
+
|
137
|
+
-if-replica-exists
|
138
|
+
Returns exit code of 0 if no backups found.
|
139
|
+
|
140
|
+
-parallelism NUM
|
141
|
+
Determines the number of WAL files downloaded in parallel.
|
142
|
+
Defaults to 8
|
143
|
+
|
144
|
+
-replica NAME
|
145
|
+
Restore from a specific replica.
|
146
|
+
Defaults to replica with latest data.
|
147
|
+
|
148
|
+
-generation NAME
|
149
|
+
Restore from a specific generation.
|
150
|
+
Defaults to generation with latest data.
|
151
|
+
|
152
|
+
-index NUM
|
153
|
+
Restore up to a specific WAL index (inclusive).
|
154
|
+
Defaults to use the highest available index.
|
155
|
+
|
156
|
+
-timestamp TIMESTAMP
|
157
|
+
Restore to a specific point-in-time.
|
158
|
+
Defaults to use the latest available backup.
|
159
|
+
|
160
|
+
-config PATH
|
161
|
+
Specifies the configuration file.
|
162
|
+
Defaults to /etc/litestream.yml
|
163
|
+
|
164
|
+
-no-expand-env
|
165
|
+
Disables environment variable expansion in configuration file.
|
166
|
+
```
|
167
|
+
|
168
|
+
### Additional commands
|
169
|
+
|
170
|
+
The rake tasks are the recommended way to interact with the Litestream utility in your Rails application or Ruby project. But, you _can_ work directly with the Litestream CLI. Since the gem installs the native executable via Bundler, the `litestream` command will be available in your `PATH`.
|
171
|
+
|
172
|
+
The full set of commands available to the `litestream` executable are covered in Litestream's [command reference](https://litestream.io/reference/), but can be summarized as:
|
173
|
+
|
174
|
+
```shell
|
175
|
+
litestream databases [arguments]
|
176
|
+
litestream generations [arguments] DB_PATH|REPLICA_URL
|
177
|
+
litestream replicate [arguments]
|
178
|
+
litestream restore [arguments] DB_PATH|REPLICA_URL
|
179
|
+
litestream snapshots [arguments] DB_PATH|REPLICA_URL
|
180
|
+
litestream version
|
181
|
+
litestream wal [arguments] DB_PATH|REPLICA_URL
|
182
|
+
```
|
98
183
|
|
99
184
|
### Using in development
|
100
185
|
|
data/exe/litestream
CHANGED
@@ -5,7 +5,6 @@ require "litestream/commands"
|
|
5
5
|
|
6
6
|
begin
|
7
7
|
command = [Litestream::Commands.executable, *ARGV]
|
8
|
-
puts command.inspect
|
9
8
|
exec(*command)
|
10
9
|
rescue Litestream::Commands::UnsupportedPlatformException, Litestream::Commands::ExecutableNotFoundException => e
|
11
10
|
warn("ERROR: " + e.message)
|
data/lib/litestream/commands.rb
CHANGED
@@ -6,16 +6,13 @@ module Litestream
|
|
6
6
|
GEM_NAME = "litestream"
|
7
7
|
|
8
8
|
# raised when the host platform is not supported by upstream litestream's binary releases
|
9
|
-
|
10
|
-
end
|
9
|
+
UnsupportedPlatformException = Class.new(StandardError)
|
11
10
|
|
12
11
|
# raised when the litestream executable could not be found where we expected it to be
|
13
|
-
|
14
|
-
end
|
12
|
+
ExecutableNotFoundException = Class.new(StandardError)
|
15
13
|
|
16
14
|
# raised when LITESTREAM_INSTALL_DIR does not exist
|
17
|
-
|
18
|
-
end
|
15
|
+
DirectoryNotFoundException = Class.new(StandardError)
|
19
16
|
|
20
17
|
def self.platform
|
21
18
|
[:cpu, :os].map { |m| Gem::Platform.local.send(m) }.join("-")
|
@@ -74,9 +71,9 @@ module Litestream
|
|
74
71
|
|
75
72
|
def self.replicate(argv = {})
|
76
73
|
if Litestream.configuration
|
77
|
-
ENV["LITESTREAM_REPLICA_BUCKET"]
|
78
|
-
ENV["LITESTREAM_ACCESS_KEY_ID"]
|
79
|
-
ENV["LITESTREAM_SECRET_ACCESS_KEY"]
|
74
|
+
ENV["LITESTREAM_REPLICA_BUCKET"] ||= Litestream.configuration.replica_bucket
|
75
|
+
ENV["LITESTREAM_ACCESS_KEY_ID"] ||= Litestream.configuration.replica_key_id
|
76
|
+
ENV["LITESTREAM_SECRET_ACCESS_KEY"] ||= Litestream.configuration.replica_access_key
|
80
77
|
end
|
81
78
|
|
82
79
|
args = {
|
@@ -92,5 +89,32 @@ module Litestream
|
|
92
89
|
exec(*command)
|
93
90
|
end
|
94
91
|
end
|
92
|
+
|
93
|
+
def self.restore(database, argv = {})
|
94
|
+
if Litestream.configuration
|
95
|
+
ENV["LITESTREAM_REPLICA_BUCKET"] ||= Litestream.configuration.replica_bucket
|
96
|
+
ENV["LITESTREAM_ACCESS_KEY_ID"] ||= Litestream.configuration.replica_key_id
|
97
|
+
ENV["LITESTREAM_SECRET_ACCESS_KEY"] ||= Litestream.configuration.replica_access_key
|
98
|
+
end
|
99
|
+
|
100
|
+
dir, file = File.split(database)
|
101
|
+
ext = File.extname(file)
|
102
|
+
base = File.basename(file, ext)
|
103
|
+
now = Time.now.utc.strftime("%Y%m%d%H%M%S")
|
104
|
+
|
105
|
+
args = {
|
106
|
+
"--config" => Rails.root.join("config", "litestream.yml").to_s,
|
107
|
+
"-o" => File.join(dir, "#{base}-#{now}#{ext}")
|
108
|
+
}.merge(argv).to_a.flatten.compact
|
109
|
+
|
110
|
+
command = [executable, "restore", *args, database]
|
111
|
+
puts command.inspect
|
112
|
+
|
113
|
+
# To release the resources of the Ruby process, just fork and exit.
|
114
|
+
# The forked process executes litestream and replaces itself.
|
115
|
+
if fork.nil?
|
116
|
+
exec(*command)
|
117
|
+
end
|
118
|
+
end
|
95
119
|
end
|
96
120
|
end
|
data/lib/litestream/version.rb
CHANGED
data/lib/litestream.rb
CHANGED
@@ -13,7 +13,7 @@ namespace :litestream do
|
|
13
13
|
true
|
14
14
|
end
|
15
15
|
|
16
|
-
desc
|
16
|
+
desc 'Monitor and continuously replicate SQLite databases defined in your config file, e.g. rake litestream:replicate -- -exec "foreman start"'
|
17
17
|
task replicate: :environment do
|
18
18
|
options = {}
|
19
19
|
if (separator_index = ARGV.index("--"))
|
@@ -24,4 +24,16 @@ namespace :litestream do
|
|
24
24
|
|
25
25
|
Litestream::Commands.replicate(options)
|
26
26
|
end
|
27
|
+
|
28
|
+
desc "Restore a SQLite database from a Litestream replica, e.g. rake litestream:restore -- -database=storage/production.sqlite3"
|
29
|
+
task restore: :environment do
|
30
|
+
options = {}
|
31
|
+
if (separator_index = ARGV.index("--"))
|
32
|
+
ARGV.slice(separator_index + 1, ARGV.length)
|
33
|
+
.map { |pair| pair.split("=") }
|
34
|
+
.each { |opt| options[opt[0]] = opt[1] || nil }
|
35
|
+
end
|
36
|
+
|
37
|
+
Litestream::Commands.restore(options.delete("--database") || options.delete("-database"), options)
|
38
|
+
end
|
27
39
|
end
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: litestream
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.5.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Stephen Margheim
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2024-04-
|
11
|
+
date: 2024-04-17 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: rubyzip
|