fx-jets 0.6.3s

data/lib/fx/statements/trigger.rb

@@ -0,0 +1,146 @@
+module Fx
+  module Statements
+    # Methods that are made available in migrations for managing Fx triggers.
+    module Trigger
+      # @api private
+      DEFINTION_TYPE = "trigger".freeze
+
+      # Create a new database trigger.
+      #
+      # @param name [String, Symbol] The name of the database trigger.
+      # @param version [Fixnum] 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 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 PROCEDURE uppercase_users_name();
+      #    SQL
+      #
+      def create_trigger(name, options = {})
+        version = options[:version]
+        _on = options[:on]
+        sql_definition = options[:sql_definition]
+
+        if version.present? && sql_definition.present?
+          raise(
+            ArgumentError,
+            "sql_definition and version cannot both be set",
+          )
+        end
+
+        if version.nil?
+          version = 1
+        end
+
+        sql_definition = sql_definition.strip_heredoc if sql_definition
+        sql_definition ||= Fx::Definition.new(
+          name: name,
+          version: version,
+          type: DEFINTION_TYPE,
+        ).to_sql
+
+        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 [Fixnum] 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 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)
+        revert_to_version = options[:revert_to_version]
+        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 [Fixnum] 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 [Fixnum] The version number to rollback to on
+      #   `rake db rollback`
+      # @return 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 PROCEDURE uppercase_users_name();
+      #    SQL
+      #
+      def update_trigger(name, options = {})
+        version = options[:version]
+        on = options[:on]
+        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
+
+        if version.present? && sql_definition.present?
+          raise(
+            ArgumentError,
+            "sql_definition and version cannot both be set",
+          )
+        end
+
+        if on.nil?
+          raise ArgumentError, "on is required"
+        end
+
+        sql_definition = sql_definition.strip_heredoc if sql_definition
+        sql_definition ||= Fx::Definition.new(
+          name: name,
+          version: version,
+          type: DEFINTION_TYPE,
+        ).to_sql
+
+        Fx.database.update_trigger(
+          name,
+          on: on,
+          sql_definition: sql_definition,
+        )
+      end
+    end
+  end
+end

data/lib/fx/statements.rb

@@ -0,0 +1,11 @@
+require "rails"
+require "fx/statements/function"
+require "fx/statements/trigger"
+
+module Fx
+  # @api private
+  module Statements
+    include Function
+    include Trigger
+  end
+end

data/lib/fx/trigger.rb

@@ -0,0 +1,26 @@
+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")
+    end
+
+    def ==(other)
+      name == other.name && definition == other.definition
+    end
+
+    def to_schema
+      <<-SCHEMA
+  create_trigger :#{name}, sql_definition: <<-\SQL
+      #{definition}
+  SQL
+      SCHEMA
+    end
+  end
+end

data/lib/fx/version.rb

@@ -0,0 +1,4 @@
+module Fx
+  # @api private
+  VERSION = "0.6.3s"
+end

data/lib/fx.rb

@@ -0,0 +1,43 @@
+require "fx/version"
+require "fx/adapters/postgres"
+require "fx/command_recorder"
+require "fx/configuration"
+require "fx/definition"
+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.send(
+      :include,
+      Fx::CommandRecorder,
+    )
+
+    ActiveRecord::SchemaDumper.send(
+      :prepend,
+      Fx::SchemaDumper,
+    )
+
+    ActiveRecord::ConnectionAdapters::AbstractAdapter.send(
+      :include,
+      Fx::Statements,
+    )
+  end
+
+  # The current database adapter used by F(x).
+  #
+  # This defaults to {Fx::Adapters::Postgres} but can be overridden
+  # via {Configuration}.
+  def self.database
+    configuration.database
+  end
+end

data/lib/generators/fx/function/USAGE

@@ -0,0 +1,11 @@
+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
+
+      create: db/functions/test_v01.sql
+      create: db/migrate/[TIMESTAMP]_create_test.rb

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

