fx 0.8.0 → 0.9.0

data/lib/fx/statements.rb

@@ -1,11 +1,233 @@
-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 [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_definition` 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.function(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 = {})
+      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_definition` 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]
+
+      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.function(name: name, version: version).to_sql
+
+      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 [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 FUNCTION 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.trigger(name: name, version: version).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)
+      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 FUNCTION uppercase_users_name();
+    #    SQL
+    #
+    def update_trigger(name, options = {})
+      version = options[:version]
+      on = options[:on]
+      sql_definition = options[:sql_definition]
+
+      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.trigger(name: name, version: version).to_sql
+
+      Fx.database.update_trigger(
+        name,
+        on: on,
+        sql_definition: sql_definition
+      )
+    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.9.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).

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

@@ -98,11 +98,11 @@ module Fx
       end
 
       def definition
-        Fx::Definition.new(name: file_name, version: version)
+        Fx::Definition.function(name: file_name, version: version)
       end
 
       def previous_definition
-        Fx::Definition.new(name: file_name, version: previous_version)
+        Fx::Definition.function(name: file_name, version: previous_version)
       end
 
       # Skip creating migration file if:

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

@@ -104,11 +104,7 @@ module Fx
       end
 
       def definition
-        Fx::Definition.new(
-          name: file_name,
-          version: version,
-          type: "trigger"
-        )
+        Fx::Definition.trigger(name: file_name, version: version)
       end
 
       def trigger_definition_path

data/spec/acceptance/user_manages_functions_spec.rb

@@ -1,9 +1,9 @@
 require "acceptance_helper"
 
-describe "User manages functions" do
+RSpec.describe "User manages functions" do
   it "handles simple functions" do
     successfully "rails generate fx:function test"
-    write_function_definition "test_v01", <<-EOS
+    write_function_definition "test_v01", <<~EOS
       CREATE OR REPLACE FUNCTION test()
       RETURNS text AS $$
       BEGIN
@@ -21,7 +21,7 @@ describe "User manages functions" do
       "db/functions/test_v01.sql",
       "db/functions/test_v02.sql"
     )
-    write_function_definition "test_v02", <<-EOS
+    write_function_definition "test_v02", <<~EOS
       CREATE OR REPLACE FUNCTION test()
       RETURNS text AS $$
       BEGIN
@@ -37,7 +37,7 @@ describe "User manages functions" do
 
   it "handles functions with arguments" do
     successfully "rails generate fx:function adder"
-    write_function_definition "adder_v01", <<-EOS
+    write_function_definition "adder_v01", <<~EOS
       CREATE FUNCTION adder(x int, y int)
       RETURNS int AS $$
       BEGIN

data/spec/acceptance/user_manages_triggers_spec.rb

@@ -1,10 +1,10 @@
 require "acceptance_helper"
 
-describe "User manages triggers" do
+RSpec.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
+    write_function_definition "uppercase_users_name_v01", <<~EOS
       CREATE OR REPLACE FUNCTION uppercase_users_name()
       RETURNS trigger AS $$
       BEGIN
@@ -14,7 +14,7 @@ describe "User manages triggers" do
       $$ LANGUAGE plpgsql;
     EOS
     successfully "rails generate fx:trigger uppercase_users_name table_name:users"
-    write_trigger_definition "uppercase_users_name_v01", <<-EOS
+    write_trigger_definition "uppercase_users_name_v01", <<~EOS
       CREATE TRIGGER uppercase_users_name
           BEFORE INSERT ON users
           FOR EACH ROW
@@ -22,7 +22,7 @@ describe "User manages triggers" do
     EOS
     successfully "rake db:migrate"
 
-    execute <<-EOS
+    execute <<~EOS
       INSERT INTO users
       (name, created_at, updated_at)
       VALUES
@@ -32,14 +32,14 @@ describe "User manages triggers" do
     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
+    write_trigger_definition "uppercase_users_name_v02", <<~EOS
       CREATE TRIGGER uppercase_users_name
           BEFORE UPDATE ON users
           FOR EACH ROW
           EXECUTE FUNCTION uppercase_users_name();
     EOS
     successfully "rake db:migrate"
-    execute <<-EOS
+    execute <<~EOS
       UPDATE users
       SET name = 'Alice'
       WHERE id = 1;

data/spec/acceptance_helper.rb

@@ -11,7 +11,7 @@ RSpec.configure do |config|
 
   config.before(:suite) do
     Dir.chdir("spec/dummy") do
-      system <<-CMD
+      system <<~CMD
         git init -b master 1>/dev/null &&
         git config user.email "fx@example.com"
         git config user.name "Fx"
@@ -24,7 +24,7 @@ RSpec.configure do |config|
   config.after(:suite) do
     Dir.chdir("spec/dummy") do
       ActiveRecord::Base.connection.disconnect!
-      system <<-CMD
+      system <<~CMD
         echo &&
         rake db:environment:set db:drop db:create 1>/dev/null &&
         git add -A &&

data/spec/dummy/config/application.rb

@@ -12,6 +12,10 @@ module Dummy
     config.eager_load = false
     config.active_support.deprecation = :stderr
 
-    config.active_record.legacy_connection_handling = false
+    config.load_defaults 7.0
+
+    if Rails.version >= "8.0"
+      config.active_support.to_time_preserves_timezone = :zone
+    end
   end
 end

data/spec/features/functions/migrations_spec.rb

@@ -1,8 +1,8 @@
 require "spec_helper"
 
-describe "Function migrations", :db do
+RSpec.describe "Function migrations", :db do
   around do |example|
