fx 0.1.0 → 0.11.0

data/lib/fx/function.rb

@@ -1,23 +1,37 @@
 module Fx
   # @api private
   class Function
+    include Comparable
+
     attr_reader :name, :definition
-    delegate :<=>, to: :name
 
-    def initialize(function_row)
-      @name = function_row.fetch("name")
-      @definition = function_row.fetch("definition")
+    def initialize(row)
+      @name = row.fetch("name")
+      @definition = row.fetch("definition")
+      @arguments = row.fetch("arguments", nil)
+    end
+
+    def <=>(other)
+      signature <=> other.signature
     end
 
     def ==(other)
-      name == other.name && definition == other.definition
+      signature == other.signature && definition == other.definition
+    end
+
+    def signature
+      if @arguments.nil?
+        name
+      else
+        "#{name}(#{@arguments})"
+      end
     end
 
     def to_schema
-      <<-SCHEMA.indent(2)
-create_function :#{name}, sql_definition: <<-\SQL
-#{definition.indent(4).rstrip}
-SQL
+      <<~SCHEMA.indent(2)
+        create_function :#{name}, sql_definition: <<-'SQL'
+        #{definition.indent(4).rstrip}
+        SQL
       SCHEMA
     end
   end

data/lib/fx/railtie.rb

@@ -0,0 +1,15 @@
+require "rails/railtie"
+
+module Fx
+  # Automatically initializes Fx in the context of a Rails application when
+  # ActiveRecord is loaded.
+  #
+  # @see Fx.load
+  class Railtie < Rails::Railtie
+    initializer "fx.load" do
+      ActiveSupport.on_load :active_record do
+        Fx.load
+      end
+    end
+  end
+end

data/lib/fx/schema_dumper.rb

@@ -1,15 +1,38 @@
-require "fx/schema_dumper/function"
-require "fx/schema_dumper/trigger"
-
 module Fx
   # @api private
   module SchemaDumper
-    include Function
-    include Trigger
+    def tables(stream)
+      if Fx.configuration.dump_functions_at_beginning_of_schema
+        functions(stream)
+      end
+
+      super
+
+      unless Fx.configuration.dump_functions_at_beginning_of_schema
+        functions(stream)
+      end
+
+      triggers(stream)
+    end
+
+    private
+
+    def functions(stream)
+      dumpable_functions_in_database = Fx.database.functions
+
+      dumpable_functions_in_database.each do |function|
+        stream.puts
+        stream.puts(function.to_schema)
+      end
+    end
+
+    def triggers(stream)
+      dumpable_triggers_in_database = Fx.database.triggers
+
+      dumpable_triggers_in_database.each do |trigger|
+        stream.puts
+        stream.puts(trigger.to_schema)
+      end
+    end
   end
 end
-
-ActiveRecord::SchemaDumper.send(
-  :prepend,
-  Fx::SchemaDumper,
-)

data/lib/fx/statements.rb

@@ -1,16 +1,218 @@
-require "rails"
-require "fx/statements/function"
-require "fx/statements/trigger"
-
 module Fx
   # @api private
   module Statements
