pg_trunk 0.1.0

data/lib/pg_trunk/operations/triggers/create_trigger.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#create_trigger(table, name = nil, **options, &block)
+# Create a trigger for a table
+#
+# @param [#to_s] table (nil) The qualified name of the table
+# @param [#to_s] name (nil) The name of the trigger
+# @option [Boolean] :replace_existing (false) If the trigger should overwrite an existing one
+# @option [#to_s] :function (nil) The qualified name of the function to be called
+# @option [Symbol] :type (nil) When the trigger should be run
+#   Supported values: :before, :after, :instead_of
+# @option [Array<Symbol>] :events List of events running the trigger
+#   Supported values in the array: :insert, :update, :delete, :truncate
+# @option [Boolean] :constraint (false) If the trigger is a constraint
+# @option [Symbol] :initially (:immediate) If the constraint check should be deferred
+#   Supported values: :immediate (default), :deferred
+# @option [#to_s] :when (nil) The SQL snippet definiing a condition for the trigger
+# @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
+#   Supported values: :statement (default), :row
+# @option [#to_s] :comment (nil) The commend describing the trigger
+# @yield [Proc] the block with the trigger's definition
+# @yieldparam The receiver of methods specifying the trigger
+#
+# The trigger can be created either using inline syntax
+#
+#   create_trigger "users", "do_something",
+#                   function: "do_something()",
+#                   for_each: :row,
+#                   type: :after,
+#                   events: %i[insert update],
+#                   comment: "Does something useful"
+#
+# or using a block:
+#
+#   create_trigger do |t|
+#     t.table "users"
+#     t.name "do_something"
+#     t.function "do_something()"
+#     t.for_each :row
+#     t.type :after
+#     t.events %i[insert update]
+#     t.comment "Does something useful"
+#   end
+#
+# With a `replace_existing: true` option,
+# it will be created using the `CREATE OR REPLACE` clause.
+# (Available in PostgreSQL v14+).
+#
+#    create_trigger "users", "do_something",
+#                   function: "do_something()",
+#                   type: :after,
+#                   events: %i[insert update],
+#                   replace_previous: true
+#
+# In this case the migration is irreversible because we
+# don't know if and how to restore its previous definition.
+
+module PGTrunk::Operations::Triggers
+  # @private
+  class CreateTrigger < Base
+    validates :function, :type, :events, presence: true
+    validates :if_exists, :new_name, absence: true
+
+    from_sql do |_version|
+      <<~SQL
+        WITH t AS (
+          SELECT
+            t.oid,
+            t.tgname AS name,
+            (
+              CASE WHEN t.tgconstraint != 0 THEN true END
+            ) AS constraint,
+            (
+              CASE
+                WHEN t.tgdeferrable AND t.tginitdeferred THEN 'deferred'
+                WHEN t.tgdeferrable AND NOT t.tginitdeferred THEN 'immediate'
+              END
+            ) AS "initially",
+            pg_get_triggerdef(t.oid, true) AS snippet,
+            (
+              CASE
+              WHEN (t.tgtype::int::bit(7) & b'0000001')::int = 0 THEN 'statement'
+              ELSE 'row'
+              END
+            ) AS for_each,
+            (
+              SELECT array_agg(attname)
+              FROM (
+                SELECT a.attname
+                FROM unnest(t.tgattr) col(num)
+                  JOIN pg_attribute a ON a.attnum = col.num
+                WHERE a.attrelid = t.tgrelid
+              ) list
+            ) AS columns,
+            (
+              CASE
+              WHEN ((tgtype::int::bit(7) & b'0000010')::int != 0) THEN 'before'
+              WHEN ((tgtype::int::bit(7) & b'0000010')::int = 0) THEN 'after'
+              ELSE 'instead_of'
+              END
+            ) AS type,
+            array_remove(
+              ARRAY[
+                (CASE WHEN (tgtype::int::bit(7) & b'0000100')::int != 0 THEN 'insert' END),
+                (CASE WHEN (tgtype::int::bit(7) & b'0001000')::int != 0 THEN 'delete' END),
+                (CASE WHEN (tgtype::int::bit(7) & b'0010000')::int != 0 THEN 'update' END),
+                (CASE WHEN (tgtype::int::bit(7) & b'0100000')::int != 0 THEN 'truncate' END)
+              ]::text[],
+              NULL
+            ) AS events,
+            (c.relnamespace::regnamespace || '.' || c.relname) AS "table",
+            (f.pronamespace::regnamespace || '.' || f.proname || '()') AS function,
+            d.description AS comment
+          FROM pg_trigger t
+            JOIN pg_proc f ON f.oid = t.tgfoid
+            JOIN pg_class c ON c.oid = t.tgrelid
+            LEFT JOIN pg_description d ON d.objoid = t.oid
+        )
+        SELECT
+          oid,
+          name,
+          "table",
+          function,
+          "constraint",
+          "initially",
+          for_each,
+          (
+            CASE
+            WHEN regexp_match(snippet, 'WHEN') IS NOT NULL
+            THEN
+              regexp_replace(
+                regexp_replace(snippet, '^.+WHEN [(]', ''),
+                '[)] EXECUTE.+',
+                ''
+              )
+            END
+          ) AS "when",
+          type,
+          events,
+          columns,
+          comment
+        FROM t
+      SQL
+    end
+
+    def to_sql(version)
+      [
+        create_trigger(version),
+        *create_comment,
+        register_trigger,
+      ].join(" ")
+    end
+
+    def invert
+      irreversible!("replace_existing: true") if replace_existing
+      DropTrigger.new(**to_h)
+    end
+
+    private
+
+    def create_trigger(version)
+      sql = "CREATE"
+      sql << " OR REPLACE" if replace_existing && version >= "14"
+      sql << " CONSTRAINT" if constraint
+      sql << " TRIGGER #{name.name.inspect}"
+      sql << " BEFORE #{events_sql}" if type == :before
+      sql << " AFTER #{events_sql}" if type == :after
+      sql << " INSTEAD OF #{events_sql}" if type == :instead_of
+      sql << " ON #{table.to_sql}"
+      sql << " DEFERRABLE" if initially.present?
+      sql << " INITIALLY DEFERRED" if initially == :deferred
+      sql << " FOR EACH ROW" if for_each&.== :row
+      sql << " WHEN (#{self.when})" if self.when.present?
+      sql << " EXECUTE PROCEDURE #{function.to_sql(true)};"
+    end
+
+    def create_comment
+      return unless comment
+
+      <<~SQL.squish
+        COMMENT ON TRIGGER #{name.name.inspect} ON #{table.to_sql}
+          IS $comment$#{comment}$comment$;
+      SQL
+    end
+
+    def register_trigger
+      <<~SQL.squish
+        INSERT INTO pg_trunk (oid, classid)
+          SELECT t.oid, 'pg_trigger'::regclass
+          FROM pg_trigger t JOIN pg_class c ON t.tgrelid = c.oid
+          WHERE c.relname = #{table.quoted}
+            AND c.relnamespace = #{table.namespace}
+            AND t.tgname = #{name.quoted}
+        ON CONFLICT DO NOTHING;
+      SQL
+    end
+
+    def events_sql
+      events.map do |event|
+        if event == :update && columns.present?
+          "UPDATE OF #{columns.join(', ')}"
+        else
+          event.to_s.upcase
+        end
+      end.join(" OR ")
+    end
+  end
+end

