pg_trunk 0.1.0

data/lib/pg_trunk/operations/enums/change_enum.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#change_enum(name, &block)
+# Modify an enumerated type
+#
+# @param [#to_s] name (nil) The qualified name of the type
+# @yield [Proc] the block with the type's definition
+# @yieldparam The receiver of methods specifying the type
+#
+# The operation can be used to rename or add values to the
+# enumerated type. The commend can be changed as well.
+#
+#   change_enum "currencies" do |e|
+#     e.add_value "EUR", after: "BTC"
+#     e.add_value "GBP", before: "usd"
+#     e.add_value "JPY" # to the end of the list
+#     e.rename_value "usd", to: "USD"
+#     e.comment <<~COMMENT, from: <<~COMMENT
+#       Supported currencies
+#     COMMENT
+#       Currencies
+#     COMMENT
+#   end
+#
+# Please, keep in mind that all values will be added before
+# the first rename. That's why you should use old values
+# (like the `usd` instead of the `USD` in the example above)
+# in `before` and `after` options.
+#
+# Also notice that PostgreSQL doesn't support value deletion,
+# that's why adding any value makes the migration irreversible.
+#
+# It is also irreversible if you changed the comment, but
+# not defined its previous value.
+
+module PGTrunk::Operations::Enums
+  # @private
+  class ChangeEnum < Base
+    # Add new value (irreversible!)
+    # If neither option is specified, the value will be added
+    # to the very end of the array.
+    # Notice, that all add-ons are made BEFORE renames.
+    def add_value(name, after: nil, before: nil)
+      changes << Change.new(name: name, after: after, before: before)
+    end
+
+    # Rename the value to new unique name (reversible)
+    def rename_value(name, to: nil)
+      changes << Change.new(name: name, new_name: to)
+    end
+
+    validates :if_exists, :force, :values, :new_name, absence: true
+    validate do
+      next if comment.present? || changes.present?
+
+      errors.add :base, "There are no changes"
+    end
+
+    def to_sql(version)
+      raise <<~MSG.squish if version < "12" && changes.any?(&:add?)
+        Adding new values to enumerable types inside a migration
+        is supported in PostgreSQL v12+.
+      MSG
+
+      [*add_values, *rename_values, *change_comment].join(" ")
+    end
+
+    def invert
+      values_added = changes.any?(&:add?)
+      raise IrreversibleMigration.new(self, nil, <<~MSG.squish) if values_added
+        Removal of values from enumerated type is not supported by PostgreSQL,
+        that's why adding new values can't be reverted.
+      MSG
+
+      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(**to_h, **inversion)
+    end
+
+    def to_h
+      super.tap { |data| data[:changes]&.map!(&:to_h) }
+    end
+
+    private
+
+    def add_values
+      changes.select(&:add?).map do |change|
+        "ALTER TYPE #{name.to_sql} #{change.to_sql};"
+      end
+    end
+
+    def rename_values
+      changes.select(&:rename?).map do |change|
+        "ALTER TYPE #{name.to_sql} #{change.to_sql};"
+      end
+    end
+
+    def change_comment
+      return unless comment # empty string is processed
+
+      "COMMENT ON TYPE #{name.to_sql} IS $comment$#{comment}$comment$;"
+    end
+
+    def change
+      @change ||= {
+        changes: changes.map(&:to_h).presence, comment: comment,
+      }.compact
+    end
+
+    def inversion
+      @inversion ||= {
+        changes: changes.reverse.map(&:invert).presence, comment: from_comment,
+      }.slice(*change.keys)
+    end
+  end
+end