-    include Function
-    include Trigger
+    # Create a new database function.
+    #
+    # @param name [String, Symbol] The name of the database function.
+    # @param version [Integer] The version number of the function, used to
+    #   find the definition file in `db/functions`. This defaults to `1` if
+    #   not provided.
+    # @param sql_definition [String] The SQL query for the function schema.
+    #   If both `sql_definition` and `version` are provided,
+    #   `sql_definition` takes precedence.
+    # @return [void] The database response from executing the create statement.
+    #
+    # @example Create from `db/functions/uppercase_users_name_v02.sql`
+    #   create_function(:uppercase_users_name, version: 2)
+    #
+    # @example Create from provided SQL string
+    #   create_function(:uppercase_users_name, sql_definition: <<~SQL)
+    #     CREATE OR REPLACE FUNCTION uppercase_users_name()
+    #     RETURNS trigger AS $$
+    #     BEGIN
+    #       NEW.upper_name = UPPER(NEW.name);
+    #       RETURN NEW;
+    #     END;
+    #     $$ LANGUAGE plpgsql;
+    #   SQL
+    #
+    def create_function(name, version: 1, sql_definition: nil, revert_to_version: nil)
+      validate_version_or_sql_definition_present!(version, sql_definition)
+      sql_definition = resolve_sql_definition(sql_definition, name, version, :function)
+
+      Fx.database.create_function(sql_definition)
+    end
+
+    # Drop a database function by name.
+    #
+    # @param name [String, Symbol] The name of the database function.
+    # @param revert_to_version [Integer] Used to reverse the `drop_function`
+    #   command on `rake db:rollback`. The provided version will be passed as
+    #   the `version` argument to {#create_function}.
+    # @return [void] The database response from executing the drop statement.
+    #
+    # @example Drop a function, rolling back to version 2 on rollback
+    #   drop_function(:uppercase_users_name, revert_to_version: 2)
+    #
+    def drop_function(name, revert_to_version: nil)
+      Fx.database.drop_function(name)
+    end
+
+    # Update a database function.
+    #
+    # @param name [String, Symbol] The name of the database function.
+    # @param version [Integer] The version number of the function, used to
+    #   find the definition file in `db/functions`. This defaults to `1` if
+    #   not provided.
+    # @param sql_definition [String] The SQL query for the function schema.
+    #   If both `sql_definition` and `version` are provided,
+    #   `sql_definition` takes precedence.
+    # @return [void] The database response from executing the create statement.
+    #
+    # @example Update function to a given version
+    #   update_function(
+    #     :uppercase_users_name,
+    #     version: 3,
+    #     revert_to_version: 2,
+    #   )
+    #
+    # @example Update function from provided SQL string
+    #   update_function(:uppercase_users_name, sql_definition: <<~SQL)
+    #     CREATE OR REPLACE FUNCTION uppercase_users_name()
+    #     RETURNS trigger AS $$
+    #     BEGIN
+    #       NEW.upper_name = UPPER(NEW.name);
+    #       RETURN NEW;
+    #     END;
+    #     $$ LANGUAGE plpgsql;
+    #   SQL
+    #
+    def update_function(name, version: nil, sql_definition: nil, revert_to_version: nil)
+      validate_version_or_sql_definition_present!(version, sql_definition)
+
+      sql_definition = resolve_sql_definition(sql_definition, name, version, :function)
+
+      Fx.database.update_function(name, sql_definition)
+    end
+
+    # Create a new database trigger.
+    #
+    # @param name [String, Symbol] The name of the database trigger.
+    # @param version [Integer] The version number of the trigger, used to
+    #   find the definition file in `db/triggers`. This defaults to `1` if
+    #   not provided.
+    # @param sql_definition [String] The SQL query for the function. An error
+    #   will be raised if `sql_definition` and `version` are both set,
+    #   as they are mutually exclusive.
+    # @return [void] The database response from executing the create statement.
+    #
+    # @example Create trigger from `db/triggers/uppercase_users_name_v01.sql`
+    #   create_trigger(:uppercase_users_name, version: 1)
+    #
+    # @example Create trigger from provided SQL string
+    #   create_trigger(:uppercase_users_name, sql_definition: <<~SQL)
+    #     CREATE TRIGGER uppercase_users_name
+    #         BEFORE INSERT ON users
+    #         FOR EACH ROW
+    #         EXECUTE FUNCTION uppercase_users_name();
+    #    SQL
+    #
+    def create_trigger(name, version: nil, sql_definition: nil, on: nil, revert_to_version: nil)
+      validate_version_and_sql_definition_exclusive!(version, sql_definition)
+
+      version ||= 1
+
+      sql_definition = resolve_sql_definition(sql_definition, name, version, :trigger)
+
+      Fx.database.create_trigger(sql_definition)
+    end
+
+    # Drop a database trigger by name.
+    #
+    # @param name [String, Symbol] The name of the database trigger.
+    # @param on [String, Symbol] The name of the table the database trigger
+    #   is associated with.
+    # @param revert_to_version [Integer] Used to reverse the `drop_trigger`
+    #   command on `rake db:rollback`. The provided version will be passed as
+    #   the `version` argument to {#create_trigger}.
+    # @return [void] The database response from executing the drop statement.
+    #
+    # @example Drop a trigger, rolling back to version 3 on rollback
+    #   drop_trigger(:log_inserts, on: :users, revert_to_version: 3)
+    #
+    def drop_trigger(name, on:, revert_to_version: nil)
+      Fx.database.drop_trigger(name, on: on)
+    end
+
+    # Update a database trigger to a new version.
+    #
+    # The existing trigger is dropped and recreated using the supplied `on`
+    # and `version` parameter.
+    #
+    # @param name [String, Symbol] The name of the database trigger.
+    # @param version [Integer] The version number of the trigger.
+    # @param on [String, Symbol] The name of the table the database trigger
+    #   is associated with.
+    # @param sql_definition [String] The SQL query for the function. An error
+    #   will be raised if `sql_definition` and `version` are both set,
+    #   as they are mutually exclusive.
+    # @param revert_to_version [Integer] The version number to rollback to on
+    #   `rake db rollback`
+    # @return [void] The database response from executing the create statement.
+    #
+    # @example Update trigger to a given version
+    #   update_trigger(
+    #     :log_inserts,
+    #     on: :users,
+    #     version: 3,
+    #     revert_to_version: 2,
+    #   )
+    #
+    # @example Update trigger from provided SQL string
+    #   update_trigger(:uppercase_users_name, sql_definition: <<~SQL)
+    #     CREATE TRIGGER uppercase_users_name
+    #         BEFORE INSERT ON users
+    #         FOR EACH ROW
+    #         EXECUTE FUNCTION uppercase_users_name();
+    #    SQL
+    #
+    def update_trigger(name, on:, version: nil, sql_definition: nil, revert_to_version: nil)
+      validate_version_or_sql_definition_present!(version, sql_definition)
+      validate_version_and_sql_definition_exclusive!(version, sql_definition)
+
+      sql_definition = resolve_sql_definition(sql_definition, name, version, :trigger)
+
+      Fx.database.update_trigger(
+        name,
+        on: on,
+        sql_definition: sql_definition
+      )
+    end
+
+    private
+
+    VERSION_OR_SQL_DEFINITION_REQUIRED = "version or sql_definition must be specified".freeze
+    private_constant :VERSION_OR_SQL_DEFINITION_REQUIRED
+
+    VERSION_AND_SQL_DEFINITION_EXCLUSIVE = "sql_definition and version cannot both be set".freeze
+    private_constant :VERSION_AND_SQL_DEFINITION_EXCLUSIVE
+
+    def validate_version_or_sql_definition_present!(version, sql_definition)
+      if version.nil? && sql_definition.nil?
+        raise ArgumentError, VERSION_OR_SQL_DEFINITION_REQUIRED, caller
+      end
+    end
+
+    def validate_version_and_sql_definition_exclusive!(version, sql_definition)
+      if version.present? && sql_definition.present?
+        raise ArgumentError, VERSION_AND_SQL_DEFINITION_EXCLUSIVE, caller
+      end
+    end
+
+    def resolve_sql_definition(sql_definition, name, version, type)
+      return sql_definition.strip_heredoc if sql_definition
+
+      definition =
+        case type
+        when :function
+          Fx::Definition.function(name: name, version: version)
+        when :trigger
+          Fx::Definition.trigger(name: name, version: version)
+        else
+          raise ArgumentError, "Unknown type: #{type}. Must be :function or :trigger", caller
+        end
+
+      definition.to_sql
+    end
   end
 end
