fx-jets 0.6.3s

data/lib/fx/adapters/postgres.rb

@@ -0,0 +1,167 @@
+require "fx/adapters/postgres/connection"
+require "fx/adapters/postgres/functions"
+require "fx/adapters/postgres/triggers"
+
+module Fx
+  # F(x) database adapters.
+  #
+  # F(x) ships with a Postgres adapter only but can be extended with
+  # additional adapters. The {Fx::Adapters::Postgres} adapter provides the
+  # interface.
+  module Adapters
+    # Creates an instance of the F(x) Postgres adapter.
+    #
+    # This is the default adapter for F(x). Configuring it via
+    # {Fx.configure} is not required, but the example below shows how one
+    # would explicitly set it.
+    #
+    # @param [#connection] connectable An object that returns the connection
+    #   for F(x) to use. Defaults to `ActiveRecord::Base`.
+    #
+    # @example
+    #  Fx.configure do |config|
+    #    config.adapter = Fx::Adapters::Postgres.new
+    #  end
+    class Postgres
+      # Creates an instance of the F(x) Postgres adapter.
+      #
+      # This is the default adapter for F(x). Configuring it via
+      # {Fx.configure} is not required, but the example below shows how one
+      # would explicitly set it.
+      #
+      # @param [#connection] connectable An object that returns the connection
+      #   for F(x) to use. Defaults to `ActiveRecord::Base`.
+      #
+      # @example
+      #  Fx.configure do |config|
+      #    config.adapter = Fx::Adapters::Postgres.new
+      #  end
+      def initialize(connectable = ActiveRecord::Base)
+        @connectable = connectable
+      end
+
+      # Returns an array of functions in the database.
+      #
+      # This collection of functions is used by the [Fx::SchemaDumper] to
+      # populate the `schema.rb` file.
+      #
+      # @return [Array<Fx::Function>]
+      def functions
+        Functions.all(connection)
+      end
+
+      # Returns an array of triggers in the database.
+      #
+      # This collection of triggers is used by the [Fx::SchemaDumper] to
+      # populate the `schema.rb` file.
+      #
+      # @return [Array<Fx::Trigger>]
+      def triggers
+        Triggers.all(connection)
+      end
+
+      # Creates a function in the database.
+      #
+      # This is typically called in a migration via
+      # {Fx::Statements::Function#create_function}.
+      #
+      # @param sql_definition The SQL schema for the function.
+      #
+      # @return [void]
+      def create_function(sql_definition)
+        execute sql_definition
+      end
+
+      # Creates a trigger in the database.
+      #
+      # This is typically called in a migration via
+      # {Fx::Statements::Trigger#create_trigger}.
+      #
+      # @param sql_definition The SQL schema for the trigger.
+      #
+      # @return [void]
+      def create_trigger(sql_definition)
+        execute sql_definition
+      end
+
+      # Updates a function in the database.
+      #
+      # This is typically called in a migration via
+      # {Fx::Statements::Function#update_function}.
+      #
+      # @param name The name of the function.
+      # @param sql_definition The SQL schema for the function.
+      #
+      # @return [void]
+      def update_function(name, sql_definition)
+        drop_function(name)
+        create_function(sql_definition)
+      end
+
+      # Updates a trigger in the database.
+      #
+      # The existing trigger is dropped and recreated using the supplied `on`
+      # and `version` parameter.
+      #
+      # This is typically called in a migration via
+      # {Fx::Statements::Function#update_trigger}.
+      #
+      # @param name The name of the trigger.
+      # @param on The associated table for the trigger to drop
+      # @param sql_definition The SQL schema for the function.
+      #
+      # @return [void]
+      def update_trigger(name, on:, sql_definition:)
+        drop_trigger(name, on: on)
+        create_trigger(sql_definition)
+      end
+
+      # Drops the function from the database
+      #
+      # This is typically called in a migration via
+      # {Fx::Statements::Function#drop_function}.
+      #
+      # @param name The name of the function to drop
+      #
+      # @return [void]
+      def drop_function(name)
+        if support_drop_function_without_args
+          execute "DROP FUNCTION #{name};"
+        else
+          execute "DROP FUNCTION #{name}();"
+        end
+      end
+
+      # Drops the trigger from the database
+      #
+      # This is typically called in a migration via
+      # {Fx::Statements::Trigger#drop_trigger}.
+      #
+      # @param name The name of the trigger to drop
+      # @param on The associated table for the trigger to drop
+      #
+      # @return [void]
+      def drop_trigger(name, on:)
+        execute "DROP TRIGGER #{name} ON #{on};"
+      end
+
+      private
+
+      attr_reader :connectable
+
+      delegate :execute, to: :connection
+
+      def connection
+        Connection.new(connectable.connection)
+      end
+
+      def support_drop_function_without_args
+        # https://www.postgresql.org/docs/9.6/sql-dropfunction.html
+        # https://www.postgresql.org/docs/10/sql-dropfunction.html
+
+        pg_connection = connectable.connection.raw_connection
+        pg_connection.server_version >= 10_00_00
+      end
+    end
+  end
+end

data/lib/fx/command_recorder/arguments.rb

@@ -0,0 +1,43 @@
+module Fx
+  module CommandRecorder
+    # @api private
+    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
+  end
+end

data/lib/fx/command_recorder/function.rb

@@ -0,0 +1,30 @@
+module Fx
+  module CommandRecorder
+    # @api private
+    module Function
+      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
+    end
+  end
+end

data/lib/fx/command_recorder/trigger.rb

@@ -0,0 +1,30 @@
+module Fx
+  module CommandRecorder
+    # @api private
+    module Trigger
+      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
+    end
+  end
+end

data/lib/fx/command_recorder.rb

