arfi 0.4.0 → 0.5.0

data/lib/arfi/commands/f_idx.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'rails'
+require File.expand_path('config/environment', Dir.pwd)
+
+module Arfi
+  module Commands
+    # +Arfi::Commands::FIdx+ module contains commands for manipulating functional index in Rails project.
+    class FIdx < Thor
+      ADAPTERS = %i[postgresql mysql].freeze
+
+      # steep:ignore:start
+      desc 'create FUNCTION_NAME [--template=template_file --adapter=adapter]', 'Initialize the functional index'
+      option :template, type: :string, banner: 'template_file',
+                        desc: 'Path to the template file. See `README.md` for details.'
+      option :adapter, type: :string,
+                       desc: 'Specify database adapter, used for projects with multiple database architecture. ' \
+                             "Available adapters: #{ADAPTERS.join(', ')}",
+                       banner: 'adapter'
+      # steep:ignore:end
+
+      # +Arfi::Commands::FIdx#create+                        -> void
+      #
+      # This command is used to create the functional index.
+      #
+      # @example
+      #   bundle exec arfi f_idx create some_function
+      #
+      # ARFI also supports the use of custom templates for SQL functions, but now there are some restrictions and rules
+      # according to which it is necessary to describe the function. First, the function must be written in a
+      # Ruby-compatible syntax: the file name is not so important, but the name for the function name must be
+      # interpolated with the +index_name+ variable name, and the function itself must be placed in the HEREDOC
+      # statement. Below is an example file.
+      #
+      # @example
+      #   # ./template/my_custom_template
+      #   <<~SQL
+      #   CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
+      #     LANGUAGE SQL
+      #     IMMUTABLE AS
+      #   $$
+      #     -- Function body here
+      #   $$
+      #   SQL
+      #
+      # To use a custom template, add the --template flag.
+      #
+      # @example
+      #   bundle exec arfi f_idx create some_function --template ./template/my_custom_template
+      #
+      # @param index_name [String] Name of the index.
+      # @return [void]
+      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby
+      # @raise [Arfi::Errors::NoFunctionsDir] if there is no `db/functions` directory
+      # @see Arfi::Commands::FIdx#validate_schema_format!
+      def create(index_name)
+        validate_schema_format!
+        content = build_sql_function(index_name)
+        create_function_file(index_name, content)
+      end
+
+      # steep:ignore:start
+      desc 'destroy INDEX_NAME [--revision=revision --adapter=adapter]', 'Delete the functional index.'
+      option :revision, type: :string, banner: 'revision', desc: 'Revision of the function.'
+      option :adapter, type: :string,
+                       desc: 'Specify database adapter, used for projects with multiple database architecture. ' \
+                             "Available adapters: #{ADAPTERS.join(', ')}",
+                       banner: 'adapter'
+      # steep:ignore:end
+
+      # +Arfi::Commands::FIdx#destroy+                        -> void
+      #
+      # This command is used to delete the functional index.
+      #
+      # @example
+      #   bundle exec arfi f_idx destroy some_function [revision index (just an integer, 1 is by default)]
+      # @param index_name [String] Name of the index.
+      # @return [void]
+      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby
+      def destroy(index_name)
+        validate_schema_format!
+
+        revision = Integer(options[:revision] || '01') # steep:ignore NoMethod
+        revision = "0#{revision}"
+        FileUtils.rm("#{functions_dir}/#{index_name}_v#{revision}.sql")
+        puts "Deleted: #{functions_dir}/#{index_name}_v#{revision}.sql"
+      end
+
+      private
+
+      # +Arfi::Commands::FIdx#validate_schema_format!+                        -> void
+      #
+      # Helper method to validate the schema format.
+      #
+      # @!visibility private
+      # @private
+      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby.
+      # @return [nil] if the schema format is valid.
+      def validate_schema_format!
+        raise Arfi::Errors::InvalidSchemaFormat unless ActiveRecord.schema_format == :ruby # steep:ignore NoMethod
+      end
+
+      # +Arfi::Commands::FIdx#build_sql_function+                        -> String
+      #
+      # Helper method to build the SQL function.
+      #
+      # @!visibility private
+      # @private
+      # @param index_name [String] Name of the index.
+      # @return [String] SQL function body.
+      def build_sql_function(index_name) # rubocop:disable Metrics/MethodLength
+        return build_from_file(index_name) if options[:template] # steep:ignore NoMethod
+
+        unless options[:adapter] # steep:ignore NoMethod
+          return <<~SQL
+            CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
+                LANGUAGE SQL
+                IMMUTABLE AS
+            $$
+                -- Function body here
+            $$
+          SQL
+        end
+
+        case options[:adapter] # steep:ignore NoMethod
+        when 'postgresql'
+          <<~SQL
+            CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
+                LANGUAGE SQL
+                IMMUTABLE AS
+            $$
+                -- Function body here
+            $$
+          SQL
+        when 'mysql'
+          <<~SQL
+            CREATE FUNCTION #{index_name} ()
+            RETURNS return_type
+            BEGIN
+              -- Function body here
+            END;
+          SQL
+        else
+          # steep:ignore:start
+          raise "Unknown adapter: #{options[:adapter]}. Supported adapters: #{ADAPTERS.join(', ')}"
+          # steep:ignore:end
+        end
+      end
+
+      # +Arfi::Commands::FIdx#build_from_file+                          -> String
+      #
+      # Helper method to build the SQL function. Used with flag `--template`.
+      #
+      # @!visibility private
+      # @private
+      # @param index_name [String] Name of the index.
+      # @return [String] SQL function body.
+      # @see Arfi::Commands::FIdx#create
+      # @see Arfi::Commands::FIdx#build_sql_function
+      def build_from_file(index_name)
+        # steep:ignore:start
+        RubyVM::InstructionSequence.compile("index_name = '#{index_name}'; #{File.read(options[:template])}").eval
+        # steep:ignore:end
+      end
+
+      # +Arfi::Commands::FIdx#create_function_file+                        -> void
+      #
+      # Helper method to create the index file.
+      #
+      # @!visibility private
+      # @private
+      # @param index_name [String] Name of the index.
+      # @param content [String] SQL function body.
+      # @return [void]
+      def create_function_file(index_name, content)
+        existing_files = Dir.glob("#{functions_dir}/#{index_name}*.sql")
+
+        return write_file(index_name, content, 1) if existing_files.empty?
+
+        latest_version = extract_latest_version(existing_files)
+        write_file(index_name, content, latest_version.succ)
+      end
+
+      # +Arfi::Commands::FIdx#extract_latest_version+                        -> Integer
+      #
+      # Helper method to extract the latest version of the index.
+      #
+      # @!visibility private
+      # @private
+      # @param files [Array<String>] List of files.
+      # @return [String] Latest version of the index.
+      def extract_latest_version(files)
+        version_numbers = files.map do |file|
+          File.basename(file)[/\w+_v(\d+)\.sql/, 1]
+        end.compact
+
+        version_numbers.max
+      end
+
+      # +Arfi::Commands::FIdx#write_file+                        -> void
+      #
+      # Helper method to write the index file.
+      #
+      # @!visibility private
+      # @private
+      # @param index_name [String] Name of the index.
+      # @param content [String] SQL function body.
+      # @param version [String|Integer] Version of the index.
+      # @return [void]
+      def write_file(index_name, content, version)
+        version_str = format('%02d', version)
+        path = "#{functions_dir}/#{index_name}_v#{version_str}.sql"
+        File.write(path, content.to_s)
+        puts "Created: #{path}"
+      end
+
+      # +Arfi::Commands::FIdx#functions_dir+                        -> Pathname
+      #
+      # Helper method to get path to `db/functions` directory.
+      #
+      # @!visibility private
+      # @private
+      # @return [Pathname] Path to `db/functions` directory
+      def functions_dir
+        # steep:ignore:start
+        if options[:adapter]
+          raise Arfi::Errors::AdapterNotSupported unless ADAPTERS.include?(options[:adapter].to_sym)
+
+          Rails.root.join("db/functions/#{options[:adapter]}")
+          # steep:ignore:end
+        else
+          Rails.root.join('db/functions')
+        end
+      end
+    end
+  end
+end