data/lib/pg_trunk/operations/triggers/drop_trigger.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#drop_trigger(table, name = nil, **options, &block)
+# Drop a trigger for a table
+#
+# @param [#to_s] table (nil) The qualified name of the table
+# @param [#to_s] name (nil) The name of the trigger
+# @option [Boolean] :if_exists (false) Suppress the error when the trigger is absent
+# @option [#to_s] :function (nil) The qualified name of the function to be called
+# @option [Symbol] :type (nil) When the trigger should be run
+#   Supported values: :before, :after, :instead_of
+# @option [Array<Symbol>] :events List of events running the trigger
+#   Supported values in the array: :insert, :update, :delete, :truncate
+# @option [Boolean] :constraint (false) If the trigger is a constraint
+# @option [Symbol] :initially (:immediate) If the constraint check should be deferred
+#   Supported values: :immediate (default), :deferred
+# @option [#to_s] :when (nil) The SQL snippet definiing a condition for the trigger
+# @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
+#   Supported values: :statement (default), :row
+# @option [#to_s] :comment (nil) The commend describing the trigger
+# @yield [Proc] the block with the trigger's definition
+# @yieldparam The receiver of methods specifying the trigger
+#
+# A trigger can be dropped by a table and name:
+#
+#   drop_trigger "users", "do_something"
+#
+# the default name can be restored from its attributes as well.
+#
+#   drop_trigger "users" do |t|
+#     t.function "send_notifications()"
+#     t.for_each :row
+#     t.type :after
+#     t.events %i[update]
+#     t.columns %w[email phone]
+#     t.comment "Does something"
+#   end
+#
+# Notice, that you have to specify all attributes to make
+# the operation reversible.
+#
+# The operation can be called with `if_exists` option. In this case
+# it would do nothing when no trigger existed.
+#
+#   drop_trigger "users", "unknown_trigger", if_exists: true
+#
+# This option, though, makes the operation irreversible because of
+# uncertainty of the previous state of the database.
+
+module PGTrunk::Operations::Triggers
+  # @private
+  class DropTrigger < Base
+    validates :replace_existing, :new_name, absence: true
+
+    def to_sql(_version)
+      sql = "DROP TRIGGER"
+      sql << " IF EXISTS" if if_exists
+      sql << " #{name.name.inspect} ON #{table.to_sql};"
+    end
+
+    def invert
+      irreversible!("if_exists: true") if if_exists
+      CreateTrigger.new(**to_h)
+    end
+  end
+end