@@ -0,0 +1,120 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Fx
+  module Generators
+    # @api private
+    class FunctionGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+      source_root File.expand_path("../templates", __FILE__)
+
+      class_option :migration, type: :boolean
+
+      def create_functions_directory
+        unless function_definition_path.exist?
+          empty_directory(function_definition_path)
+        end
+      end
+
+      def create_function_definition
+        if creating_new_function?
+          create_file definition.path
+        else
+          copy_file previous_definition.full_path, definition.full_path
+        end
+      end
+
+      def create_migration_file
+        return if skip_migration_creation?
+        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
+      end
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      no_tasks do
+        def previous_version
+          @_previous_version ||= Dir.entries(function_definition_path).
+            map { |name| version_regex.match(name).try(:[], "version").to_i }.
+            max
+        end
+
+        def version
+          @_version ||= previous_version.next
+        end
+
+        def migration_class_name
+          if updating_existing_function?
+            "UpdateFunction#{class_name}ToVersion#{version}"
+          else
+            super
+          end
+        end
+
+        def activerecord_migration_class
+          if ActiveRecord::Migration.respond_to?(:current_version)
+            "ActiveRecord::Migration[#{ActiveRecord::Migration.current_version}]"
+          else
+            "ActiveRecord::Migration"
+          end
+        end
+
+        def formatted_name
+          if singular_name.include?(".")
+            "\"#{singular_name}\""
+          else
+            ":#{singular_name}"
+          end
+        end
+      end
+
+      private
+
+      def function_definition_path
+        @_function_definition_path ||= Jets.root.join(*%w(db functions))
+      end
+
+      def version_regex
+        /\A#{file_name}_v(?<version>\d+)\.sql\z/
+      end
+
+      def updating_existing_function?
+        previous_version > 0
+      end
+
+      def creating_new_function?
+        previous_version == 0
+      end
+
+      def definition
+        Fx::Definition.new(name: file_name, version: version)
+      end
+
+      def previous_definition
+        Fx::Definition.new(name: file_name, version: previous_version)
+      end
+
+      # Skip creating migration file if:
+      #   - migrations option is nil or false
+      def skip_migration_creation?
+        !migration
+      end
+
+      # True unless explicitly false
+      def migration
+        options[:migration] != false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+class <%= migration_class_name %> < <%= activerecord_migration_class %>
+  def change
+    create_function <%= formatted_name %>
+  end
+end

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

@@ -0,0 +1,5 @@
+class <%= migration_class_name %> < <%= activerecord_migration_class %>
+  def change
+    update_function <%= formatted_name %>, version: <%= version %>, revert_to_version: <%= previous_version %>
+  end
+end

data/lib/generators/fx/trigger/USAGE

@@ -0,0 +1,20 @@
+Description:
+  Create a new database trigger for your application. This will create a new
+  trigger definition file and the accompanying migration.
+
+  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
+
+      create: db/triggers/test_v01.sql
+      create: db/migrate/[TIMESTAMP]_create_trigger_test.rb
+
+    rails generate fx:trigger test
+
+      create: db/triggers/test_v02.sql
+      create: db/migrate/[TIMESTAMP]_update_trigger_test_to_version_2.rb

data/lib/generators/fx/trigger/templates/db/migrate/create_trigger.erb

@@ -0,0 +1,5 @@
+class <%= migration_class_name %> < <%= activerecord_migration_class %>
+  def change
+    create_trigger <%= formatted_name %>, on: <%= formatted_table_name %>
+  end
+end

data/lib/generators/fx/trigger/templates/db/migrate/update_trigger.erb

@@ -0,0 +1,5 @@
+class <%= migration_class_name %> < <%= activerecord_migration_class %>
+  def change
+    update_trigger <%= formatted_name %>, on: <%= formatted_table_name %>, version: <%= version %>, revert_to_version: <%= previous_version %>
+  end
+end

data/lib/generators/fx/trigger/trigger_generator.rb

@@ -0,0 +1,130 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Fx
+  module Generators
+    # @api private
+    class TriggerGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+      source_root File.expand_path("../templates", __FILE__)
+      argument :table_name, type: :hash, required: true
+
+      class_option :migration, type: :boolean
+
+      def create_triggers_directory
+        unless trigger_definition_path.exist?
+          empty_directory(trigger_definition_path)
+        end
+      end
+
+      def create_trigger_definition
+        create_file definition.path
+      end
+
+      def create_migration_file
+        return if skip_migration_creation?
+        if updating_existing_trigger?
+          migration_template(
+            "db/migrate/update_trigger.erb",
+            "db/migrate/update_trigger_#{file_name}_to_version_#{version}.rb"
+          )
+        else
+          migration_template(
+            "db/migrate/create_trigger.erb",
+            "db/migrate/create_trigger_#{file_name}.rb"
+          )
+        end
+      end
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      no_tasks do
+        def previous_version
+          @_previous_version ||= Dir.entries(trigger_definition_path).
+            map { |name| version_regex.match(name).try(:[], "version").to_i }.
+            max
+        end
+
+        def version
+          @_version ||= previous_version.next
+        end
+
+        def migration_class_name
+          if updating_existing_trigger?
+            "UpdateTrigger#{class_name}ToVersion#{version}"
+          else
+            super
+          end
+        end
+
+        def activerecord_migration_class
+          if ActiveRecord::Migration.respond_to?(:current_version)
+            "ActiveRecord::Migration[#{ActiveRecord::Migration.current_version}]"
+          else
+            "ActiveRecord::Migration"
+          end
+        end
+
+        def formatted_name
+          if singular_name.include?(".")
+            "\"#{singular_name}\""
+          else
+            ":#{singular_name}"
+          end
+        end
+
+        def formatted_table_name
+          name = table_name["table_name"] || table_name["on"]
+
+          if name.nil?
+            raise(
+              ArgumentError,
+              "Either `table_name:NAME` or `on:NAME` must be specified",
+            )
+          end
+
+          if name.include?(".")
+            "\"#{name}\""
+          else
+            ":#{name}"
+          end
+        end
+      end
+
+      private
+
+      def version_regex
+        /\A#{file_name}_v(?<version>\d+)\.sql\z/
+      end
+
+      def updating_existing_trigger?
+        previous_version > 0
+      end
+
+      def definition
+        Fx::Definition.new(
+          name: file_name,
+          version: version,
+          type: "trigger",
+        )
+      end
+
+      def trigger_definition_path
+        @_trigger_definition_path ||= Jets.root.join(*["db", "triggers"])
+      end
+
+      # Skip creating migration file if:
+      #   - migrations option is nil or false
+      def skip_migration_creation?
+        !migration
+      end
+
+      # True unless explicitly false
+      def migration
+        options[:migration] != false
+      end
+    end
+  end
+end

