backupper 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dd44245219b3c9f3a84381ec2be375ad988d94ba7f33d90c248510bf88b6c6a
-  data.tar.gz: 2b24cf425b081d25dbed494d5200322ed982472fb76eb74b90bee7c89a527984
+  metadata.gz: 6bcd9c73d5e46de14f981d0fc742f5142c9f66d5c4553ebe19face5c98d95626
+  data.tar.gz: '0708bc10f83d92061a9c16febaf56319b5bba9eed397529f7ce0bc00ec1e7bcc'
 SHA512:
-  metadata.gz: 6a6f0feda34408f60ff4a7353a0556dad3d79030b3cd2e5d0a5b90b06b562938631456ab60682c967ed91728f20e5fd39c2ab4e52d95311b413d1af8f36d51ba
-  data.tar.gz: a6d9390747c3cdd90bede2c7c83a3adb8af97aa05009cadffdbed0b1f523ea798c504c8ce4a1f45f1e15787182432b5d031a8256eb61d1a9476be4f3a9f0bf1d
+  metadata.gz: 77c91c30b33c1ea38a07537027e021f6be9ecd91878858701caaf452321d1a8244551360327f6e80d412996833cf69402021eb5d07b693fb6af4f1ed3491b79f
+  data.tar.gz: c56d8476dd7b7eea3f4fcc307a1311020630b132a564159759d763d0ea8b3ac180c2582c9c7f808a424ff6e32c57436974fa79eca1d2e8a4588adb24eca0d516

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backupper (0.6.1)
+    backupper (0.7.0)
       mail (~> 2.9)
       sshkit (~> 1.25)
 

data/README.md

@@ -33,7 +33,7 @@ db1:
   port: 22                                     # server ssh port
   password: Pa$$w0rD                           # server ssh password (also used as sudo password when sudo is true)
   sudo: false                                  # true to run the dump command with sudo
-  adapter: mysql                               # adapter to use to perform the backup (mysql, postgresql or mydumper)
+  adapter: mysql                               # adapter to use to perform the backup (built-in: mysql, postgresql, mydumper — see "Custom adapters")
   database: db_name                            # database name
   db_username: db_user                         # database username
   db_password: db_Pa$$w0rD                     # database password
@@ -62,15 +62,44 @@ ignoring the others configuration keys.
 
 ## Custom adapters
 
-An adapter is just a module method of `DumpCommand` that returns the shell command used to dump the database:
+An adapter is a subclass of `Backupper::Adapter` that declares the extension of the file it produces and builds the shell command used to dump the database:
 
 ```ruby
-def self.myadapter(database:, username: 'root', password: nil, dump_options: nil, working_dir: nil, outfile:)
-  return "mydump #{database} -u #{username} > #{outfile}"
+require 'backupper'
+
+class Foodump < Backupper::Adapter
+  # Automatically registered as 'foodump' (the underscored class name).
+  # Uncomment to use a different name for the `adapter:` configuration key:
+  # register 'foo'
+
+  def extension
+    return '.sql.gz'
+  end
+
+  def command
+    params = []
+    params << "-u #{username}"
+    params << "-p #{password}" if password
+    params << dump_options if dump_options
+    return "foodump #{database} #{params.join(' ')} | gzip > #{outfile}"
+  end
 end
 ```
 
-All the values arrive already shell-escaped: interpolate them as they are, without wrapping them in quotes. `dump_options` is parsed as shell-style arguments, then each argument is escaped before it reaches the adapter. The command must write the dump to `outfile`; `working_dir` is an empty temporary directory you can use as scratch space (both are removed from the server after the download). If your adapter produces a file format different from `.sql.bz2`, add its extension to `DumpCommand::EXTENSIONS`.
+Inside `command` you never deal with shell escaping: every accessor already returns a shell-escaped value, so interpolate them directly, without wrapping them in quotes.
+
+| accessor       | value                                                                    |
+|----------------|--------------------------------------------------------------------------|
+| `database`     | database name                                                            |
+| `username`     | database username                                                        |
+| `password`     | database password, or `nil` if not configured                            |
+| `dump_options` | extra options as a single escaped string, or `nil` if not configured     |
+| `outfile`      | remote path where the command must write the dump (extension included)  |
+| `working_dir`  | empty temporary directory you can use as scratch space                   |
+
+`command` must return a single command string (it is run with `set -o pipefail`, so chaining with `|` and `&&` is fine) and must write the dump to `outfile`. `working_dir` is created before the command runs; both `working_dir` and `outfile` are removed from the server after the download. If two adapters register the same name, the last one loaded wins, so a custom adapter can also replace a built-in one.
+
+⚠️ Upgrading from 0.6: custom adapters written as `DumpCommand` module methods no longer work; port each method to a `Backupper::Adapter` subclass as shown above. Also, `mydumper` archives now store the dump under its full remote path (`tmp/<key>__<database>/...`) instead of a top-level `<key>__<database>/` directory.
 
 ## Contributing
 