data/lib/pg_trunk/operations/enums/create_enum.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#create_enum(name, **options, &block)
+# Create an enumerated type by qualified name
+#
+# @param [#to_s] name (nil) The qualified name of the type
+# @option [Array<#to_s>] :values ([]) The list of values
+# @option [#to_s] :comment (nil) The comment describing the constraint
+# @yield [Proc] the block with the type's definition
+# @yieldparam The receiver of methods specifying the type
+#
+# @example
+#
+#   create_enum "finances.currency" do |e|
+#     e.values "BTC", "EUR", "GBP", "USD"
+#     e.value "JPY" # the alternative way to add a value to the tail
+#     e.comment <<~COMMENT
+#       The list of values for supported currencies.
+#     COMMENT
+#   end
+#
+# It is always reversible.
+
+module PGTrunk::Operations::Enums
+  # @private
+  class CreateEnum < Base
+    validates :values, presence: true
+    validates :changes, :force, :if_exists, :new_name, absence: true
+
+    from_sql do |_version|
+      <<~SQL
+        SELECT
+          t.oid,
+          (t.typnamespace::regnamespace || '.' || t.typname) AS name,
+          array_agg(n.enumlabel ORDER BY n.enumsortorder) AS values,
+          d.description AS comment
+        FROM pg_type t
+          JOIN pg_trunk e ON e.oid = t.oid AND e.classid = 'pg_type'::regclass
+          LEFT JOIN pg_enum n ON n.enumtypid = t.oid
+          LEFT JOIN pg_description d ON d.objoid = t.oid
+            AND d.classoid = 'pg_type'::regclass
+        WHERE t.typtype = 'e'
+        GROUP BY t.oid, t.typnamespace, t.typname, d.description
+      SQL
+    end
+
+    def to_sql(_version)
+      [create_enum, *create_comment, register_enum].join(" ")
+    end
+
+    def invert
+      DropEnum.new(**to_h)
+    end
+
+    private
+
+    def create_enum
+      <<~SQL.squish
+        CREATE TYPE #{name.to_sql} AS ENUM (
+          #{values.map { |value| "'#{value}'" }.join(', ')}
+        );
+      SQL
+    end
+
+    def create_comment
+      return if comment.blank?
+
+      "COMMENT ON TYPE #{name.to_sql} IS $comment$#{comment}$comment$;"
+    end
+
+    def register_enum
+      <<~SQL.squish
+        INSERT INTO pg_trunk (oid, classid)
+          SELECT oid, 'pg_type'::regclass
+          FROM pg_type
+          WHERE typname = #{name.quoted}
+            AND typnamespace = #{name.namespace}
+            AND typtype = 'e'
+        ON CONFLICT DO NOTHING;
+      SQL
+    end
+  end
+end

data/lib/pg_trunk/operations/enums/drop_enum.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#drop_enum(name, **options, &block)
+# Drop an enumerated type by qualified name
+#
+# @param [#to_s] name (nil) The qualified name of the type
+# @option [Boolean] :if_exists (false) Suppress the error when the type is absent
+# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+# @option [Array<#to_s>] :values ([]) The list of values
+# @option [#to_s] :comment (nil) The comment describing the constraint
+# @yield [Proc] the block with the type's definition
+# @yieldparam The receiver of methods specifying the type
+#
+# The operation drops a enumerated type identified by its
+# qualified name (it can include a schema).
+#
+#   drop_enum "finances.currency"
+#
+# To make the operation invertible, use the same options
+# as in the `create_enum` operation.
+#
+#   drop_enum "finances.currency" do |e|
+#     e.values "BTC", "EUR", "GBP", "USD"
+#     e.value "JPY" # the alternative way to add a value
+#     e.comment <<~COMMENT
+#       The list of values for supported currencies.
+#     COMMENT
+#   end
+#
+# With the `force: :cascade` option the operation would remove
+# all the objects that use the type.
+#
+#   drop_enum "finances.currency", force: :cascade
+#
+# With the `if_exists: true` option the operation won't fail
+# even when the view was absent in the database.
+#
+#   drop_enum "finances.currency", if_exists: true
+#
+# Both options make a migration irreversible due to uncertainty
+# of the previous state of the database.
+
+module PGTrunk::Operations::Enums
+  # @private
+  class DropEnum < Base
+    # Forbid these attributes
+    validates :changes, :new_name, absence: true
+
+    def to_sql(_version)
+      sql = "DROP TYPE"
+      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
+      CreateEnum.new(**to_h.except(:force))
+    end
+  end
+end

data/lib/pg_trunk/operations/enums/rename_enum.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#rename_enum(name, to:)
+# Change the name and/or schema of an enumerated type
+#
+# @param [#to_s] :name (nil) The qualified name of the type
+# @option [#to_s] :to (nil) The new qualified name for the type
+#
+# @example:
+#
+#   rename_enum "currencies", to: "finances.currency"
+#
+# The operation is always reversible.
+
+module PGTrunk::Operations::Enums
+  # @private
+  class RenameEnum < Base
+    validates :new_name, presence: true
+    validates :force, :if_exists, :values, :changes, absence: true
+
+    def to_sql(_version)
+      [*change_schema, *change_name].join("; ")
+    end
+
+    def invert
+      self.class.new(**to_h, name: new_name, to: name)
+    end
+
+    private
+
+    def change_schema
+      return if name.schema == new_name.schema
+
+      "ALTER TYPE #{name.to_sql} SET SCHEMA #{new_name.schema.inspect};"
+    end
+
+    def change_name
+      return if new_name.name == name.name
+
+      moved = name.merge(schema: new_name.schema)
+      "ALTER TYPE #{moved.to_sql} RENAME TO #{new_name.name.inspect};"
+    end
+  end
+end