data/lib/generators.rb

@@ -0,0 +1,11 @@
+module Fx
+  # Fx provides generators for creating and updating functions and triggers.
+  #
+  # See:
+  #
+  # * {file:lib/generators/fx/function/USAGE Function Generator}
+  # * {file:lib/generators/fx/trigger/USAGE Trigger Generator}
+  # * {file:README.md README}
+  module Generators
+  end
+end

data/spec/acceptance/user_manages_functions_spec.rb

@@ -0,0 +1,57 @@
+require "acceptance_helper"
+
+describe "User manages functions" do
+  it "handles simple functions" do
+    successfully "rails generate fx:function test"
+    write_function_definition "test_v01", <<-EOS
+      CREATE OR REPLACE FUNCTION test()
+      RETURNS text AS $$
+      BEGIN
+          RETURN 'test';
+      END;
+      $$ LANGUAGE plpgsql;
+    EOS
+    successfully "rake db:migrate"
+
+    result = execute("SELECT * FROM test() AS result")
+    expect(result).to eq("result" => "test")
+
+    successfully "rails generate fx:function test"
+    verify_identical_definitions(
+      "db/functions/test_v01.sql",
+      "db/functions/test_v02.sql",
+    )
+    write_function_definition "test_v02", <<-EOS
+      CREATE OR REPLACE FUNCTION test()
+      RETURNS text AS $$
+      BEGIN
+          RETURN 'testest';
+      END;
+      $$ LANGUAGE plpgsql;
+    EOS
+    successfully "rake db:migrate"
+
+    result = execute("SELECT * FROM test() AS result")
+    expect(result).to eq("result" => "testest")
+  end
+
+  it "handles functions with arguments" do
+    successfully "rails generate fx:function adder"
+    write_function_definition "adder_v01", <<-EOS
+      CREATE FUNCTION adder(x int, y int)
+      RETURNS int AS $$
+      BEGIN
+          RETURN $1 + $2;
+      END;
+      $$ LANGUAGE plpgsql;
+    EOS
+    successfully "rake db:migrate"
+
+    result = execute("SELECT * FROM adder(1, 2) AS result")
+    result["result"] = result["result"].to_i
+    expect(result).to eq("result" => 3)
+
+    successfully "rails destroy fx:function adder"
+    successfully "rake db:migrate"
+  end
+end

data/spec/acceptance/user_manages_triggers_spec.rb

@@ -0,0 +1,51 @@
+require "acceptance_helper"
+
+describe "User manages triggers" do
+  it "handles simple triggers" do
+    successfully "rails generate model user name:string upper_name:string"
+    successfully "rails generate fx:function uppercase_users_name"
+    write_function_definition "uppercase_users_name_v01", <<-EOS
+      CREATE OR REPLACE FUNCTION uppercase_users_name()
+      RETURNS trigger AS $$
+      BEGIN
+        NEW.upper_name = UPPER(NEW.name);
+        RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql;
+    EOS
+    successfully "rails generate fx:trigger uppercase_users_name table_name:users"
+    write_trigger_definition "uppercase_users_name_v01", <<-EOS
+      CREATE TRIGGER uppercase_users_name
+          BEFORE INSERT ON users
+          FOR EACH ROW
+          EXECUTE PROCEDURE uppercase_users_name();
+    EOS
+    successfully "rake db:migrate"
+
+    execute <<-EOS
+      INSERT INTO users
+      (name, created_at, updated_at)
+      VALUES
+      ('Bob', NOW(), NOW());
+    EOS
+    result = execute("SELECT upper_name FROM users WHERE name = 'Bob';")
+    expect(result).to eq("upper_name" => "BOB")
+
+    successfully "rails generate fx:trigger uppercase_users_name table_name:users"
+    write_trigger_definition "uppercase_users_name_v02", <<-EOS
+      CREATE TRIGGER uppercase_users_name
+          BEFORE UPDATE ON users
+          FOR EACH ROW
+          EXECUTE PROCEDURE uppercase_users_name();
+    EOS
+    successfully "rake db:migrate"
+    execute <<-EOS
+      UPDATE users
+      SET name = 'Alice'
+      WHERE id = 1;
+    EOS
+
+    result = execute("SELECT upper_name FROM users WHERE name = 'Alice';")
+    expect(result).to eq("upper_name" => "ALICE")
+  end
+end