data/lib/backupper/adapter.rb

@@ -0,0 +1,118 @@
+require 'shellwords'
+
+class Backupper
+  # Base class for dump adapters. A subclass must implement `#extension` and
+  # `#command`; it is automatically registered under its underscored class
+  # name (use `register 'name'` to pick a different one).
+  class Adapter
+    @subclasses = []
+
+    class << self
+      def inherited(subclass)
+        super
+        Backupper::Adapter.subclasses << subclass
+      end
+
+      def register(name)
+        @adapter_name = name.to_s
+      end
+
+      def adapter_name
+        return @adapter_name if defined?(@adapter_name) && @adapter_name
+        # On Ruby < 3.0 `inherited` fires before the constant is assigned, so
+        # the name must be derived lazily, at lookup time.
+        return nil if name.nil?
+
+        basename = name.split('::').last
+        return basename.gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      def find(name)
+        # Reverse scan: a later-loaded custom adapter can shadow a built-in name.
+        return Backupper::Adapter.subclasses.reverse_each.find { |klass| klass.adapter_name == name.to_s }
+      end
+
+      def names
+        return Backupper::Adapter.subclasses.map(&:adapter_name).compact.uniq.sort
+      end
+
+      def subclasses
+        return @subclasses ||= []
+      end
+
+      def shellescape_dump_options(dump_options)
+        return nil if dump_options.nil?
+
+        options =
+          if dump_options.is_a?(Array)
+            dump_options.map(&:to_s)
+          else
+            Shellwords.split(dump_options.to_s)
+          end
+        return nil if options.empty?
+
+        return options.map { |option| Shellwords.escape(option) }.join(' ')
+      rescue ArgumentError => e
+        raise ArgumentError, "Invalid dump_options: #{e.message}"
+      end
+    end
+
+    # All values arrive raw; escaping happens in the accessors below.
+    def initialize(database:, username: 'root', password: nil, dump_options: nil, basename:, tmp_dir: '/tmp')
+      @raw_database = database
+      @raw_username = username
+      @raw_password = password
+      @raw_dump_options = dump_options
+      @raw_basename = basename
+      @raw_tmp_dir = tmp_dir
+    end
+
+    # Extension of the file produced by `#command` (e.g. '.sql.bz2').
+    def extension
+      raise NotImplementedError, "#{self.class} must implement #extension"
+    end
+
+    # Shell command that writes the dump to `outfile`.
+    def command
+      raise NotImplementedError, "#{self.class} must implement #command"
+    end
+
+    # Raw paths, for the orchestrator (SSHKit download!, report).
+    def filename
+      return "#{@raw_basename}#{extension}"
+    end
+
+    def outfile_path
+      return File.join(@raw_tmp_dir, filename)
+    end
+
+    def working_dir_path
+      return File.join(@raw_tmp_dir, @raw_basename)
+    end
+
+    # Shell-escaped accessors: interpolate them directly in `#command`.
+    def database
+      return Shellwords.escape(@raw_database)
+    end
+
+    def username
+      return Shellwords.escape(@raw_username)
+    end
+
+    def password
+      return @raw_password && Shellwords.escape(@raw_password)
+    end
+
+    def dump_options
+      return Backupper::Adapter.shellescape_dump_options(@raw_dump_options)
+    end
+
+    def outfile
+      return Shellwords.escape(outfile_path)
+    end
+
+    def working_dir
+      return Shellwords.escape(working_dir_path)
+    end
+  end
+end

data/lib/backupper/adapters/mydumper.rb