-
-ActiveRecord::ConnectionAdapters::AbstractAdapter.send(
-  :include,
-  Fx::Statements,
-)

data/lib/fx/trigger.rb

@@ -1,12 +1,14 @@
 module Fx
   # @api private
   class Trigger
+    include Comparable
+
     attr_reader :name, :definition
     delegate :<=>, to: :name
 
-    def initialize(function_row)
-      @name = function_row.fetch("name")
-      @definition = function_row.fetch("definition")
+    def initialize(row)
+      @name = row.fetch("name")
+      @definition = row.fetch("definition")
     end
 
     def ==(other)

data/lib/fx/version.rb

@@ -1,4 +1,4 @@
 module Fx
   # @api private
-  VERSION = "0.1.0"
+  VERSION = "0.11.0"
 end

data/lib/fx.rb

@@ -1,3 +1,5 @@
+require "rails"
+
 require "fx/version"
 require "fx/adapters/postgres"
 require "fx/command_recorder"
@@ -7,10 +9,48 @@ require "fx/function"
 require "fx/statements"
 require "fx/schema_dumper"
 require "fx/trigger"
+require "fx/railtie"
 
 # F(x) adds methods `ActiveRecord::Migration` to create and manage database
 # triggers and functions in Rails applications.
 module Fx