-    sql_definition = <<-EOS
+    sql_definition = <<~EOS
       CREATE OR REPLACE FUNCTION test()
       RETURNS text AS $$
       BEGIN
@@ -40,7 +40,7 @@ describe "Function migrations", :db do
   it "can run migrations that updates functions" do
     connection.create_function(:test)
 
-    sql_definition = <<-EOS
+    sql_definition = <<~EOS
       CREATE OR REPLACE FUNCTION test()
       RETURNS text AS $$
       BEGIN

data/spec/features/functions/revert_spec.rb

@@ -1,8 +1,8 @@
 require "spec_helper"
 
-describe "Reverting migrations", :db do
+RSpec.describe "Reverting migrations", :db do
   around do |example|
-    sql_definition = <<-EOS
+    sql_definition = <<~EOS
       CREATE OR REPLACE FUNCTION test()
       RETURNS text AS $$
       BEGIN
@@ -50,7 +50,7 @@ describe "Reverting migrations", :db do
   it "can run reversible migrations for updating functions" do
     connection.create_function(:test)
 
-    sql_definition = <<-EOS
+    sql_definition = <<~EOS
       CREATE OR REPLACE FUNCTION test()
       RETURNS text AS $$
       BEGIN

data/spec/features/triggers/migrations_spec.rb

@@ -1,15 +1,15 @@
 require "spec_helper"
 
-describe "Trigger migrations", :db do
+RSpec.describe "Trigger migrations", :db do
   around do |example|
-    connection.execute <<-EOS
+    connection.execute <<~EOS
       CREATE TABLE users (
           id int PRIMARY KEY,
           name varchar(256),
           upper_name varchar(256)
       );
     EOS
-    Fx.database.create_function <<-EOS
+    Fx.database.create_function <<~EOS
       CREATE OR REPLACE FUNCTION uppercase_users_name()
       RETURNS trigger AS $$
       BEGIN
@@ -18,7 +18,7 @@ describe "Trigger migrations", :db do
       END;
       $$ LANGUAGE plpgsql;
     EOS
-    sql_definition = <<-EOS
+    sql_definition = <<~EOS
       CREATE TRIGGER uppercase_users_name
           BEFORE INSERT ON users
           FOR EACH ROW

data/spec/features/triggers/revert_spec.rb

@@ -1,15 +1,15 @@
 require "spec_helper"
 
-describe "Reverting migrations", :db do
+RSpec.describe "Reverting migrations", :db do
   around do |example|
-    connection.execute <<-EOS
+    connection.execute <<~EOS
       CREATE TABLE users (
           id int PRIMARY KEY,
           name varchar(256),
           upper_name varchar(256)
       );
     EOS
-    Fx.database.create_function <<-EOS
+    Fx.database.create_function <<~EOS
       CREATE OR REPLACE FUNCTION uppercase_users_name()
       RETURNS trigger AS $$
       BEGIN
@@ -18,7 +18,7 @@ describe "Reverting migrations", :db do
       END;
       $$ LANGUAGE plpgsql;
     EOS
-    sql_definition = <<-EOS
+    sql_definition = <<~EOS
       CREATE TRIGGER uppercase_users_name
           BEFORE INSERT ON users
           FOR EACH ROW
@@ -67,7 +67,7 @@ describe "Reverting migrations", :db do
   it "can run reversible migrations for updating triggers" do
     connection.create_trigger(:uppercase_users_name)
 
-    sql_definition = <<-EOS
+    sql_definition = <<~EOS
       CREATE TRIGGER uppercase_users_name
           BEFORE UPDATE ON users
           FOR EACH ROW

data/spec/fx/adapters/postgres/functions_spec.rb

@@ -1,37 +1,33 @@
 require "spec_helper"
 
-module Fx
-  module Adapters
-    describe Postgres::Functions, :db do
-      describe ".all" do
-        it "returns `Function` objects" do
-          connection = ActiveRecord::Base.connection
-          connection.execute <<-EOS.strip_heredoc
-            CREATE OR REPLACE FUNCTION test()
-            RETURNS text AS $$
-            BEGIN
-                RETURN 'test';
-            END;
-            $$ LANGUAGE plpgsql;
-          EOS
+RSpec.describe Fx::Adapters::Postgres::Functions, :db do
+  describe ".all" do
+    it "returns `Function` objects" do
+      connection = ActiveRecord::Base.connection
+      connection.execute <<~EOS
+        CREATE OR REPLACE FUNCTION test()
+        RETURNS text AS $$
+        BEGIN
+            RETURN 'test';
+        END;
+        $$ LANGUAGE plpgsql;
+      EOS
 
-          functions = Postgres::Functions.new(connection).all
+      functions = Fx::Adapters::Postgres::Functions.new(connection).all
 
-          first = functions.first
-          expect(functions.size).to eq 1
-          expect(first.name).to eq "test"
-          expect(first.definition).to eq <<-EOS.strip_heredoc
-            CREATE OR REPLACE FUNCTION public.test()
-             RETURNS text
-             LANGUAGE plpgsql
-            AS $function$
-            BEGIN
-                RETURN 'test';
-            END;
-            $function$
-          EOS
-        end
-      end
+      first = functions.first
+      expect(functions.size).to eq(1)
+      expect(first.name).to eq("test")
+      expect(first.definition).to eq(<<~EOS)
+        CREATE OR REPLACE FUNCTION public.test()
+         RETURNS text
+         LANGUAGE plpgsql
+        AS $function$
+        BEGIN
+            RETURN 'test';
+        END;
+        $function$
+      EOS
     end
   end
 end