@@ -0,0 +1,19 @@
+require_relative '../adapter'
+
+class Backupper
+  module Adapters
+    class Mydumper < Backupper::Adapter
+      def extension
+        return '.tar'
+      end
+
+      def command
+        params = []
+        params << "--user #{username}"
+        params << "--password #{password}" if password
+        params << dump_options if dump_options
+        return "mydumper --database #{database} #{params.join(' ')} --outputdir #{working_dir} && tar -cf #{outfile} #{working_dir}"
+      end
+    end
+  end
+end

data/lib/backupper/adapters/mysql.rb

@@ -0,0 +1,19 @@
+require_relative '../adapter'
+
+class Backupper
+  module Adapters
+    class Mysql < Backupper::Adapter
+      def extension
+        return '.sql.bz2'
+      end
+
+      def command
+        params = []
+        params << "-u#{username}"
+        params << "-p#{password}" if password
+        params << dump_options if dump_options
+        return "mysqldump #{database} #{params.join(' ')} | bzip2 > #{outfile}"
+      end
+    end
+  end
+end

data/lib/backupper/adapters/postgresql.rb

@@ -0,0 +1,18 @@
+require_relative '../adapter'
+
+class Backupper
+  module Adapters
+    class Postgresql < Backupper::Adapter
+      def extension
+        return '.sql.bz2'
+      end
+
+      def command
+        params = []
+        params << "-U #{username}"
+        params << dump_options if dump_options
+        return "PGPASSWORD=#{password} pg_dump #{database} #{params.join(' ')} | bzip2 > #{outfile}"
+      end
+    end
+  end
+end

data/lib/backupper/backupper.rb

@@ -1,10 +1,12 @@
 require 'fileutils'
-require 'shellwords'
 require 'sshkit'
 require 'sshkit/dsl'
 require 'yaml'
 
-require_relative 'dump_command'
+require_relative 'adapter'
+require_relative 'adapters/mysql'
+require_relative 'adapters/postgresql'
+require_relative 'adapters/mydumper'
 require_relative 'mailer'
 require_relative 'sshkit'
 
@@ -60,7 +62,7 @@ class Backupper
           outdir:       o['outdir'],
           extra_copy:   o['extra_copy']
         )
-      rescue SSHKit::Runner::ExecuteError => e
+      rescue SSHKit::Runner::ExecuteError, ArgumentError, NotImplementedError => e
         error(k, e.to_s)
         @logger.error e
       end
@@ -72,30 +74,23 @@ class Backupper
 
     def do_and_download_dump(key:, adapter: 'mysql', url:, password: nil, database:, db_username: 'root', db_password: nil, dump_options: nil, sudo: false, outdir:, extra_copy: nil)
       t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      filename = "#{key}__#{database}#{DumpCommand::EXTENSIONS[adapter]}"
-      temp_file = File.join('/tmp', filename)
-      working_dirname = "#{key}__#{database}"
-      temp_working_dir = File.join('/tmp', working_dirname)
-      dump_name = "#{Time.now.strftime('%Y-%m-%d_%H-%M-%S')}__#{filename}"
+      adapter = Adapter.find(adapter).new(
+        database: database,
+        username: db_username,
+        password: db_password,
+        dump_options: dump_options,
+        basename: "#{key}__#{database}"
+      )
+      dump_name = "#{Time.now.strftime('%Y-%m-%d_%H-%M-%S')}__#{adapter.filename}"
       path = File.join(outdir, dump_name)
-      outfile = Shellwords.escape(temp_file)
-      working_dir = Shellwords.escape(temp_working_dir)
+      command = adapter.command
       on(url) do |host|
         host.password = password
-        sudo_execute :mkdir, '-p', working_dir, password: password, sudo: sudo
-        command = DumpCommand.public_send(
-          adapter,
-          database: Shellwords.escape(database),
-          username: Shellwords.escape(db_username),
-          password: db_password && Shellwords.escape(db_password),
-          dump_options: dump_options,
-          working_dir: working_dir,
-          outfile: outfile
-        )
+        sudo_execute :mkdir, '-p', adapter.working_dir, password: password, sudo: sudo
         sudo_execute 'set -o pipefail; ' + command, password: password, sudo: sudo