+  # Hooks Fx into Rails.
+  #
+  # Enables fx migration methods, migration reversability, and `schema.rb`
+  # dumping.
+  def self.load
+    ActiveRecord::Migration::CommandRecorder.include(Fx::CommandRecorder)
+    ActiveRecord::ConnectionAdapters::AbstractAdapter.include(Fx::Statements)
+    ActiveRecord::SchemaDumper.prepend(Fx::SchemaDumper)
+
+    true
+  end
+
+  # @return [Fx::Configuration] F(x)'s current configuration
+  def self.configuration
+    @_configuration ||= Fx::Configuration.new
+  end
+
+  # Set F(x)'s configuration
+  #
+  # @param config [Fx::Configuration]
+  def self.configuration=(config)
+    @_configuration = config
+  end
+
+  # Modify F(x)'s current configuration
+  #
+  # @yieldparam [Fx::Configuration] config current F(x) config
+  # ```
+  # Fx.configure do |config|
+  #   config.database = Fx::Adapters::Postgres
+  #   config.dump_functions_at_beginning_of_schema = true
+  # end
+  # ```
+  def self.configure
+    yield configuration
+  end
+
   # The current database adapter used by F(x).
   #
   # This defaults to {Fx::Adapters::Postgres} but can be overridden

data/lib/generators/fx/function/USAGE

@@ -2,6 +2,8 @@ Description:
   Create a new database function for your application. This will create a new
   function definition file and the accompanying migration.
 
+  When --no-migration is passed, skips generating a migration.
+
 Examples:
     rails generate fx:function test
 

data/lib/generators/fx/function/function_generator.rb

@@ -1,39 +1,49 @@
 require "rails/generators"
 require "rails/generators/active_record"
+require "generators/fx/version_helper"
+require "generators/fx/migration_helper"
+require "generators/fx/name_helper"
 
 module Fx
   module Generators
     # @api private
     class FunctionGenerator < Rails::Generators::NamedBase
       include Rails::Generators::Migration
+
       source_root File.expand_path("../templates", __FILE__)
 
+      DEFINITION_PATH = %w[db functions].freeze
+
+      class_option :migration, type: :boolean
+
       def create_functions_directory
-        unless function_definition_path.exist?
-          empty_directory(function_definition_path)
-        end
+        return if function_definition_path.exist?
+
+        empty_directory(function_definition_path)
       end
 
       def create_function_definition
-        if creating_new_function?
-          create_file definition.path
+        if version_helper.creating_new?
+          create_file(definition.path)
         else
-          copy_file previous_definition.full_path, definition.full_path
+          copy_file(previous_definition.full_path, definition.full_path)
         end
       end
 
       def create_migration_file
-        if updating_existing_function?
-          migration_template(
-            "db/migrate/update_function.erb",
-            "db/migrate/update_function_#{file_name}_to_version_#{version}.rb",
-          )
-        else
-          migration_template(
-            "db/migrate/create_function.erb",
-            "db/migrate/create_function_#{file_name}.rb",
-          )
-        end
+        return if migration_helper.skip_creation?
+
+        template_info = migration_helper.migration_template_info(
+          object_type: :function,
+          file_name: file_name,
+          updating_existing: version_helper.updating_existing?,
+          version: version_helper.current_version
+        )
+
+        migration_template(
+          template_info.fetch(:template),
+          template_info.fetch(:filename)
+        )
       end
 
       def self.next_migration_number(dir)
@@ -42,56 +52,61 @@ module Fx
 
       no_tasks do
         def previous_version
-          @_previous_version ||= Dir.entries(function_definition_path).
-            map { |name| version_regex.match(name).try(:[], "version").to_i }.
-            max
+          version_helper.previous_version
         end
 
         def version
-          @_version ||= previous_version.next
+          version_helper.current_version
         end
 
         def migration_class_name
-          if updating_existing_function?
-            "UpdateFunction#{class_name}ToVersion#{version}"
+          if version_helper.updating_existing?
+            migration_helper.update_migration_class_name(
+              object_type: :function,
+              class_name: class_name,
+              version: version
+            )
           else
             super
           end
         end
 
         def formatted_name