data/lib/pg_trunk/operations/triggers/rename_trigger.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#rename_trigger(table, name = nil, **options, &block)
+# Rename a trigger
+#
+# @param [#to_s] table (nil) The qualified name of the table
+# @param [#to_s] name (nil) The name of the trigger
+# @option [#to_s] :to (nil) The new name of the trigger
+# @param [#to_s] table (nil) The qualified name of the table
+# @param [#to_s] name (nil) The current name of the trigger
+# @option [#to_s] :to (nil) The new name for the trigger
+# @option [#to_s] :function (nil) The qualified name of the function to be called
+# @option [Symbol] :type (nil) When the trigger should be run
+#   Supported values: :before, :after, :instead_of
+# @option [Array<Symbol>] :events List of events running the trigger
+#   Supported values in the array: :insert, :update, :delete, :truncate
+# @option [Symbol] :for_each (:statement) Define if a trigger should be run for every row
+#   Supported values: :statement (default), :row
+# @yield [Proc] the block with the trigger's definition
+# @yieldparam The receiver of methods specifying the trigger
+#
+# A trigger can be renamed by either setting a new name explicitly
+#
+#   rename_trigger "users", "do_something", to: "do_something_different"
+#
+# or resetting it to the default (generated) value.
+#
+#   rename_trigger "users", "do_something"
+#
+# The previously generated name of the trigger can be get
+# from its parameters. In this case all the essentials
+# parameters must be specified:
+#
+#   rename_trigger "users", to: "do_something_different" do |t|
+#     t.function "do_something()"
+#     t.for_each :row
+#     t.type :after
+#     t.events %i[insert update]
+#   end
+#
+# In the same way, when you reset the name to default,
+# all the essential parameters must be got to make the trigger
+# invertible.
+#
+#   rename_trigger "users", "do_something" do |t|
+#     t.function "do_something()"
+#     t.for_each :row
+#     t.type :after
+#     t.events %i[insert update]
+#   end
+
+module PGTrunk::Operations::Triggers
+  # @private
+  class RenameTrigger < Base
+    after_initialize { self.new_name = generated_name if new_name.blank? }
+
+    validates :if_exists, :constraint, :initially, :when, :replace_existing, absence: true
+    validates :new_name, presence: true
+
+    def to_sql(_version)
+      <<~SQL.squish
+        ALTER TRIGGER #{name.name.inspect} ON #{table.to_sql}
+        RENAME TO #{new_name.name.inspect};
+      SQL
+    end
+
+    def invert
+      self.class.new(**to_h, name: new_name, to: name)
+    end
+  end
+end