data/lib/arfi/commands/project.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'fileutils'
+require 'rails'
+
+module Arfi
+  module Commands
+    # +Arfi::Commands::Project+ class is used to create `db/functions` directory.
+    class Project < Thor
+      ADAPTERS = %i[postgresql mysql].freeze
+
+      # steep:ignore:start
+      desc 'create', 'Initialize project by creating db/functions directory'
+      option :adapter, type: :string,
+                       desc: 'Specify database adapter, used for projects with multiple database architecture. ' \
+                             "Available adapters: #{ADAPTERS.join(', ')}",
+                       banner: 'adapter'
+      # steep:ignore:end
+
+      # +Arfi::Commands::Project#create+                 -> void
+      #
+      # This command is used to create `db/functions` directory.
+      #
+      # @example
+      #   bundle exec arfi project create
+      # @return [void]
+      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby.
+      def create
+        raise Arfi::Errors::InvalidSchemaFormat unless ActiveRecord.schema_format == :ruby # steep:ignore NoMethod
+        return puts "Directory #{functions_dir} already exists" if Dir.exist?(functions_dir)
+
+        FileUtils.mkdir_p(functions_dir)
+        puts "Created: #{functions_dir}"
+      end
+
+      private
+
+      # +Arfi::Commands::Project#functions_dir+          -> Pathname
+      #
+      # Helper method to get path to `db/functions` directory.
+      #
+      # @!visibility private
+      # @private
+      # @return [Pathname] Path to `db/functions` directory
+      def functions_dir
+        # steep:ignore:start
+        if options[:adapter]
+          raise Arfi::Errors::AdapterNotSupported unless ADAPTERS.include?(options[:adapter].to_sym)
+
+          Rails.root.join("db/functions/#{options[:adapter]}")
+          # steep:ignore:end
+        else
+          Rails.root.join('db/functions')
+        end
+      end
+    end
+  end
+end