@@ -0,0 +1,24 @@
+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
+
+    private
+
+    def perform_inversion(method, args)
+      arguments = Arguments.new(args)
+
+      if arguments.revert_to_version.nil?
+        message = "`#{method}` is reversible only if given a `revert_to_version`"
+        raise ActiveRecord::IrreversibleMigration, message
+      end
+
+      [method, arguments.invert_version.to_a]
+    end
+  end
+end

data/lib/fx/configuration.rb

@@ -0,0 +1,48 @@
+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
+    attr_accessor :database
+
+    # Prioritizes the order in the schema.rb of functions before other
+    # statements in order to make directly schema load work when using functions
+    # in statements below, i.e.: default column values.
+    #
+    # Defaults to false
+    # @return Boolean
+    attr_accessor :dump_functions_at_beginning_of_schema
+
+    def initialize
+      @database = Fx::Adapters::Postgres.new
+      @dump_functions_at_beginning_of_schema = false
+    end
+  end
+end

data/lib/fx/definition.rb

@@ -0,0 +1,46 @@
+module Fx
+  # @api private
+  class Definition
+    def initialize(name:, version:, type: "function")
+      @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
+    end
+
+    def full_path
+      Jets.root.join(path)
+    end
+
+    def path
+      @_path ||= File.join("db", @type.pluralize, filename)
+    end
+
+    def version
+      @version.to_s.rjust(2, "0")
+    end
+
+    private
+
+    def filename
+      @_filename ||= "#{@name}_v#{version}.sql"
+    end
+
+    def find_file
+      migration_paths.lazy
+        .map { |migration_path| File.expand_path(File.join("..", "..", path), migration_path) }
+        .find { |definition_path| File.exist?(definition_path) }
+    end
+
+    def migration_paths
+      [Jets.root.join('db', 'migrate').to_s]
+    end
+  end
+end

data/lib/fx/function.rb

@@ -0,0 +1,26 @@
+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")
+    end
+
+    def ==(other)
+      name == other.name && definition == other.definition
+    end
+
+    def to_schema
+      <<-SCHEMA.indent(2)
+create_function :#{name}, sql_definition: <<-'SQL'
+#{definition.indent(4).rstrip}
+SQL
+      SCHEMA
+    end
+  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/function.rb

@@ -0,0 +1,38 @@
+require "rails"
+
+module Fx
+  module SchemaDumper
+    # @api private
+    module Function
+      def tables(stream)
+        if Fx.configuration.dump_functions_at_beginning_of_schema
+          functions(stream)
+          empty_line(stream)
+        end
+
+        super
+
+        unless Fx.configuration.dump_functions_at_beginning_of_schema
+          functions(stream)
+          empty_line(stream)
+        end
+      end
+
+      def empty_line(stream)
+        stream.puts if dumpable_functions_in_database.any?
+      end
+
+      def functions(stream)
+        dumpable_functions_in_database.each do |function|
+          stream.puts(function.to_schema)
+        end
+      end
+
+      private
+
+      def dumpable_functions_in_database
+        @_dumpable_functions_in_database ||= Fx.database.functions
+      end
+    end
+  end
+end

data/lib/fx/schema_dumper/trigger.rb

@@ -0,0 +1,29 @@
+require "rails"
+
+module Fx
+  module SchemaDumper
+    # @api private
+    module Trigger
+      def tables(stream)
+        super
+        triggers(stream)
+      end
+
+      def triggers(stream)
+        if dumpable_triggers_in_database.any?
+          stream.puts
+        end
+
+        dumpable_triggers_in_database.each do |trigger|
+          stream.puts(trigger.to_schema)
+        end
+      end
+
+      private
+
+      def dumpable_triggers_in_database
+        @_dumpable_triggers_in_database ||= Fx.database.triggers
+      end
+    end
+  end
+end

data/lib/fx/schema_dumper.rb

@@ -0,0 +1,10 @@
+require "fx/schema_dumper/function"
+require "fx/schema_dumper/trigger"
+
+module Fx
+  # @api private
+  module SchemaDumper
+    include Function
+    include Trigger
+  end
+end

data/lib/fx/statements/function.rb

@@ -0,0 +1,115 @@
+require "rails"
+
+module Fx
+  module Statements
+    # Methods that are made available in migrations for managing Fx functions.
+    module Function
+      # Create a new database function.
+      #
+      # @param name [String, Symbol] The name of the database function.
+      # @param version [Fixnum] 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_defintion` and `version` are provided,
+      #   `sql_definition` takes prescedence.
+      # @return 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]
+
+        if version.nil? && sql_definition.nil?
+          raise(
+            ArgumentError,
+            "version or sql_definition must be specified",
+          )
+        end
+        sql_definition = sql_definition.strip_heredoc if sql_definition
+        sql_definition ||= Fx::Definition.new(name: name, version: version).to_sql
+
+        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 [Fixnum] 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 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 = {})
+        revert_to_version = options[:revert_to_version]
+        Fx.database.drop_function(name)
+      end
+
+      # Update a database function.
+      #
+      # @param name [String, Symbol] The name of the database function.
+      # @param version [Fixnum] 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_defintion` and `version` are provided,
+      #   `sql_definition` takes prescedence.
+      # @return 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]
+        revert_to_version = options[:revert_to_version]
+
+        if version.nil? && sql_definition.nil?
+          raise(
+            ArgumentError,
+            "version or sql_definition must be specified",
+          )
+        end
+
+        sql_definition = sql_definition.strip_heredoc if sql_definition
+        sql_definition ||= Fx::Definition.new(
+          name: name,
+          version: version,
+        ).to_sql
+
+        Fx.database.update_function(name, sql_definition)
+      end
+    end
+  end
+end