data/lib/pg_trunk/operations/triggers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# nodoc
+module PGTrunk::Operations
+  # @private
+  # Namespace for operations with triggers
+  module Triggers
+    require_relative "triggers/base"
+    require_relative "triggers/change_trigger"
+    require_relative "triggers/create_trigger"
+    require_relative "triggers/drop_trigger"
+    require_relative "triggers/rename_trigger"
+  end
+end

data/lib/pg_trunk/operations/views/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: false
+
+module PGTrunk::Operations::Views
+  # @abstract
+  # @private
+  # Base class for operations with views
+  class Base < PGTrunk::Operation
+    # All attributes that can be used by view-related commands
+    attribute :check, :pg_trunk_symbol
+    attribute :force, :pg_trunk_symbol
+    attribute :replace_existing, :boolean
+    attribute :sql_definition, :pg_trunk_multiline_text
+    attribute :version, :integer, aliases: :revert_to_version
+
+    # Load missed `sql_definition` from the external file
+    after_initialize { self.sql_definition ||= read_snippet_from(:views) }
+
+    # Ensure correctness of present values
+    validates :check, inclusion: %i[local cascaded], allow_nil: true
+    validates :force, inclusion: %i[cascade restrict], allow_nil: true
+
+    # Use comparison by name from pg_trunk operations base class (default)
+    # Support name as the only positional argument (default)
+
+    ruby_snippet do |s|
+      s.ruby_param(name.lean) if name.present?
+      s.ruby_param(to: new_name.lean) if new_name.present?
+      s.ruby_param(replace_existing: true) if replace_existing
+      s.ruby_param(if_exists: true) if if_exists
+      s.ruby_param(force: :cascade) if force == :cascade
+
+      s.ruby_line(:version, version, from: from_version)
+      s.ruby_line(:sql_definition, sql_definition, from: from_sql_definition)
+      s.ruby_line(:check, check, from: from_check)
+      s.ruby_line(:comment, comment, from: from_comment)
+    end
+  end
+end

