departure-next 6.7.1.pre.pre

data/lib/departure/connection_details.rb

@@ -0,0 +1,121 @@
+require 'shellwords'
+module Departure
+  # Holds the parameters of the DB connection and formats them to string
+  class ConnectionDetails
+    DEFAULT_PORT = 3306
+    # Constructor
+    #
+    # @param connection_data [Hash] connection parameters as used in #establish_conneciton
+    def initialize(connection_data)
+      @connection_data = connection_data
+    end
+
+    # Returns the details formatted as an string to be used with
+    # pt-online-schema-change. It follows the mysql client's format.
+    #
+    # @return [String]
+    def to_s
+      @to_s ||= "#{base_connection} -u #{user} #{password_argument}"
+    end
+
+    # TODO: Doesn't the abstract adapter already handle this somehow?
+    # Returns the database name. If PERCONA_DB_NAME is passed its value will be
+    # used instead
+    #
+    # Returns the database name
+    #
+    # @return [String]
+    def database
+      ENV.fetch('PERCONA_DB_NAME', connection_data[:database])
+    end
+
+    # Returns the password fragment of the details string if a password is passed
+    #
+    # @return [String]
+    def password_argument
+      if password.present?
+        %(--password #{Shellwords.escape(password)} )
+      else
+        ''
+      end
+    end
+
+    private
+
+    attr_reader :connection_data
+
+    # Returns conditionally host or socket configuration
+    #
+    # @return [String]
+    def base_connection
+      return socket_argument if socket.present?
+
+      "#{host_argument} -P #{port}"
+    end
+
+    # Returns the host fragment of the details string, adds ssl options if needed
+    #
+    # @return [String]
+    def host_argument
+      host_string = host
+      if ssl_ca.present?
+        host_string += ";mysql_ssl=1;mysql_ssl_client_ca=#{ssl_ca}"
+      end
+      "-h \"#{host_string}\""
+    end
+
+    # Returns the socket fragment of the details string
+    # FIXME: SSL connection
+    #
+    # @return [String]
+    def socket_argument
+      "-S #{socket}"
+    end
+
+    # Returns the database host name, defaulting to localhost. If PERCONA_DB_HOST
+    # is passed its value will be used instead
+    #
+    # @return [String]
+    def host
+      ENV.fetch('PERCONA_DB_HOST', connection_data[:host]) || 'localhost'
+    end
+
+    # Returns the database user. If PERCONA_DB_USER is passed its value will be
+    # used instead
+    #
+    # @return [String]
+    def user
+      ENV.fetch('PERCONA_DB_USER', connection_data[:username])
+    end
+
+    # Returns the database user's password. If PERCONA_DB_PASSWORD is passed its
+    # value will be used instead
+    #
+    # @return [String]
+    def password
+      ENV.fetch('PERCONA_DB_PASSWORD', connection_data[:password])
+    end
+
+    # Returns the database socket path. If PERCONA_DB_SOCKET is passed its value
+    # will be used instead
+    #
+    # @return [String]
+    def socket
+      ENV.fetch('PERCONA_DB_SOCKET', connection_data[:socket])
+    end
+
+    # Returns the database's port.
+    #
+    # @return [String]
+    def port
+      connection_data.fetch(:port, DEFAULT_PORT)
+    end
+
+    # Returns the database' SSL CA certificate.
+    #
+    # @return [String]
+    def ssl_ca
+      connection_data.fetch(:sslca, nil)
+    end
+  end
+end

data/lib/departure/dsn.rb

@@ -0,0 +1,25 @@
+module Departure
+  # Represents the 'DSN' argument of Percona's pt-online-schema-change
+  # See https://www.percona.com/doc/percona-toolkit/2.0/pt-online-schema-change.html#dsn-options
+  class DSN
+    # Constructor
+    #
+    # @param database [String, Symbol]
+    # @param table_name [String, Symbol]
+    def initialize(database, table_name)
+      @database = database
+      @table_name = table_name
+      @suffix = ENV.fetch('PERCONA_DSN_SUFFIX', nil)
+    end
+
+    # Returns the pt-online-schema-change DSN string. See
+    # https://www.percona.com/doc/percona-toolkit/2.0/pt-online-schema-change.html#dsn-options
+    def to_s
+      "D=#{database},t=#{table_name}#{suffix.nil? ? nil : ',' + suffix}"
+    end
+
+    private
+
+    attr_reader :table_name, :database, :suffix
+  end
+end

data/lib/departure/errors.rb

@@ -0,0 +1,39 @@
+module Departure
+  class Error < StandardError; end
+
+  # Used when for whatever reason we couldn't get the spawned process'
+  # status.
+  class NoStatusError < Error
+    def message
+      'Status could not be retrieved'.freeze
+    end
+  end
+
+  # Used when the spawned process failed by receiving a signal.
+  # pt-online-schema-change returns "SIGSEGV (signal 11)" on failures.
+  class SignalError < Error
+    attr_reader :status
+
+    # Constructor
+    #
+    # @param status [Process::Status]
+    def initialize(status)
+      super
+      @status = status
+    end
+
+    def message
+      status.to_s
+    end
+  end
+
+  class CommandNotFoundError < Error
+    def message
+      'Please install pt-online-schema-change. Check: https://www.percona.com/doc/percona-toolkit for further details'
+    end
+  end
+
+  # Used to prevent running the db:migrate rake task when providing arguments
+  # through PERCONA_ARGS env var
+  class ArgumentsNotSupported < Error; end
+end

data/lib/departure/log_sanitizers/password_sanitizer.rb

@@ -0,0 +1,22 @@
+module Departure
+  module LogSanitizers
+    class PasswordSanitizer
+      PASSWORD_REPLACEMENT = '[filtered_password]'.freeze
+
+      delegate :password_argument, to: :connection_details
+
+      def initialize(connection_details)
+        @connection_details = connection_details
+      end
+
+      def execute(log_statement)
+        return log_statement if password_argument.blank?
+        log_statement.gsub(password_argument, PASSWORD_REPLACEMENT)
+      end
+
+      private
+
+      attr_accessor :connection_details
+    end
+  end
+end

data/lib/departure/logger.rb

@@ -0,0 +1,42 @@
+module Departure
+  # Copies the ActiveRecord::Migration #say and #write plus a new
+  # #write_no_newline to log the migration's status. It's not possible to reuse
+  # the from ActiveRecord::Migration because the migration's instance can't be
+  # seen from the connection adapter.
+  class Logger
+    def initialize(sanitizers)
+      @sanitizers = sanitizers
+    end
+
+    # Outputs the message through the stdout, following the
+    # ActiveRecord::Migration log format
+    #
+    # @param message [String]
+    # @param subitem [Boolean] whether to show message as a nested log item
+    def say(message, subitem = false)
+      write "#{subitem ? '   ->' : '--'} #{message}"
+    end
+
+    # Outputs the text through the stdout adding a new line at the end
+    #
+    # @param text [String]
+    def write(text = '')
+      puts(sanitize(text))
+    end
+
+    # Outputs the text through the stdout without adding a new line at the end
+    #
+    # @param text [String]
+    def write_no_newline(text)
+      print(sanitize(text))
+    end
+
+    private
+
+    attr_accessor :sanitizers
+
+    def sanitize(text)
+      sanitizers.inject(text) { |memo, sanitizer| sanitizer.execute(memo) }
+    end
+  end
+end

data/lib/departure/logger_factory.rb

@@ -0,0 +1,16 @@
+module Departure
+  module LoggerFactory
+    # Returns the appropriate logger instance for the given configuration. Use
+    # :verbose option to log to the stdout
+    #
+    # @param verbose [Boolean]
+    # @return [#say, #write]
+    def self.build(sanitizers: [], verbose: true)
+      if verbose
+        Departure::Logger.new(sanitizers)
+      else
+        Departure::NullLogger.new
+      end
+    end
+  end
+end

data/lib/departure/migration.rb

@@ -0,0 +1,104 @@
+module Departure
+  # Hooks Departure into Rails migrations by replacing the configured database
+  # adapter.
+  #
+  # It also patches ActiveRecord's #migrate method so that it patches LHM
+  # first. This will make migrations written with LHM to go through the
+  # regular Rails Migration DSL.
+  module Migration
+    extend ActiveSupport::Concern
+
+    included do
+      # Holds the name of the adapter that was configured by the app.
+      mattr_accessor :original_adapter
+
+      # Declare on a per-migration class basis whether or not to use Departure.
+      # The default for this attribute is set based on
+      # Departure.configuration.enabled_by_default (default true).
+      class_attribute :uses_departure
+      self.uses_departure = true
+
+      alias_method :active_record_migrate, :migrate
+      remove_method :migrate
+    end
+
+    module ClassMethods
+      # Declare `uses_departure!` in the class body of your migration to enable
+      # Departure for that migration only when
+      # Departure.configuration.enabled_by_default is false.
+      def uses_departure!
+        self.uses_departure = true
+      end
+
+      # Declare `disable_departure!` in the class body of your migration to
+      # disable Departure for that migration only (when
+      # Departure.configuration.enabled_by_default is true, the default).
+      def disable_departure!
+        self.uses_departure = false
+      end
+    end
+
+    # Replaces the current connection adapter with the PerconaAdapter and
+    # patches LHM, then it continues with the regular migration process.
+    #
+    # @param direction [Symbol] :up or :down
+    def departure_migrate(direction)
+      reconnect_with_percona
+      include_foreigner if defined?(Foreigner)
+
+      ::Lhm.migration = self
+      active_record_migrate(direction)
+    end
+
+    # Migrate with or without Departure based on uses_departure class
+    # attribute.
+    def migrate(direction)
+      if uses_departure?
+        departure_migrate(direction)
+      else
+        reconnect_without_percona
+        active_record_migrate(direction)
+      end
+    end
+
+    # Includes the Foreigner's Mysql2Adapter implemention in
+    # DepartureAdapter to support foreign keys
+    def include_foreigner
+      Foreigner::Adapter.safe_include(
+        :DepartureAdapter,
+        Foreigner::ConnectionAdapters::Mysql2Adapter
+      )
+    end
+
+    # Make all connections in the connection pool to use PerconaAdapter
+    # instead of the current adapter.
+    def reconnect_with_percona
+      return if connection_config[:adapter] == 'percona'
+      Departure::ConnectionBase.establish_connection(connection_config.merge(adapter: 'percona'))
+    end
+
+    # Reconnect without percona adapter when Departure is disabled but was
+    # enabled in a previous migration.
+    def reconnect_without_percona
+      return unless connection_config[:adapter] == 'percona'
+      Departure::OriginalAdapterConnection.establish_connection(connection_config.merge(adapter: original_adapter))
+    end
+
+    private
+
+    # Capture the type of the adapter configured by the app if not already set.
+    def connection_config
+      configuration_hash.tap do |config|
+        self.class.original_adapter ||= config[:adapter]
+      end
+    end
+
+    private def configuration_hash
+      if ActiveRecord::VERSION::STRING >= '6.1'
+        ActiveRecord::Base.connection_db_config.configuration_hash
+      else
+        ActiveRecord::Base.connection_config
+      end
+    end
+  end
+end

data/lib/departure/null_logger.rb

@@ -0,0 +1,15 @@
+module Departure
+  class NullLogger
+    def say(_message, _subitem = false)
+      # noop
+    end
+
+    def write(_text)
+      # noop
+    end
+
+    def write_no_newline(_text)
+      # noop
+    end
+  end
+end

data/lib/departure/option.rb

@@ -0,0 +1,75 @@
+module Departure
+  class Option
+    attr_reader :name, :value
+
+    # Builds an instance by parsing its name and value out of the given string.
+    #
+    # @param string [String]
+    # @return [Option]
+    def self.from_string(string)
+      name, value = string.split(/\s|=/, 2)
+      new(name, value)
+    end
+
+    # Constructor
+    #
+    # @param name [String]
+    # @param optional value [String]
+    def initialize(name, value = nil)
+      @name = normalize_option(name)
+      @value = value
+    end
+
+    # Compares two options
+    #
+    # @param [Option]
+    # @return [Boolean]
+    def ==(other)
+      name == other.name
+    end
+    alias eql? ==
+
+    # Returns the option's hash
+    #
+    # @return [Fixnum]
+    def hash
+      name.hash
+    end
+
+    # Returns the option as string following the "--<name>=<value>" format or
+    # the short "-n=value" format
+    #
+    # @return [String]
+    def to_s
+      "#{name}#{value_as_string}"
+    end
+
+    private
+
+    # Returns the option name in "long" format, e.g., "--name"
+    #
+    # @return [String]
+    def normalize_option(name)
+      if name.start_with?('-')
+        name
+      elsif name.length == 1
+        "-#{name}"
+      else
+        "--#{name}"
+      end
+    end
+
+    # Returns the value fragment of the option string if any value is specified
+    #
+    # @return [String]
+    def value_as_string
+      if value.nil?
+        ''
+      elsif value.include?('=')
+        " #{value}"
+      else
+        "=#{value}"
+      end
+    end
+  end
+end

data/lib/departure/rails_adapter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Departure
+  class RailsAdapter
+    extend Forwardable
+
+    class << self
+      def current_version
+        ActiveRecord::VERSION
+      end
+
+      def for_current
+        self.for(current_version)
+      end
+
+      def for(ar_version)
+        if ar_version::MAJOR >= 7 && ar_version::MINOR >= 2
+          V7_2_Adapter
+        else
+          BaseAdapter
+        end
+      end
+    end
+
+    class BaseAdapter
+      class << self
+        def register_integrations
+          require 'active_record/connection_adapters/percona_adapter'
+
+          ActiveSupport.on_load(:active_record) do
+            ActiveRecord::Migration.class_eval do
+              include Departure::Migration
+            end
+          end
+        end
+
+        # ActiveRecord::ConnectionAdapters::Mysql2Adapter
+        def create_connection_adapter(**config)
+          mysql2_adapter = ActiveRecord::Base.mysql2_connection(config)
+
+          connection_details = Departure::ConnectionDetails.new(config)
+          verbose = ActiveRecord::Migration.verbose
+          sanitizers = [
+            Departure::LogSanitizers::PasswordSanitizer.new(connection_details)
+          ]
+          percona_logger = Departure::LoggerFactory.build(sanitizers: sanitizers, verbose: verbose)
+          cli_generator = Departure::CliGenerator.new(connection_details)
+
+          runner = Departure::Runner.new(
+            percona_logger,
+            cli_generator,
+            mysql2_adapter
+          )
+
+          connection_options = { mysql_adapter: mysql2_adapter }
+
+          ActiveRecord::ConnectionAdapters::DepartureAdapter.new(
+            runner,
+            percona_logger,
+            connection_options,
+            config
+          )
+        end
+
+        def sql_column
+          ::ActiveRecord::ConnectionAdapters::DepartureAdapter::Column
+        end
+      end
+    end
+
+    class V7_2_Adapter < BaseAdapter # rubocop:disable Naming/ClassAndModuleCamelCase
+      class << self
+        def register_integrations
+          require 'active_record/connection_adapters/rails_7_2_departure_adapter'
+
+          ActiveSupport.on_load(:active_record) do
+            ActiveRecord::Migration.class_eval do
+              include Departure::Migration
+            end
+          end
+
+          ActiveRecord::ConnectionAdapters.register 'percona',
+                                                    'ActiveRecord::ConnectionAdapters::Rails72DepartureAdapter',
+                                                    'active_record/connection_adapters/rails_7_2_departure_adapter'
+        end
+
+        def create_connection_adapter(**config)
+          ActiveRecord::ConnectionAdapters::Rails72DepartureAdapter.new(config)
+        end
+
+        def sql_column
+          ::ActiveRecord::ConnectionAdapters::Rails72DepartureAdapter::Column
+        end
+      end
+    end
+  end
+end

data/lib/departure/railtie.rb

@@ -0,0 +1,21 @@
+require 'departure'
+require 'lhm' # It's our own Lhm adapter, not the gem
+require 'rails'
+
+module Departure
+  class Railtie < Rails::Railtie
+    railtie_name :departure
+
+    initializer 'departure.configure' do |app|
+      Departure.configure do |config|
+        config.tmp_path = app.paths['tmp'].first
+      end
+    end
+
+    config.after_initialize do
+      Departure.configure do |dc|
+        ActiveRecord::Migration.uses_departure = dc.enabled_by_default
+      end
+    end
+  end
+end

data/lib/departure/runner.rb

@@ -0,0 +1,75 @@
+require 'open3'
+
+module Departure
+  # It executes pt-online-schema-change commands in a new process and gets its
+  # output and status
+  class Runner
+    extend Forwardable
+
+    def_delegators :raw_connection, :execute, :escape, :close, :affected_rows
+
+    # Constructor
+    #
+    # @param logger [#say, #write]
+    # @param cli_generator [CliGenerator]
+    # @param mysql_adapter [ActiveRecord::ConnectionAdapter] it must implement
+    #   #execute and #raw_connection
+    def initialize(logger, cli_generator, mysql_adapter, config = Departure.configuration)
+      @logger = logger
+      @cli_generator = cli_generator
+      @mysql_adapter = mysql_adapter
+      @error_log_path = config&.error_log_path
+      @redirect_stderr = config&.redirect_stderr
+    end
+
+    def database_adapter
+      @mysql_adapter
+    end
+
+    def raw_connection
+      database_adapter.raw_connection
+    end
+
+    # Executes the passed sql statement using pt-online-schema-change for ALTER
+    # TABLE statements, or the specified mysql adapter otherwise.
+    #
+    # @param sql [String]
+    def query(sql)
+      if alter_statement?(sql)
+        command_line = cli_generator.parse_statement(sql)
+        execute(command_line)
+      else
+        database_adapter.execute(sql)
+      end
+    end
+
+    # Returns the number of rows affected by the last UPDATE, DELETE or INSERT
+    # statements
+    #
+    # @return [Integer]
+    def affected_rows
+      raw_connection.affected_rows
+    end
+
+    # TODO: rename it so we don't confuse it with AR's #execute
+    # Runs and logs the given command
+    #
+    # @param command_line [String]
+    # @return [Boolean]
+    def execute(command_line)
+      Command.new(command_line, error_log_path, logger, redirect_stderr).run
+    end
+
+    private
+
+    attr_reader :logger, :cli_generator, :mysql_adapter, :error_log_path, :redirect_stderr
+
+    # Checks whether the sql statement is an ALTER TABLE
+    #
+    # @param sql [String]
+    # @return [Boolean]
+    def alter_statement?(sql)
+      sql =~ /\Aalter table/i
+    end
+  end
+end

data/lib/departure/user_options.rb

@@ -0,0 +1,44 @@
+module Departure
+  # Encapsulates the pt-online-schema-change options defined by the user
+  class UserOptions
+    delegate :each, :merge, to: :to_set
+
+    # Constructor
+    #
+    # @param arguments [String]
+    def initialize(arguments = ENV['PERCONA_ARGS'])
+      @arguments = arguments
+    end
+
+    private
+
+    attr_reader :arguments
+
+    # Returns the arguments the user defined but without duplicates
+    #
+    # @return [Set]
+    def to_set
+      Set.new(user_options)
+    end
+
+    # Returns Option instances from the arguments the user specified, if any
+    #
+    # @return [Array]
+    def user_options
+      if arguments
+        build_options
+      else
+        []
+      end
+    end
+
+    # Builds Option instances from the user arguments
+    #
+    # @return [Array<Option>]
+    def build_options
+      arguments.split(/\s(?=-)/).map do |argument|
+        Option.from_string(argument)
+      end
+    end
+  end
+end