solid_backup 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee957011ccc278fb06096635c8b158939f283538bb5ccc25869ba07d3bb7bb5a
+  data.tar.gz: ea9cdbdbd9e9ae3ae0fdb4b252b9db1c412e80d3288258c8ccf4062e59a70b66
+SHA512:
+  metadata.gz: '0802038b0aeac7c0b0bebbf1b8b6d68054b52621ef1c50c9c21f1a640866fb2f1e51ee9a3d98bc6fef80a5b63ab85c4ed9cec500e7ba86ddc24bf45fe65d3c33'
+  data.tar.gz: 82bec8bad5efe105b5ad7247b6f0754fda99381baafdcaff36704c249a36996c86bf0d1e65e1d4cd81a896a03513cc631a0c4540dc6b501115b5b3134f0936c5

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2026 Greg Navis
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,87 @@
+# Solid Backup
+
+Solid Backup provides simple backups for SQLite databases in Ruby on Rails apps.
+
+## Installation
+
+In order to install Solid Backup run:
+
+1. `bundle add solid_backup`.
+2. `bin/rails generate solid_backup:install`.
+
+The generator will go over all production SQLite databases and ask you whether
+you want to back up each one of them. By default, it uses the `API` mode. It'll
+also create `storage/backups` and install the Puma plugin.
+
+That's it! Read the following section to learn how to customize the backup
+process.
+
+## Configuration
+
+Solid Backup **REQUIRES** each SQLite production database to have a backup mode set,
+with the goal of ensuring all databases were taken into consideration and none
+will lack backups due to omission. There are three database backup modes:
+
+- `SolidBackup::Backup::None` - don't back up.
+- `SolidBackup::Backup::API` - use [the SQLite3 backup API].
+- `SolidBackup::Backup::VacuumInto` - use [`VACUUM INTO`].
+
+Modes other than `SolidBackup::Backup::None` take the following parameters:
+
+- `destination` - a `strftime` template used to generate backup file names; the
+                  directory under which the files are placed must already exist
+                  and be writeable.
+- `interval_in_minutes` - the number of minutes to the beginning of the next
+                          backup after the previous one finished.
+
+Additionally, `SolidBackup::Backup::API` takes the following parameters:
+
+- `step` - the number of database pages to back up in one step.
+- `wait` - how many seconds to wait in case the backup process run into a lock.
+
+The following example configuration file demonstrates how to use each backup
+mode in practice:
+
+```ruby
+SolidBackup.configure do |config|
+	# Back up the primary database using the SQLite backup API.
+  config.backup "primary",
+                SolidBackup::Backup::API,
+                destination: "storage/backups/primary_%Y%m%dT%H%M%S.sqlite3",
+                interval_in_minutes: 15, # Start the next backup 15 minutes after the previous one.
+                step: 100,               # Back up in 100-page increments.
+                wait: 0.1                # Wait 0.1 seconds if a lock interrupts a backup step.
+
+	# Don't back up the cache database.
+  config.backup "cache", SolidBackup::Backup::None
+
+  # Back up the queue database using VACUUM INTO.
+  config.backup "queue",
+                SolidBackup::Backup::VacuumInto,
+                destination: "storage/backups/queue_%Y%m%dT%H%M%S.sqlite3",
+                interval_in_minutes: 60 # Start the next backup 60 minutes after the previous one.
+end
+```
+
+## Puma plugin
+
+Solid Backup ships with a Puma plugin that runs the backup process in the
+background on schedule. The install generator installs it automatically, but if
+you need to install it manually you can add the following line to `puma.rb`:
+
+```ruby
+plugin "solid_backup"
+```
+
+## Ruby and Rails Compatibility Policy
+
+Solid Backup supports Rails versions supported by the Rails Core Team and Ruby
+versions supported by all supported Rails versions.
+
+## Author
+
+This gem was created and is maintained by [Greg Navis].
+
+[Greg Navis]: https://www.gregnavis.com/
+[the SQLite3 backup API]: https://sqlite.org/c3ref/backup_finish.html
+[`VACUUM INTO`]: https://sqlite.org/lang_vacuum.html#vacuuminto

data/lib/puma/plugin/solid_backup.rb

@@ -0,0 +1,15 @@
+require "puma/plugin"
+require "solid_backup"
+
+Puma::Plugin.create do
+  def start(launcher)
+    return if SolidBackup.disabled?
+
+    in_background do
+      loop do
+        sleep(1)
+        SolidBackup.tick
+      end
+    end
+  end
+end

data/lib/solid_backup/backup/api.rb