data/lib/pg_trunk/operations/views/change_view.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#change_view(name, **options, &block)
+# Modify a view
+#
+# @param [#to_s] name (nil) The qualified name of the view
+# @option [Boolean] :if_exists (false) Suppress the error when the view is absent
+# @yield [Proc] the block with the view's definition
+# @yieldparam The receiver of methods specifying the view
+#
+# The operation replaces the view with a new definition(s):
+#
+#   change_view "admin_users" do |v|
+#     v.sql_definition: <<~SQL, from: <<~SQL
+#       SELECT id, name FROM users WHERE admin;
+#     SQL
+#       SELECT * FROM users WHERE admin;
+#     SQL
+#   end
+#
+# For some compatibility to the `scenic` gem, we also support
+# adding a definition via its version:
+#
+#    change_view "admin_users" do |v|
+#      v.version 2, from: 1
+#    end
+#
+# It is expected, that both `db/views/admin_users_v01.sql`
+# and `db/views/admin_users_v02.sql` to contain SQL snippets.
+#
+# Please, notice that neither deletion of columns,
+# nor changing their types is supported by the PostgreSQL.
+#
+# You can also (re)set a comment describing the view,
+# and the check option (either `:local` or `:cascaded`):
+#
+#   change_view "admin_users" do |v|
+#     v.check :local, from: :cascaded
+#     v.comment "Admin users only", from: ""
+#   end
+
+module PGTrunk::Operations::Views
+  # @private
+  class ChangeView < Base
+    validates :replace_existing, :force, :new_name, absence: true
+    validate { errors.add :base, "Changes can't be blank" if changes.blank? }
+    validate do
+      next if if_exists || name.blank?
+
+      errors.add :base, "Can't find the view #{name.lean}" unless create_view
+    end
+
+    def to_sql(server_version)
+      create_view&.to_sql(server_version)
+    end
+
+    def invert
+      irreversible!("if_exists: true") if if_exists
+      undefined = inversion.select { |_, v| v.nil? }.keys.join(", ").presence
+      raise IrreversibleMigration.new(self, nil, <<~MSG.squish) if undefined
+        Undefined values to revert #{undefined}.
+      MSG
+
+      self.class.new(**inversion, name: name)
+    end
+
+    private
+
+    def changes
+      @changes ||= to_h.slice(:sql_definition, :check, :comment).compact
+    end
+
+    def inversion
+      @inversion ||= {}.tap do |inv|
+        inv[:version] = from_version if version
+        inv[:sql_definition] = from_sql_definition unless version
+        inv[:check] = from_check if check
+        inv[:comment] = from_comment if comment
+      end
+    end
+
+    def create_view
+      return if name.blank?
+
+      @create_view ||= CreateView.find { |o| o.name == name }&.tap do |op|
+        op.attributes = { **changes, replace_existing: true }
+      end
+    end
+  end
+end

data/lib/pg_trunk/operations/views/create_view.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#create_view(name, **options, &block)
+# Create a view
+#
+# @param [#to_s] name (nil) The qualified name of the view
+# @option [Boolean] :replace_existing (false) If the view should overwrite an existing one
+# @option [#to_s] :sql_definition (nil) The snippet containing the query
+# @option [#to_i] :version (nil)
+#   The alternative way to set sql_definition by referencing to a file containing the snippet
+# @option [#to_s] :check (nil) Controls the behavior of automatically updatable views
+#   Supported values: :local, :cascaded
+# @option [#to_s] :comment (nil) The comment describing the view
+# @yield [Proc] the block with the view's definition
+# @yieldparam The receiver of methods specifying the view
+#
+# The operation creates the view using its `sql_definition`:
+#
+#   create_view("views.admin_users", sql_definition: <<~SQL)
+#     SELECT id, name FROM users WHERE admin;
+#   SQL
+#
+# For compatibility to the `scenic` gem, we also support
+# adding a definition via its version:
+#
+#    create_view "admin_users", version: 1
+#
+# It is expected, that a `db/views/admin_users_v01.sql`
+# to contain the SQL snippet.
+#
+# You can also set a comment describing the view, and the check option
+# (either `:local` or `:cascaded`):
+#
+#   create_view "admin_users" do |v|
+#     v.sql_definition "SELECT id, name FROM users WHERE admin;"
+#     v.check :local
+#     v.comment "Admin users only"
+#   end
+#
+# With the `replace_existing: true` option the operation
+# would use `CREATE OR REPLACE VIEW` command, so it
+# can be used to "update" (or reload) the existing view.
+#
+#   create_view "admin_users", version: 1, replace_existing: true
+#
+# This option makes an operation irreversible due to uncertainty
+# of the previous state of the database.
+
+module PGTrunk::Operations::Views
+  # @private
+  class CreateView < Base
+    validates :sql_definition, presence: true
+    validates :if_exists, :force, :new_name, absence: true
+
+    from_sql do |_version|
+      <<~SQL
+        SELECT
+          c.oid,
+          (c.relnamespace::regnamespace || '.' || c.relname) AS name,
+          replace(pg_get_viewdef(c.oid, 60), ';', '') AS sql_definition,
+          (
+            SELECT option_value
+            FROM pg_options_to_table(c.reloptions)
+            WHERE option_name = 'check_option'
+            LIMIT 1
+          ) AS check,
+          d.description AS comment
+        FROM pg_class c
+          JOIN pg_trunk e ON e.oid = c.oid
+            AND e.classid = 'pg_class'::regclass
+          LEFT JOIN pg_description d ON d.objoid = c.oid
+            AND d.classoid = 'pg_class'::regclass
+        WHERE c.relkind = 'v';
+      SQL
+    end
+
+    def to_sql(_version)
+      [create_view, *create_comment, register_view].join(" ")
+    end
+
+    def invert
+      irreversible!("replace_existing: true") if replace_existing
+      DropView.new(**to_h)
+    end
+
+    private
+
+    def create_view
+      sql = "CREATE"
+      sql << " OR REPLACE" if replace_existing
+      sql << " VIEW #{name.to_sql}"
+      sql << " AS (#{sql_definition})"
+      sql << " WITH #{check.to_s.upcase} CHECK OPTION" if check.present?
+      sql << ";"
+    end
+
+    def create_comment
+      return if comment.blank?
+
+      "COMMENT ON VIEW #{name.to_sql} IS $comment$#{comment}$comment$;"
+    end
+
+    def register_view
+      <<~SQL.squish
+        INSERT INTO pg_trunk (oid, classid)
+          SELECT oid, 'pg_class'::regclass
+          FROM pg_class
+          WHERE relname = #{name.quoted}
+            AND relnamespace = #{name.namespace}
+            AND relkind = 'v'
+        ON CONFLICT DO NOTHING;
+      SQL
+    end
+  end
+end

