fx 0.8.0 → 0.10.0

data/lib/fx/command_recorder.rb

@@ -1,12 +1,53 @@
-require "fx/command_recorder/arguments"
-require "fx/command_recorder/function"
-require "fx/command_recorder/trigger"
-
 module Fx
   # @api private
   module CommandRecorder
-    include Function
-    include Trigger
+    def create_function(*args)
+      record(:create_function, args)
+    end
+
+    def drop_function(*args)
+      record(:drop_function, args)
+    end
+
+    def update_function(*args)
+      record(:update_function, args)
+    end
+
+    def invert_create_function(args)
+      [:drop_function, args]
+    end
+
+    def invert_drop_function(args)
+      perform_inversion(:create_function, args)
+    end
+
+    def invert_update_function(args)
+      perform_inversion(:update_function, args)
+    end
+
+    def create_trigger(*args)
+      record(:create_trigger, args)
+    end
+
+    def drop_trigger(*args)
+      record(:drop_trigger, args)
+    end
+
+    def update_trigger(*args)
+      record(:update_trigger, args)
+    end
+
+    def invert_create_trigger(args)
+      [:drop_trigger, args]
+    end
+
+    def invert_drop_trigger(args)
+      perform_inversion(:create_trigger, args)
+    end
+
+    def invert_update_trigger(args)
+      perform_inversion(:update_trigger, args)
+    end
 
     private
 
@@ -20,5 +61,45 @@ module Fx
 
       [method, arguments.invert_version.to_a]
     end
+
+    class Arguments
+      def initialize(args)
+        @args = args.freeze
+      end
+
+      def function
+        @args[0]
+      end
+
+      def version
+        options[:version]
+      end
+
+      def revert_to_version
+        options[:revert_to_version]
+      end
+
+      def invert_version
+        Arguments.new([function, options_for_revert])
+      end
+
+      def to_a
+        @args.to_a
+      end
+
+      private
+
+      def options
+        @options ||= @args[1] || {}
+      end
+
+      def options_for_revert
+        options.clone.tap do |revert_options|
+          revert_options[:version] = revert_to_version
+          revert_options.delete(:revert_to_version)
+        end
+      end
+    end
+    private_constant :Arguments
   end
 end

data/lib/fx/configuration.rb

@@ -1,35 +1,10 @@
 module Fx
-  # @return [Fx::Configuration] F(x)'s current configuration
-  def self.configuration
-    @_configuration ||= 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
-
   # F(x)'s configuration object.
   class Configuration
     # The F(x) database adapter instance to use when executing SQL.
     #
     # Defaults to an instance of {Fx::Adapters::Postgres}
-    # @return Fx adapter
+    # @return [Fx::Adapters::Postgres] Fx adapter
     attr_accessor :database
 
     # Prioritizes the order in the schema.rb of functions before other
@@ -37,7 +12,7 @@ module Fx
     # in statements below, i.e.: default column values.
     #
     # Defaults to false
-    # @return Boolean
+    # @return [Boolean] Boolean
     attr_accessor :dump_functions_at_beginning_of_schema
 
     def initialize

data/lib/fx/definition.rb

@@ -1,18 +1,28 @@
 module Fx
   # @api private
   class Definition
-    def initialize(name:, version:, type: "function")
+    FUNCTION = "function".freeze
+    TRIGGER = "trigger".freeze
+
+    def self.function(name:, version:)
+      new(name: name, version: version, type: FUNCTION)
+    end
+
+    def self.trigger(name:, version:)
+      new(name: name, version: version, type: TRIGGER)
+    end
+
+    def initialize(name:, version:, type:)
       @name = name
       @version = version.to_i
       @type = type
     end
 
     def to_sql
-      File.read(find_file || full_path).tap do |content|
-        if content.empty?
-          raise "Define #{@type} in #{path} before migrating."
-        end
-      end
+      content = File.read(find_file || full_path)
+      raise "Define #{@type} in #{path} before migrating." if content.empty?
+
+      content
     end
 
     def full_path

data/lib/fx/function.rb

@@ -6,9 +6,9 @@ module Fx
     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/schema_dumper.rb

@@ -1,10 +1,42 @@
-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(function.to_schema)
+      end
+
+      stream.puts if dumpable_functions_in_database.any?
+    end
+
+    def triggers(stream)
+      dumpable_triggers_in_database = Fx.database.triggers
+
+      if dumpable_triggers_in_database.any?
+        stream.puts
+      end
+
+      dumpable_triggers_in_database.each do |trigger|
+        stream.puts(trigger.to_schema)
+      end
+    end
   end
 end

data/lib/fx/statements.rb

@@ -1,11 +1,236 @@
-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, options = {})
+      version = options.fetch(:version, 1)
+      sql_definition = options[:sql_definition]
+
+      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, options = {})
+      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, options = {})
+      version = options[:version]
+      sql_definition = options[:sql_definition]
+
+      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, options = {})
+      version = options[:version]
+      sql_definition = options[:sql_definition]
+
+      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, options = {})
+      on = options.fetch(:on)
+      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, options = {})
+      version = options[:version]
+      on = options[:on]
+      sql_definition = options[:sql_definition]
+
+      validate_version_or_sql_definition_present!(version, sql_definition)
+      validate_version_and_sql_definition_exclusive!(version, sql_definition)
+
+      if on.nil?
+        raise ArgumentError, "on is required"
+      end
+
+      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

data/lib/fx/trigger.rb

@@ -6,9 +6,9 @@ module Fx
     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.8.0"
+  VERSION = "0.10.0"
 end

data/lib/fx.rb

@@ -1,3 +1,5 @@
+require "rails"
+
 require "fx/version"
 require "fx/adapters/postgres"
 require "fx/command_recorder"
@@ -17,20 +19,36 @@ module Fx
   # Enables fx migration methods, migration reversability, and `schema.rb`
   # dumping.
   def self.load
-    ActiveRecord::Migration::CommandRecorder.send(
-      :include,
-      Fx::CommandRecorder
-    )
+    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 ||= Configuration.new
+  end
 
-    ActiveRecord::SchemaDumper.send(
-      :prepend,
-      Fx::SchemaDumper
-    )
+  # Set F(x)'s configuration
+  #
+  # @param config [Fx::Configuration]
+  def self.configuration=(config)
+    @_configuration = config
+  end
 
-    ActiveRecord::ConnectionAdapters::AbstractAdapter.send(
-      :include,
-      Fx::Statements
-    )
+  # 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).