@@ -0,0 +1,38 @@
+class SolidBackup::Backup::API < SolidBackup::Backup
+  def initialize(step:, wait:, **)
+    super(**)
+
+    self.step = Integer(step)
+    self.wait = Float(wait)
+  end
+
+  private
+
+  attr_accessor :step, :wait
+
+  def do_perform(backup_path)
+    with_connection do |connection|
+      source = connection.raw_connection
+      destination = SQLite3::Database.new(backup_path)
+
+      backup = SQLite3::Backup.new(destination, "main", source, "main")
+
+      loop do
+        result = backup.step(step)
+        case result
+        when SQLite3::Constants::ErrorCode::DONE
+          break
+        when SQLite3::Constants::ErrorCode::OK
+          next
+        when SQLite3::Constants::ErrorCode::BUSY, SQLite3::Constants::ErrorCode::LOCKED
+          sleep(wait)
+        else
+          raise "SQLite backup failed with #{result.inspect}"
+        end
+      end
+
+      backup.finish
+      destination.close
+    end
+  end
+end

data/lib/solid_backup/backup/none.rb

@@ -0,0 +1,25 @@
+# None is a special case: all other backup methods need a destination and
+# interval, but it doesn't make sense to pass them to None. That's why it
+# overrides:
+#
+# - tick - to avoid the countdown
+# - perform - to avoid creating lock files and emitting instrumentation events
+# - destination and interval_in_minutes - to allow nil values
+class SolidBackup::Backup::None < SolidBackup::Backup
+  def initialize(name:)
+    super(name:, destination: nil, interval_in_minutes: 0)
+  end
+
+  def tick
+  end
+
+  def perform
+  end
+
+  private
+
+  attr_writer :destination, :interval_in_minutes
+
+  def do_perform(backup_path)
+  end
+end

data/lib/solid_backup/backup/vacuum_into.rb

@@ -0,0 +1,9 @@
+class SolidBackup::Backup::VacuumInto < SolidBackup::Backup
+  private
+
+  def do_perform(backup_path)
+    with_connection do |connection|
+      connection.exec_query("VACUUM INTO ?", "Solid Backup", [backup_path.to_s])
+    end
+  end
+end

data/lib/solid_backup/backup.rb

@@ -0,0 +1,101 @@
+module SolidBackup
+  class Backup
+    attr_reader :name
+
+    def initialize(name:, destination:, interval_in_minutes:)
+      self.name = name
+      self.destination = destination
+      self.interval_in_minutes = interval_in_minutes
+
+      reset_countdown
+    end
+
+    def tick
+      if countdown > 0
+        self.countdown -= 1
+      end
+
+      if countdown <= 0
+        perform
+        reset_countdown
+      end
+    end
+
+    def perform
+      ActiveSupport::Notifications.instrument("backup.solid_backup", name:) do
+        lock do
+          do_perform(Time.now.utc.strftime(destination.to_s))
+        end
+      end
+    end
+
+    private
+
+    attr_accessor :countdown
+    attr_writer :name
+    attr_reader :destination, :interval_in_minutes
+
+    def interval_in_minutes=(value)
+      if !value.is_a?(Integer) && value <= 0
+        raise TypeError.new(<<~ERROR)
+          invalid backup configuration for #{name}: interval_in_minutes is set to #{interval_in_minutes.inspect}, but should be set to a positive integer
+        ERROR
+      end
+
+      @interval_in_minutes = value
+    end
+
+    def destination=(value)
+      value = Pathname(value)
+      directory = value.dirname
+
+      if !directory.directory?
+        raise "invalid backup configuration for #{name}: destination directory #{directory} must exist"
+      end
+
+      test_path = directory / "solid_backup.txt"
+      begin
+        test_path.write("Solid Backup Test")
+      rescue Errno::EACCESS
+        raise "invalid backup configuration for #{name}: destination directory #{directory} must be writeable"
+      ensure
+        test_path.unlink
+      end
+
+      @destination = value
+    end
+
+    def reset_countdown
+      self.countdown = 60 * interval_in_minutes
+    end
+
+    def do_perform(backup_path)
+      raise "must be implemented by a subclass"
+    end
+
+    def connection_pool
+      ActiveRecord::Base.connection_handler.establish_connection(name.to_sym)
+    end
+
+    delegate :with_connection, to: :connection_pool
+
+    def lock
+      path = destination.dirname / ".solid_backup.#{name}.lock"
+
+      File.open(path, File::RDWR | File::CREAT) do |f|
+        if f.flock(File::LOCK_EX | File::LOCK_NB)
+          begin
+            yield
+          ensure
+            f.flock(File::LOCK_UN)
+          end
+        end
+      end
+
+      begin
+        File.unlink(path)
+      rescue ERRNO::ENOENT
+      end
+    end
+  end
+end

data/lib/solid_backup/configuration.rb