data/lib/pg_trunk/operations/views/drop_view.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#drop_view(name, **options, &block)
+# Drop a view
+#
+# @param [#to_s] name (nil) The qualified name of the view
+# @option [Boolean] :replace_existing (false) If the view should overwrite an existing one
+# @option [Boolean] :if_exists (false) Suppress the error when the view is absent
+# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+# @option [#to_s] :sql_definition (nil) The snippet containing the query
+# @option [#to_i] :revert_to_version (nil)
+#   The alternative way to set sql_definition by referencing to a file containing the snippet
+# @option [#to_s] :check (nil) Controls the behavior of automatically updatable views
+#   Supported values: :local, :cascaded
+# @option [#to_s] :comment (nil) The comment describing the view
+# @yield [Proc] the block with the view's definition
+# @yieldparam The receiver of methods specifying the view
+#
+# The operation drops the existing view identified by its
+# qualified name (it can include a schema).
+#
+#   drop_view "views.admin_users"
+#
+# To make the operation invertible, use the same options
+# as in the `create_view` operation.
+#
+#   drop_view "views.admin_users" do |v|
+#     v.sql_definition "SELECT name, email FROM users WHERE admin;"
+#     v.check :local
+#     v.comment "Admin users only"
+#   end
+#
+# You can also use a version-base SQL definition like:
+#
+#    drop_view "views.admin_users", revert_to_version: 1
+#
+# With the `force: :cascade` option the operation would remove
+# all the objects which depend on the view.
+#
+#   drop_view "views.admin_users", force: :cascade
+#
+# With the `if_exists: true` option the operation won't fail
+# even when the view was absent in the database.
+#
+#   drop_view "views.admin_users", if_exists: true
+#
+# Both options make an operation irreversible due to uncertainty
+# of the previous state of the database.
+
+module PGTrunk::Operations::Views
+  # @private
+  class DropView < Base
+    validates :replace_existing, :new_name, absence: true
+
+    def to_sql(_version)
+      sql = "DROP VIEW"
+      sql << " IF EXISTS" if if_exists
+      sql << " #{name.to_sql}"
+      sql << " CASCADE" if force == :cascade
+      sql << ";"
+    end
+
+    def invert
+      irreversible!("if_exists: true") if if_exists
+      irreversible!("force: :cascade") if force == :cascade
+      CreateView.new(**to_h.except(:force))
+    end
+  end
+end