data/lib/arfi/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Arfi
+  module Errors
+    # This error is raised when there is no `db/functions` directory
+    class NoFunctionsDir < StandardError
+      def initialize(message =
+                       'There is no such directory: db/functions. Did you run `bundle exec arfi project:create`?')
+        @message = message
+        super
+      end
+    end
+
+    # This error is raised when Rails project schema format is not +schema.rb+
+    class InvalidSchemaFormat < StandardError
+      def initialize(message = 'Invalid schema format. ARFI supports only ruby format schemas.')
+        @message = message
+        super
+      end
+    end
+
+    # This error is raised when database adapter is not supported (for e.g., SQLite3).
+    class AdapterNotSupported < StandardError
+      def initialize(message = 'Adapter not supported')
+        @message = message
+        super
+      end
+    end
+  end
+end

data/lib/arfi/extensions/active_record/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'active_record'
+
+module ActiveRecord
+  class Base # :nodoc:
+    # +ActiveRecord::Base.function_exists?+               -> bool
+    #
+    # This method checks if a custom SQL function exists in the database.
+    #
+    # @example
+    #   ActiveRecord::Base.function_exists?('my_function') #=> true
+    #   ActiveRecord::Base.function_exists?('my_function123') #=> false
+    # @param [String] function_name The name of the function to check.
+    # @return [Boolean] Returns true if the function exists, false otherwise.
+    def self.function_exists?(function_name) # rubocop:disable Metrics/MethodLength
+      case connection
+      when ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+        connection.execute("SELECT * FROM pg_proc WHERE proname = '#{function_name}'").any?
+      when ActiveRecord::ConnectionAdapters::Mysql2Adapter
+        sql = <<~SQL
+          SELECT 1
+          FROM information_schema.ROUTINES
+          WHERE ROUTINE_TYPE = 'FUNCTION'
+            AND ROUTINE_SCHEMA = '#{connection.current_database}'
+            AND ROUTINE_NAME = '#{function_name}'
+          LIMIT 1;
+        SQL
+
+        !!connection.execute(sql).first
+      else
+        raise ActiveRecord::AdapterNotFound, "adapter #{connection.class.name} is not supported"
+      end
+    end
+  end
+end