-          if singular_name.include?(".")
-            "\"#{singular_name}\""
-          else
-            ":#{singular_name}"
-          end
+          Fx::Generators::NameHelper.format_for_migration(singular_name)
         end
       end
 
       private
 
       def function_definition_path
-        @_function_definition_path ||= Rails.root.join(*%w(db functions))
+        @_function_definition_path ||= Rails.root.join(*DEFINITION_PATH)
       end
 
-      def version_regex
-        /\A#{file_name}_v(?<version>\d+)\.sql\z/
+      def version_helper
+        @_version_helper ||= Fx::Generators::VersionHelper.new(
+          file_name: file_name,
+          definition_path: function_definition_path
+        )
       end
 
-      def updating_existing_function?
-        previous_version > 0
-      end
-
-      def creating_new_function?
-        previous_version == 0
+      def migration_helper
+        @_migration_helper ||= Fx::Generators::MigrationHelper.new(options)
       end
 
       def definition
-        Fx::Definition.new(name: file_name, version: version)
+        version_helper.definition_for_version(version: version, type: :function)
       end
 
       def previous_definition
-        Fx::Definition.new(name: file_name, version: previous_version)
+        version_helper.definition_for_version(version: previous_version, type: :function)
+      end
+
+      def updating_existing_function?
+        version_helper.updating_existing?
+      end
+
+      def creating_new_function?
+        version_helper.creating_new?
       end
     end
   end

data/lib/generators/fx/function/templates/db/migrate/create_function.erb

@@ -1,4 +1,4 @@
-class <%= migration_class_name %> < ActiveRecord::Migration
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_function <%= formatted_name %>
   end

data/lib/generators/fx/function/templates/db/migrate/update_function.erb

@@ -1,4 +1,4 @@
-class <%= migration_class_name %> < ActiveRecord::Migration
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     update_function <%= formatted_name %>, version: <%= version %>, revert_to_version: <%= previous_version %>
   end

data/lib/generators/fx/migration_helper.rb

@@ -0,0 +1,45 @@
+module Fx
+  module Generators
+    # @api private
+    class MigrationHelper
+      def initialize(options)
+        @options = options
+      end
+
+      def skip_creation?
+        !should_create_migration?
+      end
+
+      def update_migration_class_name(object_type:, class_name:, version:)
+        "Update#{object_type.capitalize}#{class_name}ToVersion#{version}"
+      end
+
+      def migration_template_info(
+        object_type:,
+        file_name:,
+        updating_existing:,
+        version:
+      )
+        if updating_existing
+          {
+            template: "db/migrate/update_#{object_type}.erb",
+            filename: "db/migrate/update_#{object_type}_#{file_name}_to_version_#{version}.rb"
+          }
+        else
+          {
+            template: "db/migrate/create_#{object_type}.erb",
+            filename: "db/migrate/create_#{object_type}_#{file_name}.rb"
+          }
+        end
+      end
+
+      private
+
+      attr_reader :options
+
+      def should_create_migration?
+        options.fetch(:migration, true)
+      end
+    end
+  end
+end

data/lib/generators/fx/name_helper.rb

@@ -0,0 +1,33 @@
+module Fx
+  module Generators
+    # @api private
+    class NameHelper
+      def self.format_for_migration(name)
+        if name.include?(".")
+          "\"#{name}\""
+        else
+          ":#{name}"
+        end
+      end
+
+      def self.format_table_name_from_hash(table_hash)
+        name = table_hash["table_name"] || table_hash["on"]
+
+        if name.nil?
+          raise(
+            ArgumentError,
+            "Either `table_name:NAME` or `on:NAME` must be specified"
+          )
+        end
+
+        format_for_migration(name)
+      end
+
+      def self.validate_and_format(name)
+        raise ArgumentError, "Name cannot be blank" if name.blank?
+
+        format_for_migration(name)
+      end
+    end
+  end
+end

data/lib/generators/fx/trigger/USAGE

@@ -5,6 +5,8 @@ Description:
   If a trigger of the given name already exists, create a new version of the
   trigger and a migration to replace the old version with the new.
 
+  When --no-migration is passed, skips generating a migration.
+
 Examples:
 
     rails generate fx:trigger test