@@ -0,0 +1,50 @@
+module SolidBackup
+  class Configuration
+    attr_accessor :enabled
+    attr_reader :algorithms
+
+    def initialize
+      self.enabled = nil
+      self.algorithms = []
+    end
+
+    def backup(name, algorithm_class, **algorithm_arguments)
+      name = name.to_s
+      if algorithms.find { it.name == name }
+        raise ArgumentError.new("#{name} has had backups configured already")
+      end
+
+      algorithms << algorithm_class.new(name:, **algorithm_arguments)
+    end
+
+    def validate!
+      if [true, false].exclude?(enabled)
+        raise TypeError.new("enabled is set to #{enabled.inspect}, but allowed values are true or false")
+      end
+
+      configured_database_names = algorithms.map(&:name)
+      all_database_names = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).select do |db_config|
+        db_config.adapter == "sqlite3"
+      end.map(&:name)
+
+      if (missing_databases = all_database_names - configured_database_names).present?
+        raise "SQLite databases missing from backup configuration: #{missing_databases.join(", ")}"
+      end
+      if (unknown_databases = configured_database_names - all_database_names).present?
+        raise "unknown SQLite databases present in backup configuration: #{unknown_databases.join(", ")}"
+      end
+    end
+
+    def enabled?
+      enabled
+    end
+
+    def disabled?
+      !enabled?
+    end
+
+    private
+
+    attr_writer :algorithms
+  end
+end

data/lib/solid_backup/generators/install_generator.rb

@@ -0,0 +1,54 @@
+require "rails/generators"
+
+module SolidBackup
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Solid Backup initializer"
+
+      def copy_initializer
+        backups = []
+
+        ActiveRecord::Base.configurations.configs_for(env_name: "production").each do |db_config|
+          backups << if yes?("Back up #{db_config.name} in production?")
+            <<~CODE.chomp
+              config.backup #{db_config.name.inspect},
+                            SolidBackup::Backup::API,
+                            destination: "storage/backups/#{db_config.name}_%Y%m%dT%H%M%S.sqlite3",
+                            interval_in_minutes: 60,
+                            step: 100,
+                            wait: 0.1
+            CODE
+          else
+            "config.backup #{db_config.name.inspect}, SolidBackup::Backup::None"
+          end
+        end
+
+        initializer "solid_backup.rb", <<~CODE
+          SolidBackup.configure do |config|
+            # Enable or disable Solid Backup globally.
+            config.enabled = Rails.env.production?
+
+            # Backup configuration for each database.
+            #
+            # IMPORTANT: all databases must be explicitly configured, even if they're not
+            # backed up, to avoid accidentally excluding new databases from backups.
+          #{backups.join("\n").indent(2)}
+          end
+        CODE
+
+        insert_into_file "config/puma.rb", <<~CODE
+
+          # Run Solid Backup in the background.
+          plugin :solid_backup
+        CODE
+
+        empty_directory "storage/backups"
+        create_file "storage/backups/.keep"
+
+        insert_into_file ".gitignore", "!/storage/backups/.keep\n", after: "!/storage/.keep\n"
+      end
+    end
+  end
+end

data/lib/solid_backup/railtie.rb

@@ -0,0 +1,13 @@
+require "rails"
+
+module SolidBackup
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative "generators/install_generator"
+    end
+
+    config.after_initialize do
+      SolidBackup.configuration&.validate!
+    end
+  end
+end

data/lib/solid_backup/version.rb

@@ -0,0 +1,3 @@
+module SolidBackup
+  VERSION = "0.1.0"
+end

data/lib/solid_backup.rb

@@ -0,0 +1,28 @@
+require "solid_backup/backup"
+require "solid_backup/backup/none"
+require "solid_backup/backup/api"
+require "solid_backup/backup/vacuum_into"
+require "solid_backup/configuration"
+require "solid_backup/version"
+require "solid_backup/railtie"
+
+module SolidBackup
+  class << self
+    delegate :enabled?, :disabled?, to: :configuration
+
+    attr_reader :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def tick
+      configuration.algorithms.each(&:tick)
+    end
+
+    private
+
+    attr_writer :configuration
+  end
+end

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: solid_backup
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Greg Navis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.56'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.56'
+description: Solid Backup makes it easy to backup SQLite databases using VACUUM INTO
+  or the backup API.
+email:
+- contact@gregnavis.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE.txt
+- README.md
+- lib/puma/plugin/solid_backup.rb
+- lib/solid_backup.rb
+- lib/solid_backup/backup.rb
+- lib/solid_backup/backup/api.rb
+- lib/solid_backup/backup/none.rb
+- lib/solid_backup/backup/vacuum_into.rb
+- lib/solid_backup/configuration.rb
+- lib/solid_backup/generators/install_generator.rb
+- lib/solid_backup/railtie.rb
+- lib/solid_backup/version.rb
+homepage: https://github.com/gregnavis/solid_backup
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/gregnavis/solid_backup
+  bug_tracker_uri: https://github.com/gregnavis/solid_backup/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Solid Backup provides simple backups for SQLite databases in Ruby on Rails
+  apps.
+test_files: []