data/lib/pg_trunk/operations/enums.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# nodoc
+module PGTrunk::Operations
+  # @private
+  # Namespace for operations with functions
+  module Enums
+    require_relative "enums/change"
+    require_relative "enums/base"
+    require_relative "enums/change_enum"
+    require_relative "enums/create_enum"
+    require_relative "enums/drop_enum"
+    require_relative "enums/rename_enum"
+  end
+end

data/lib/pg_trunk/operations/foreign_keys/add_foreign_key.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#add_foreign_key(table, reference, **options, &block)
+# Create a foreign key constraint
+#
+# @param [#to_s] table (nil) The qualified name of the table
+# @param [#to_s] reference (nil) The qualified name of the reference table
+# @option [#to_s] :name (nil) The current name of the foreign key
+# @option [#to_s] :to (nil) The new name for the foreign key
+# @option [Array<#to_s>] :columns ([]) The list of columns of the table
+# @option [#to_s] :column (nil) An alias for :columns for the case of single-column keys
+# @option [Array<#to_s>] :primary_key ([]) The list of columns of the reference table
+# @option [Symbol] :match (:full) Define how to match rows
+#   Supported values: :full (default), :partial, :simple
+# @option [Symbol] :on_delete (:restrict)
+#   Define how to handle the deletion of the referred row.
+#   Supported values: :restrict (default), :cascade, :nullify, :reset
+# @option [Symbol] :on_update (:restrict)
+#   Define how to handle the update of the referred row.
+#   Supported values: :restrict (default), :cascade, :nullify, :reset
+# @yield [Proc] the block with the key's definition
+# @yieldparam The receiver of methods specifying the foreign key
+#
+# The table and reference of the new key must be set explicitly.
+# All the rest (including the name) can be generated by default:
+#
+#   # same as `..., column: 'role_id', primary_key: 'id'`
+#   add_foreign_key :users, :roles
+#
+# The block syntax can be used for any argument:
+#
+#   add_foreign_key do |c|
+#     c.table "users"
+#     c.reference "roles"
+#     c.column "role_id" # (generated by default from reference and pk)
+#     c.primary_key "id" # (default)
+#     c.on_update :cascade # :restrict (default)
+#     c.on_delete :cascade # :restrict (default)
+#     c.name "user_roles_fk" # can be generated
+#     c.comment "Phone is 10+ chars long"
+#   end
+#
+# Composite foreign keys are supported as well:
+#
+#   add_foreign_key "users", "roles" do |c|
+#     c.columns %w[role_name role_id]
+#     c.primary_key %w[name id] # Requires unique index
+#     c.match :full # :partial, :simple (default)
+#   end
+#
+# The operation is always invertible.
+
+module PGTrunk::Operations::ForeignKeys
+  # @private
+  class AddForeignKey < Base
+    # The operation used by the generator `rails g foreign_key`
+    generates_object :foreign_key
+
+    # New name is generated from the full signature
+    # including table, reference, columns and primary_key.
+    after_initialize { self.name = generated_name if name.blank? }
+
+    validates :reference, presence: true
+    validates :if_exists, :new_name, absence: true
+
+    from_sql do
+      <<~SQL
+        SELECT
+          c.oid,
+          c.conname AS name,
+          c.connamespace::regnamespace AS schema,
+          (t.relnamespace::regnamespace || '.' || t.relname) AS "table",
+          (r.relnamespace::regnamespace || '.' || r.relname) AS "reference",
+          (
+            SELECT array_agg(attname)
+            FROM (
+              SELECT a.attname
+              FROM unnest(c.conkey) b(i) JOIN pg_attribute a ON a.attnum = b.i
+              WHERE a.attrelid = c.conrelid
+              ORDER BY array_position(c.conkey, b.i)
+            ) list
+          ) AS columns,
+          (
+            SELECT array_agg(attname)
+            FROM (
+              SELECT a.attname
+              FROM unnest(c.confkey) b(i) JOIN pg_attribute a ON a.attnum = b.i
+              WHERE a.attrelid = c.confrelid
+              ORDER BY array_position(c.confkey, b.i)
+            ) list
+          ) AS primary_key,
+          (
+            CASE
+              WHEN c.confupdtype = 'r' THEN 'restrict'
+              WHEN c.confupdtype = 'c' THEN 'cascade'
+              WHEN c.confupdtype = 'n' THEN 'nullify'
+              WHEN c.confupdtype = 'd' THEN 'reset'
+            END
+          ) AS on_update,
+          (
+            CASE
+              WHEN c.confdeltype = 'r' THEN 'restrict'
+              WHEN c.confdeltype = 'c' THEN 'cascade'
+              WHEN c.confdeltype = 'n' THEN 'nullify'
+              WHEN c.confdeltype = 'd' THEN 'reset'
+            END
+          ) AS on_delete,
+          (
+            CASE
+            WHEN c.confmatchtype = 's' THEN 'simple'
+            WHEN c.confmatchtype = 'f' THEN 'full'
+            WHEN c.confmatchtype = 'p' THEN 'partial'
+            END
+          ) AS match,
+          c.convalidated AS validate,
+          d.description AS comment
+        FROM pg_constraint c
+          JOIN pg_class t ON t.oid = c.conrelid
+          JOIN pg_class r ON r.oid = c.confrelid
+          LEFT JOIN pg_description d ON d.objoid = c.oid
+        WHERE c.contype = 'f';
+      SQL
+    end
+
+    def to_sql(_version)
+      # Notice that in Rails the key `if_not_exists: true` means
+      # the constraint should not be created if the table has ANY other
+      # foreign key with the same reference <table>.
+      return if if_not_exists && added?
+
+      [add_constraint, create_comment, register_fk].join(" ")
+    end
+
+    def invert
+      irreversible!("if_not_exists: true") if if_not_exists
+      DropForeignKey.new(**to_h)
+    end
+
+    private
+
+    def add_constraint
+      sql = "ALTER TABLE #{table.to_sql} ADD CONSTRAINT #{name.lean.inspect}"
+      sql << " FOREIGN KEY (#{columns.map(&:inspect).join(', ')})"
+      sql << " REFERENCES #{reference.to_sql} (#{primary_key.map(&:inspect).join(', ')})"
+      sql << " MATCH #{match.to_s.upcase}" if match&.!= :simple
+      sql << " ON DELETE #{sql_action(on_delete)}"
+      sql << " ON UPDATE #{sql_action(on_update)}"
+      sql << " NOT VALID" unless validate
+      sql << ";"
+    end
+
+    def create_comment
+      return if comment.blank?
+
+      <<~SQL
+        COMMENT ON CONSTRAINT #{name.lean.inspect} ON #{table.to_sql}
+        IS $comment$#{comment}$comment$;
+      SQL
+    end
+
+    # Rely on the fact the (schema.table, schema.name) is unique
+    def register_fk
+      <<~SQL
+        INSERT INTO pg_trunk (oid, classid)
+          SELECT c.oid, 'pg_constraint'::regclass
+          FROM pg_constraint c JOIN pg_class r ON r.oid = c.conrelid
+          WHERE r.relname = #{table.quoted}
+            AND r.relnamespace = #{table.namespace}
+            AND c.conname = #{name.quoted}
+        ON CONFLICT DO NOTHING;
+      SQL
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: false
+
+module PGTrunk::Operations::ForeignKeys
+  # @abstract
+  # @private
+  # Base class for operations with foreign keys
+  class Base < PGTrunk::Operation
+    # All attributes that can be used by fk-related commands
+    attribute :columns, :pg_trunk_array_of_strings, aliases: :column, default: []
+    attribute :match, :pg_trunk_symbol
+    attribute :on_delete, :pg_trunk_symbol
+    attribute :on_update, :pg_trunk_symbol
+    attribute :primary_key, :pg_trunk_array_of_strings, default: %(id)
+    attribute :reference, :pg_trunk_qualified_name
+    attribute :table, :pg_trunk_qualified_name
+    attribute :validate, :boolean, default: true
+
+    # Generate missed columns from the reference ant its foreign keys.
+    # The generation of the missed name is operation-specific.
+    after_initialize { self.columns = generated_columns if columns.blank? }
+
+    # Ensure correctness of present values
+    # The table must be defined because the name only
+    # is not enough to identify the key.
+    validates :table, presence: true
+    validates :force, absence: true
+    validates :match, inclusion: { in: %i[full partial simple] }, allow_nil: true
+    validates :on_update, :on_delete,
+              inclusion: { in: %i[restrict cascade nullify reset] },
+              allow_nil: true
+
+    # By default foreign keys are sorted by tables and names.
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      result = table <=> other.table
+      result.zero? ? super : result
+    end
+
+    # Support `table` and `reference` in positional arguments.
+    # @example
+    #   add_foreign_key :users, :roles, **opts
+    ruby_params :table, :reference
+
+    ruby_snippet do |s|
+      s.ruby_param(table.lean) if table.present?
+      s.ruby_param(reference.lean) if reference.present?
+      unless default_columns?
+        s.ruby_param(column: columns.first) if columns.size == 1
+        s.ruby_param(columns: columns) if columns.size > 1
+      end
+      unless default_pkey?
+        s.ruby_param(primary_key: primary_key.first) if primary_key.size == 1
+        s.ruby_param(primary_key: primary_key) if primary_key.size > 1
+      end
+      s.ruby_param(match: match) if match&.!= :simple
+      s.ruby_param(on_update: on_update) if on_update
+      s.ruby_param(on_delete: on_delete) if on_delete
+      s.ruby_param(name: name.lean) if custom_name?
+      s.ruby_param(to: new_name.lean) if custom_name?(new_name)
+      s.ruby_param(if_exists: true) if if_exists
+      s.ruby_param(comment: comment) if comment.present?
+    end
+
+    private
+
+    # ***********************************************************************
+    # Helpers for operation definitions
+    # ***********************************************************************
+
+    # @param [#reference] operation
+    # @return [Array<String>]
+    def generated_columns
+      return @generated_columns if instance_variable_defined?(:@generated_columns)
+
+      @generated_columns = begin
+        return if reference.blank? || primary_key.blank?
+
+        prefix =
+          PGTrunk
+          .database
+          .strip_table_name(reference.name)
+          .to_s
+          .singularize
+
+        primary_key.map { |pk| "#{prefix}_#{pk}" }
+      end
+    end
+
+    # Generate the name for the foreign key using the essential options
+    # @return [PGTrunk::QualifiedName]
+    def generated_name
+      return @generated_name if instance_variable_defined?(:@generated_name)
+
+      @generated_name = begin
+        return if table.blank? || reference.blank?
+        return if primary_key.blank? || columns.blank?
+
+        key_options = to_h.slice(:reference, :columns, :primary_key)
+        identifier = "#{table.lean}_#{key_options}_fk"
+        hashed_identifier = Digest::SHA256.hexdigest(identifier).first(10)
+        PGTrunk::QualifiedName.wrap("fk_rails_#{hashed_identifier}")
+      end
+    end
+
+    # Check if the fk name wasn't generated by Rails
+    # @param [#name] operation The operation
+    # @return [Boolean]
+    def custom_name?(qname = name)
+      qname&.differs_from?(/^fk_rails_\w+$/)
+    end
+
+    # Check if the only column is custom
+    # @param [#table, #reference, #columns, #primary_key] operation
+    def default_columns?
+      columns == generated_columns
+    end
+
+    # Check if columns are default for the reference
+    # @param [#table, #reference, #columns, #primary_key] operation
+    def default_pkey?
+      primary_key == %w[id]
+    end
+
+    # Notice that in Rails the key `if_not_exists: true` means that
+    # the constraint should not be created if the table has ANY
+    # fk reference to the other table (even though the keys differ).
+    #
+    # @param [#table, #reference] operation
+    # @return [Boolean]
+    def added?
+      PGTrunk.database.foreign_key_exists?(table.name, reference.name)
+    end
+
+    # Add a name of the existing foreign key
+    def current_name
+      @current_name ||= AddForeignKey.find do |fk|
+        fk.table == table &&
+          fk.columns == columns &&
+          fk.reference == reference &&
+          fk.primary_key == primary_key
+      end&.name
+    end
+
+    def sql_action(key)
+      case key
+      when :nullify then "SET NULL"
+      when :reset then "SET DEFAULT"
+      when :restrict then "RESTRICT"
+      when :cascade then "CASCADE"
+      else "NO ACTION"
+      end
+    end
+  end
+end