data/lib/arfi/extensions/active_record/connection_adapters/postgresql/database_statements.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'active_record/connection_adapters/postgresql/database_statements'
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostgreSQL
+      module DatabaseStatements
+        # This patch is used for db:prepare task.
+        def raw_execute(sql, name, async: false, allow_retry: false, materialize_transactions: true)
+          log(sql, name, async: async) do |notification_payload|
+            with_raw_connection(allow_retry: allow_retry, materialize_transactions: materialize_transactions) do |conn|
+              result = conn.async_exec(sql)
+              verified!
+              handle_warnings(result)
+              notification_payload[:row_count] = result.count
+              result
+            rescue => e
+              if e.message.match?(/ERROR:\s{2}function (\S+\(\w+\)) does not exist/)
+                function_name = e.message.match(/ERROR:\s{2}function (\S+\(\w+\)) does not exist/)[1][/^[^(]*/]
+                if (function_file = Dir.glob(Rails.root.join('db', 'functions', "#{function_name}_v*.sql").to_s).first)
+                  conn.async_exec(File.read(function_file).chop)
+                  retry
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/arfi/extensions/extensions.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_record/schema'
+require 'arfi/sql_function_loader'
+require_relative 'active_record/base'
+require_relative 'active_record/connection_adapters/postgresql/database_statements'

data/lib/arfi/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'arfi'
+require 'rails'
+
+module Arfi
+  class Railtie < ::Rails::Railtie # :nodoc:
+    railtie_name :arfi
+
+    rake_tasks do
+      path = File.expand_path(__dir__ || '.')
+      Dir.glob("#{path}/tasks/**/*.rake").each { |f| load f }
+    end
+  end
+end

data/lib/arfi/sql_function_loader.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Arfi
+  # +Arfi::SqlFunctionLoader+ is a class which loads user defined SQL functions into database.
+  class SqlFunctionLoader
+    class << self
+      # +Arfi::SqlFunctionLoader.load!+                        -> (nil | void)
+      #
+      # Loads user defined SQL functions into database.
+      #
+      # @param task_name [String|nil] Name of the task.
+      # @return [nil] if there is no `db/functions` directory.
+      # @return [void] if there is no errors.
+      def load!(task_name: nil)
+        self.task_name = task_name[/([^:]+$)/] if task_name
+        return puts 'No SQL files found. Skipping db population with ARFI' unless sql_files.any?
+
+        raise_unless_supported_adapter
+        handle_db_population
+        conn.close
+      end
+
+      private
+
+      attr_accessor :task_name
+
+      # +Arfi::SqlFunctionLoader#raise_unless_supported_adapter+ -> void
+      #
+      # Checks if the database adapter is supported.
+      #
+      # @!visibility private
+      # @private
+      # @return [void]
+      # @raise [Arfi::Errors::AdapterNotSupported]
+      def raise_unless_supported_adapter
+        allowed = %w[ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+                     ActiveRecord::ConnectionAdapters::Mysql2Adapter].freeze
+        return if allowed.include?(conn.class.to_s) # steep:ignore ArgumentTypeMismatch
+
+        raise Arfi::Errors::AdapterNotSupported
+      end
+
+      # +Arfi::SqlFunctionLoader#handle_db_population+         -> void
+      #
+      # Loads user defined SQL functions into database. This conditional branch was written this way because if we
+      # call db:migrate:db_name, then task_name will not be nil, but it will be zero if we call db:migrate. Then we
+      # check that the application has been configured to work with multiple databases in order to populate all
+      # databases, and only after this check can we populate the database in case the db:migrate (or any other) task
+      # has been called for configuration with a single database. Go to `lib/arfi/tasks/db.rake` for additional info.
+      #
+      # @!visibility private
+      # @private
+      # @return [void]
+      def handle_db_population
+        if task_name || (task_name && multi_db?) || task_name.nil?
+          populate_db
+        elsif multi_db?
+          populate_multiple_db
+        end
+      end
+
+      # +Arfi::SqlFunctionLoader#multi_db?+                       -> Boolean
+      #
+      # Checks if the application has been configured to work with multiple databases.
+      #
+      # @return [Boolean]
+      def multi_db?
+        ActiveRecord::Base.configurations.configurations.count { _1.env_name == Rails.env } > 1 # steep:ignore NoMethod
+      end
+
+      # +Arfi::SqlFunctionLoader#populate_multiple_db+          -> void
+      #
+      # Loads user defined SQL functions into all databases.
+      #
+      # @!visibility private
+      # @private
+      # @return [void]
+      # @see Arfi::SqlFunctionLoader#multi_db?
+      # @see Arfi::SqlFunctionLoader#populate_db
+      def populate_multiple_db
+        # steep:ignore:start
+        ActiveRecord::Base.configurations.configurations.select { _1.env_name == Rails.env }.each do |config|
+          ActiveRecord::Base.establish_connection(config)
+          populate_db
+        end
+        # steep:ignore:end
+      end
+
+      # +Arfi::SqlFunctionLoader#populate_db+                   -> void
+      #
+      # Loads user defined SQL functions into database.
+      #
+      # @!visibility private
+      # @private
+      # @return [void]
+      def populate_db
+        sql_files.each do |file|
+          sql = File.read(file).strip
+          conn.execute(sql)
+          puts "[ARFI] Loaded: #{File.basename(file)} into #{conn.pool.db_config.env_name} #{conn.pool.db_config.name}"
+        end
+      end
+
+      # +Arfi::SqlFunctionLoader#sql_files+                     -> Array<String>
+      #
+      # Helper method to get list of SQL files. Here we check if we need to populate all databases or just one.
+      #
+      # @!visibility private
+      # @private
+      # @return [Array<String>] List of SQL files.
+      # @see Arfi::SqlFunctionLoader#load!
+      # @see Arfi::SqlFunctionLoader#multi_db?
+      # @see Arfi::SqlFunctionLoader#sql_functions_by_adapter
+      def sql_files
+        if task_name || multi_db?
+          sql_functions_by_adapter
+        else
+          Dir.glob(Rails.root.join('db', 'functions').join('*.sql'))
+        end
+      end
+
+      # +Arfi::SqlFunctionLoader#sql_functions_by_adapter+      -> Array<String>
+      #
+      # Helper method to get list of SQL files for specific database adapter.
+      #
+      # @!visibility private
+      # @private
+      # @return [Array<String>] List of SQL files.
+      # @raise [Arfi::Errors::AdapterNotSupported] if database adapter is not supported.
+      def sql_functions_by_adapter
+        case conn
+        when ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+          Dir.glob(Rails.root.join('db', 'functions', 'postgresql').join('*.sql'))
+        when ActiveRecord::ConnectionAdapters::Mysql2Adapter
+          Dir.glob(Rails.root.join('db', 'functions', 'mysql').join('*.sql'))
+        else
+          raise Arfi::Errors::AdapterNotSupported
+        end
+      end
+
+      # +Arfi::SqlFunctionLoader#conn+                          -> ActiveRecord::ConnectionAdapters::AbstractAdapter
+      #
+      # Helper method to get database connection.
+      #
+      # @!visibility private
+      # @private
+      # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter] Database connection.
+      def conn
+        ActiveRecord::Base.lease_connection
+      end
+    end
+  end
+end

data/lib/arfi/tasks/db.rake

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'arfi/sql_function_loader'
+
+namespace :_db do
+  task :arfi_enhance do
+    Arfi::SqlFunctionLoader.load!
+  end
+end
+
+Rake::Task.define_task(:environment) unless Rake::Task.task_defined?(:environment)
+
+# Enhancing single db tasks
+%w[db:migrate db:schema:load db:setup].each do |task|
+  Rake::Task[task].enhance(['_db:arfi_enhance']) if Rake::Task.task_defined?(task)
+end
+
+# We remove user defined keys in database.yml and use only the ones about RDBMS connections.
+# Here we try to find tasks like db:migrate:your_db_name and enhance them as well as tasks for single db connections.
+rdbms_configs = Rails.configuration.database_configuration[Rails.env].select { |_k, v| v.is_a?(Hash) }.keys
+possible_tasks = Rake::Task.tasks.select do |task|
+  task.name.match?(/^(db:migrate:|db:schema:load:|db:setup:|db:prepare:|db:test:prepare:)(\w+)$/)
+end
+possible_tasks = possible_tasks.select do |task|
+  rdbms_configs.any? { |n| task.name.include?(n) }
+end
+
+# In general, this is a small trick due to the fact that Rake does not allow you to view parent tasks from a task that
+# was called for enhancing. Moreover, the utility does not provide for passing parameters to the called task.
+# To get around this limitation, we dynamically create a task with the name we need, and then pass this name as
+# an argument to the method.
+possible_tasks.each do |task|
+  Rake::Task.define_task("_db:arfi_enhance:#{task.name}") do
+    Arfi::SqlFunctionLoader.load!(task_name: task.name)
+  end
+  task.enhance(["_db:arfi_enhance:#{task.name}"])
+end

data/lib/arfi/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Arfi
+  VERSION = '0.5.0'
+end

data/lib/arfi.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'arfi/version'
+require_relative 'arfi/errors'
+require 'arfi/extensions/extensions'
+require 'rails' if defined?(Rails)
+
+# Top level module
+module Arfi
+  require_relative 'arfi/railtie' if defined?(Rails)
+end

data/rakelib/yard_docs_generator.rake

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'yard'
+
+# run as `rm -rf arfi_docs && bundle exec rake docs:generate && bundle exec rake docs:push`
+
+namespace :docs do
+  desc 'Generate new docs and push them repo'
+  task :generate do
+    puts 'Generating docs...'
+    args = %w[--no-cache --private --protected --readme README.md --no-progress --output-dir doc]
+    YARD::CLI::Yardoc.run(*args)
+    puts 'Docs generated'
+  end
+
+  desc 'Push docs to repo'
+  task :push do
+    puts 'Copying docs...'
+    `git clone git@github.com:unurgunite/arfi_docs.git`
+    Dir.chdir('arfi_docs') do
+      cp_r('../doc/.', '.', remove_destination: true)
+      `git add .`
+      `git commit -m "Update docs #{Time.now.utc}"`
+      `git push`
+    end
+    rm_rf('arfi_docs')
+    puts 'Docs pushed'
+  end
+end