-        download! temp_file, path
-        sudo_execute :rm, outfile, password: password, sudo: sudo
-        sudo_execute :rm, '-r', working_dir, password: password, sudo: sudo
+        download! adapter.outfile_path, path
+        sudo_execute :rm, adapter.outfile, password: password, sudo: sudo
+        sudo_execute :rm, '-r', adapter.working_dir, password: password, sudo: sudo
       end
       extra_copy = check_dir(extra_copy)
       FileUtils.cp(path, extra_copy) if extra_copy
@@ -118,11 +113,11 @@ class Backupper
       o['url'] = "#{o['username']}@#{o['url']}" if o['username']
       o['url'] = "#{o['url']}:#{o['port']}" if o['port']
       o['adapter'] ||= 'mysql'
-      unless DumpCommand.singleton_methods(false).map(&:to_s).include?(o['adapter'])
-        return nil, "Cannot handle adapter '#{o['adapter']}' (supported: #{DumpCommand.singleton_methods(false).join(', ')})"
+      if Adapter.find(o['adapter']).nil?
+        return nil, "Cannot handle adapter '#{o['adapter']}' (supported: #{Adapter.names.join(', ')})"
       end
       begin
-        shellescape_dump_options(o['dump_options'])
+        Adapter.shellescape_dump_options(o['dump_options'])
       rescue ArgumentError => e
         return nil, e.message
       end
@@ -130,22 +125,6 @@ class Backupper
       return o, nil
     end
 
-    def shellescape_dump_options(dump_options)
-      return nil if dump_options.nil?
-
-      options =
-        if dump_options.is_a?(Array)
-          dump_options.map(&:to_s)
-        else
-          Shellwords.split(dump_options.to_s)
-        end
-      return nil if options.empty?
-
-      return options.map { |option| Shellwords.escape(option) }.join(' ')
-    rescue ArgumentError => e
-      raise ArgumentError, "Invalid dump_options: #{e.message}"
-    end
-
     def send_report_email!
       if @report.any? && @mailer['from'] && @mailer['to'] && @mailer['password']
         begin

data/lib/backupper/version.rb

@@ -1,3 +1,3 @@
 class Backupper
-  VERSION = '0.6.1'.freeze
+  VERSION = '0.7.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backupper
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - pioz
@@ -83,8 +83,11 @@ files:
 - backupper.gemspec
 - bin/backupper
 - lib/backupper.rb
+- lib/backupper/adapter.rb
+- lib/backupper/adapters/mydumper.rb
+- lib/backupper/adapters/mysql.rb
+- lib/backupper/adapters/postgresql.rb
 - lib/backupper/backupper.rb
-- lib/backupper/dump_command.rb
 - lib/backupper/mailer.rb
 - lib/backupper/sshkit.rb
 - lib/backupper/version.rb

data/lib/backupper/dump_command.rb

@@ -1,27 +0,0 @@
-module DumpCommand
-  # Extension of the file produced by each adapter ('.sql.bz2' if not listed here)
-  EXTENSIONS = Hash.new('.sql.bz2').update('mydumper' => '.tar').freeze
-
-  def self.mysql(database:, username: 'root', password: nil, dump_options: nil, working_dir: nil, outfile:)
-    params = []
-    params << "-u#{username}"
-    params << "-p#{password}" if password
-    params << dump_options if dump_options
-    return "mysqldump #{database} #{params.join(' ')} | bzip2 > #{outfile}"
-  end
-
-  def self.postgresql(database:, username: 'root', password: nil, dump_options: nil, working_dir: nil, outfile:)
-    params = []
-    params << "-U #{username}"
-    params << dump_options if dump_options
-    return "PGPASSWORD=#{password} pg_dump #{database} #{params.join(' ')} | bzip2 > #{outfile}"
-  end
-
-  def self.mydumper(database:, username: 'root', password: nil, dump_options: nil, working_dir: nil, outfile:)
-    params = []
-    params << "--user #{username}"
-    params << "--password #{password}" if password
-    params << dump_options if dump_options
-    return "mydumper --database #{database} #{params.join(' ')} --outputdir #{working_dir} && tar -cf #{outfile} -C #{File.dirname(working_dir)} #{File.basename(working_dir)}"
-  end
-end