pg_trunk 0.1.0

data/lib/pg_trunk/operations/statistics/create_statistics.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#create_statistics(name, **options, &block)
+# Create a custom statistics
+#
+# @param [#to_s] name (nil) The qualified name of the statistics
+# @option [Boolean] :if_not_exists (false)
+#   Suppress the error when the statistics is already exist
+# @option [#to_s] table (nil)
+#   The qualified name of the table whose statistics will be collected
+# @option [Array<Symbol>] kinds ([:dependencies, :mcv, :ndistinct])
+#   The kinds of statistics to be collected (all by default).
+#   Supported values in the array: :dependencies, :mcv, :ndistinct
+# @option [#to_s] :comment The description of the statistics
+# @yield [Proc] the block with the statistics' definition
+# @yieldparam The receiver of methods specifying the statistics
+#
+# The statistics can be created with explicit name:
+#
+#   create_statistics "users_stats" do |s|
+#     s.table "users"
+#     s.columns "family", "name"
+#     s.kinds :dependencies, :mcv, :ndistinct
+#     s.comment "Statistics for users' names and families"
+#   SQL
+#
+# The name can be generated as well:
+#
+#   create_statistics do |s|
+#     s.table "users"
+#     s.columns "family", "name"
+#     s.kinds :dependencies, :mcv, :ndistinct
+#     s.comment "Statistics for users' names and families"
+#   SQL
+#
+# Since v14 PostgreSQL have supported expressions in addition to columns:
+#
+#   create_statistics "users_stats" do |s|
+#     s.table "users"
+#     s.columns "family"
+#     s.expression "length(name)"
+#     s.kinds :dependencies, :mcv, :ndistinct
+#     s.comment "Statistics for users' name lengths and families"
+#   SQL
+#
+# as well as statistics for the sole expression (kinds must be blank)
+# by columns of some table.
+#
+#   create_statistics "users_stats" do |s|
+#     s.table "users"
+#     s.expression "length(name || ' ' || family)"
+#     s.comment "Statistics for full name lengths"
+#   SQL
+#
+# Use `if_not_exists: true` to suppress error in case the statistics
+# has already been created. This option, though, makes the migration
+# irreversible due to uncertainty of the previous state of the database.
+
+module PGTrunk::Operations::Statistics
+  # SQL snippet to fetch statistics in v10-13
+  SQL_V10 = <<~SQL.freeze
+    WITH
+      list (key, name) AS (
+        VALUES ('m', 'mcv'), ('f', 'dependencies'), ('d', 'ndistinct')
+      )
+    SELECT
+      s.oid,
+      (s.stxnamespace::regnamespace || '.' || s.stxname) AS name,
+      (t.relnamespace::regnamespace || '.' || t.relname) AS "table",
+      (
+        SELECT array_agg(l.name)
+        FROM list l
+        WHERE ARRAY[l.key]::char[] <@ s.stxkind::char[]
+      ) AS kinds,
+      (
+        SELECT array_agg(DISTINCT a.attname)
+        FROM pg_attribute a
+        WHERE a.attrelid = s.stxrelid
+          AND ARRAY[a.attnum]::int[] <@ s.stxkeys::int[]
+      ) AS columns,
+      d.description AS comment
+    FROM pg_statistic_ext s
+      JOIN pg_trunk e ON e.oid = s.oid AND e.classid = 'pg_statistic_ext'::regclass
+      JOIN pg_class t ON t.oid = s.stxrelid
+      LEFT JOIN pg_description d ON d.objoid = s.oid;
+  SQL
+
+  # In version 14 statistics can be collected for expressions.
+  SQL_V14 = <<~SQL.freeze
+    WITH
+      list (key, name) AS (
+        VALUES ('m', 'mcv'), ('f', 'dependencies'), ('d', 'ndistinct')
+      )
+    SELECT
+      s.oid,
+      (s.stxnamespace::regnamespace || '.' || s.stxname) AS name,
+      (t.relnamespace::regnamespace || '.' || t.relname) AS "table",
+      (
+        SELECT array_agg(l.name)
+        FROM list l
+        WHERE ARRAY[l.key]::char[] <@ s.stxkind::char[]
+      ) AS kinds,
+      (
+        SELECT array_agg(DISTINCT a.attname)
+        FROM pg_attribute a
+        WHERE a.attrelid = s.stxrelid
+          AND ARRAY[a.attnum]::int[] <@ s.stxkeys::int[]
+      ) AS columns,
+      pg_get_expr(s.stxexprs, stxrelid, true) AS expressions,
+      d.description AS comment
+    FROM pg_statistic_ext s
+      JOIN pg_trunk e ON e.oid = s.oid AND e.classid = 'pg_statistic_ext'::regclass
+      JOIN pg_class t ON t.oid = s.stxrelid
+      LEFT JOIN pg_description d ON d.objoid = s.oid;
+  SQL
+
+  # @private
+  class CreateStatistics < Base
+    validates :if_exists, :force, :new_name, absence: true
+    validates :table, presence: true
+    validate do
+      errors.add :base, "Columns and expressions can't be blank" if parts.blank?
+    end
+
+    from_sql do |version|
+      version >= "14" ? SQL_V14 : SQL_V10
+    end
+
+    def to_sql(version)
+      check_version!(version)
+
+      [create_statistics, *create_comment, register_object].join(" ")
+    end
+
+    def invert
+      irreversible!("if_not_exists: true") if if_not_exists
+      DropStatistics.new(**to_h)
+    end
+
+    private
+
+    def check_version!(version)
+      raise <<~ERROR.squish if version < "14" && expressions.present?
+        Statistics for expressions are supported in PostgreSQL v14+"
+      ERROR
+
+      raise <<~ERROR.squish if version < "12" && kinds.include?(:mcv)
+        The `mcv` kind is supported in PostgreSQL v12+
+      ERROR
+    end
+
+    def create_statistics
+      sql = "CREATE STATISTICS"
+      sql << " IF NOT EXISTS" if if_not_exists
+      sql << " #{name.to_sql}"
+      sql << " (#{kinds.join(',')})" if kinds.present?
+      sql << " ON #{parts.join(', ')}"
+      sql << "FROM #{table.to_sql};"
+    end
+
+    def create_comment
+      return if comment.blank?
+
+      "COMMENT ON STATISTICS #{name.to_sql} IS $comment$#{comment}$comment$;"
+    end
+
+    def register_object
+      <<~SQL
+        INSERT INTO pg_trunk(oid, classid)
+        SELECT s.oid, 'pg_statistic_ext'::regclass
+        FROM pg_statistic_ext s
+          JOIN pg_class t ON t.oid = s.stxrelid
+        WHERE s.stxname = #{name.quoted}
+          AND s.stxnamespace = #{name.namespace}
+          AND t.relname = #{table.quoted}
+          AND t.relnamespace = #{table.namespace}
+        ON CONFLICT DO NOTHING;
+      SQL
+    end
+  end
+end

data/lib/pg_trunk/operations/statistics/drop_statistics.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#drop_statistics(name, **options, &block)
+# Drop a custom statistics
+#
+# @param [#to_s] name (nil) The qualified name of the statistics
+# @option [Boolean] :if_exists (false) Suppress the error when the statistics is absent
+# @option [Symbol] :force (:restrict) How to process dependent objects (`:cascade` or `:restrict`)
+# @option [#to_s] table (nil)
+#   The qualified name of the table whose statistics will be collected
+# @option [Array<Symbol>] kinds ([:dependencies, :mcv, :ndistinct])
+#   The kinds of statistics to be collected (all by default).
+#   Supported values in the array: :dependencies, :mcv, :ndistinct
+# @option [#to_s] :comment The description of the statistics
+# @yield [Proc] the block with the statistics' definition
+# @yieldparam The receiver of methods specifying the statistics
+#
+# A statistics can be dropped by its name only:
+#
+#   drop_statistics "my_stats"
+#
+# Such operation is irreversible. To make it inverted
+# you have to provide a full definition:
+#
+#   drop_statistics "users_stat" do |s|
+#     s.table "users"
+#     s.columns "firstname", "name"
+#     s.expression <<~SQL
+#       round(age, 10)
+#     SQL
+#     s.kinds :dependency, :mcv, :ndistinct
+#     p.comment "Statistics for name, firstname, and rough age"
+#   SQL
+#
+# If the statistics was anonymous (used the generated name),
+# it can be dropped without defining the name as well:
+#
+#   drop_statistics do |s|
+#     s.table "users"
+#     s.columns "firstname", "name"
+#     s.expression <<~SQL
+#       round(age, 10)
+#     SQL
+#     s.kinds :dependency, :mcv, :ndistinct
+#     p.comment "Statistics for name, firstname, and rough age"
+#   SQL
+#
+# The operation can be called with `if_exists` option. In this case
+# it would do nothing when no statistics existed.
+#
+#   drop_procedure "unknown_statistics", if_exists: true
+#
+# Notice, that this option make the operation irreversible because of
+# uncertainty about the previous state of the database.
+
+module PGTrunk::Operations::Statistics
+  # @private
+  class DropStatistics < Base
+    validates :if_not_exists, :new_name, absence: true
+
+    def to_sql(_version)
+      sql = "DROP STATISTICS"
+      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
+      CreateStatistics.new(**to_h.except(:force))
+    end
+  end
+end

data/lib/pg_trunk/operations/statistics/rename_statistics.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: false
+
+# @!method ActiveRecord::Migration#rename_statistics(name, to:)
+# Change the name and/or schema of a statistics
+#
+# @param [#to_s] :name (nil) The qualified name of the statistics
+# @option [#to_s] :to (nil) The new qualified name for the statistics
+#
+# A custom statistics can be renamed by changing both the name
+# and the schema (namespace) it belongs to.
+#
+#   rename_statistics "math.my_stat", to: "public.my_stats"
+#
+# The operation is always reversible.
+
+module PGTrunk::Operations::Statistics
+  # @private
+  class RenameStatistics < Base
+    after_initialize { self.new_name ||= generated_name }
+
+    validates :new_name, presence: true
+    validates :if_exists, :if_not_exists, :force, absence: true
+
+    def to_sql(_version)
+      [*change_schema, *change_name].join("; ")
+    end
+
+    def invert
+      q_new_name = "#{new_name.schema}.#{new_name.routine}(#{name.args}) #{name.returns}"
+      self.class.new(**to_h, name: q_new_name.strip, to: name)
+    end
+
+    private
+
+    def change_schema
+      return if name.schema == new_name.schema
+
+      "ALTER STATISTICS #{name.to_sql} SET SCHEMA #{new_name.schema.inspect};"
+    end
+
+    def change_name
+      return if new_name.routine == name.routine
+
+      changed_name = name.merge(schema: new_name.schema).to_sql
+      "ALTER STATISTICS #{changed_name} RENAME TO #{new_name.routine.inspect};"
+    end
+  end
+end

data/lib/pg_trunk/operations/statistics.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# nodoc
+module PGTrunk::Operations
+  # @private
+  # Namespace for operations with functions
+  module Statistics
+    require_relative "statistics/base"
+    require_relative "statistics/create_statistics"
+    require_relative "statistics/drop_statistics"
+    require_relative "statistics/rename_statistics"
+  end
+end

data/lib/pg_trunk/operations/tables/create_table.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PGTrunk::Operations::Tables
+  # @private
+  #
+  # When dealing with tables we're only interested in
+  # dumping tables one-by-one to enable other operations
+  # in between tables.
+  #
+  # We doesn't overload the method `create_table`, but
+  # keep the original implementation unchanged. That's why
+  # neither `to_sql`, `invert` or `generates_object` are necessary.
+  #
+  # While we rely on the original implementation,
+  # there are some differences in a way we fetching
+  # tables and dumping them to the schema:
+  #
+  # - we extracting both qualified +name+ and +oid+ for every table,
+  #   and checking them against the content of `pg_trunk`;
+  # - we wrap every table new_name this class for dependencies resolving;
+  # - we don't keep indexes and check constraints
+  #   inside the table definitions because they can depend
+  #   on functions which, in turn, can depend on tables.
+  #
+  class CreateTable < PGTrunk::Operation
+    # No other attributes except for the mandatory `name` and `oid` are needed.
+    # We also use default ordering by qualified names.
+    validates :oid, presence: true
+
+    # SQL to fetch table names and oids from the database.
+    # We rely on the fact all tables of interest are registered in `pg_trunk`.
+    from_sql do
+      <<~SQL
+        SELECT
+          c.oid,
+          (c.relnamespace::regnamespace || '.' || c.relname) AS name
+        FROM pg_class c JOIN pg_trunk p ON p.oid = c.oid
+        -- 'r' for tables and 'p' for partitions
+        WHERE c.relkind IN ('r', 'p')
+      SQL
+    end
+
+    # Instead of defining +ruby_snippet+, we overload
+    # the +to_ruby+ to rely on the original implementation.
+    #
+    # We overloaded the +ActiveRecord::SchemaDumper+
+    # methods +indexes_in_create+ and +check_constraints_in_create+
+    # so that they do nothing to exclude indexes and constraints
+    # from a table definition.
+    #
+    # @see +PGTrunk::SchemaDumper+ module (in `core/railtie`).
+    def to_ruby
+      stream = StringIO.new
+      PGTrunk.dumper.send(:table, name.lean, stream)
+      unindent(stream.string)
+    end
+
+    private
+
+    # ActiveRecord builds the dump indented by 2 space chars.
+    # Because the +to_ruby+ method is used in error messages,
+    # we do indentation separately in the +PGTrunk::SchemaDumper+.
+    #
+    # That's why we have to unindent the original snippet
+    # provided by the +ActiveRecord::Dumper##table+ method call
+    # back by 2 space characters.
+    #
+    # The `.strip << "\n"` is added for the compatibility
+    # with the +RubyBuilder+ which returns snippets
+    # having one trailing newline only.
+    def unindent(snippet)
+      snippet.lines.map { |line| line.sub(/^ {1,2}/, "") }.join.strip << "\n"
+    end
+  end
+end

data/lib/pg_trunk/operations/tables.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# nodoc
+module PGTrunk::Operations
+  # @private
+  # Namespace for operations with tables
+  module Tables
+    require_relative "tables/create_table"
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: false
+
+module PGTrunk::Operations::Triggers
+  # @abstract
+  # @private
+  # Base class for operations with triggers
+  class Base < PGTrunk::Operation
+    # All attributes that can be used by trigger-related commands
+    attribute :columns, :pg_trunk_array_of_strings, default: []
+    attribute :constraint, :boolean
+    attribute :events, :pg_trunk_array_of_symbols, default: []
+    attribute :for_each, :pg_trunk_symbol
+    attribute :function, :pg_trunk_qualified_name
+    attribute :initially, :pg_trunk_symbol
+    attribute :replace_existing, :boolean
+    attribute :table, :pg_trunk_qualified_name
+    attribute :type, :pg_trunk_symbol
+    attribute :when, :string
+
+    # Generate missed name of the trigger
+    after_initialize { self.name = generated_name if name.blank? }
+    after_initialize { self.type ||= :after if constraint }
+    after_initialize { self.for_each ||= :row if constraint }
+
+    # Ensure correctness of present values
+    validates :table, presence: true
+    validates :for_each, inclusion: { in: %i[row statement] }, allow_nil: true
+    validates :initially, inclusion: { in: %i[immediate deferred] }, allow_nil: true
+    validates :type, inclusion: { in: %i[after before instead_of] }, allow_nil: true
+    validates :events,
+              inclusion: { in: %i[insert update delete truncate] },
+              allow_blank: true
+    validate do
+      next if name.blank?
+
+      errors.add :name, "can't have a schema" unless name.current_schema?
+    end
+    validate do
+      next unless initially && !constraint
+
+      errors.add :initially, "can be used for constraints only"
+    end
+    validate do
+      next unless columns.present? && type == :instead_of
+
+      errors.add :columns,
+                 "can be defined for before/after update triggers only"
+    end
+    validate do
+      next unless constraint && type != :after && for_each != :row
+
+      errors.add :base, "Only AFTER EACH ROW triggers can be constraints"
+    end
+    validate do
+      next unless self.when && type == :instead_of
+
+      errors.add :when, "is not supported for INSTEAD OF triggers"
+    end
+    validate do
+      next if new_name.blank? || new_name.current_schema?
+
+      errors.add :base, "New name can't specify the schema"
+    end
+
+    # triggers are ordered by table and name
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      result = table <=> other.table
+      result.zero? ? super : result
+    end
+
+    # Support `table` and `name` in positional arguments.
+    # @example
+    #   add_trigger :users, :my_trigger, **opts
+    ruby_params :table, :name
+
+    ruby_snippet do |s|
+      s.ruby_param(table.lean) if table.present?
+      s.ruby_param(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(:replace_existing, true) if replace_existing
+
+      s.ruby_line(:function, function.lean) if function.present?
+      s.ruby_line(:when, self.when)
+      s.ruby_line(:constraint, true) if constraint
+      s.ruby_line(:for_each, for_each) if for_each&.== :row
+      s.ruby_line(:type, type) if type.present?
+      s.ruby_line(:events, events) if events.present?
+      s.ruby_line(:columns, columns) if columns.present?
+      s.ruby_line(:initially, initially)
+      s.ruby_line(:comment, comment, from: from_comment)
+    end
+
+    private
+
+    # Generate the name of the trigger 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, function, type, events].any?(&:blank?)
+
+        key_options = to_h.reject { |_, v| v.blank? }.slice(
+          :table, :function, :for_each, :type, :events,
+        )
+        identifier = "#{table.lean}_#{key_options}_tg"
+        hashed_identifier = Digest::SHA256.hexdigest(identifier).first(10)
+        PGTrunk::QualifiedName.wrap("tg_rails_#{hashed_identifier}")
+      end
+    end
+
+    def custom_name?(qname = name)
+      qname&.differs_from?(/^tg_rails_\w{10}$/)
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# 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] :if_exists (false) Suppress the error when the trigger is absent
+# @yield [Proc] the block with the trigger's definition
+# @yieldparam The receiver of methods specifying the trigger
+#
+# The trigger can be changed using `CREATE OR REPLACE TRIGGER` command:
+#
+#   change_trigger "users", "do_something" do |t|
+#     t.function "do_something()", from: "do_something_different()"
+#     t.for_each :row # from: :statement
+#     t.type :after, from: :before
+#     t.events %i[insert update], from: %i[insert]
+#     t.comment "Does something useful", from: ""
+#   end
+
+module PGTrunk::Operations::Triggers
+  # @private
+  class ChangeTrigger < Base
+    validates :replace_existing, :new_name, :version, absence: true
+    validate { errors.add :base, "Changes can't be blank" if changes.blank? }
+    validate do
+      next if if_exists
+
+      errors.add :base, "The trigger cannot be found" unless create_trigger
+    end
+
+    def to_sql(server_version)
+      return create_trigger&.to_sql(server_version) if server_version >= "14"
+
+      raise "The operation is supported by PostgreSQL server v14+"
+    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, table: table, name: name)
+    end
+
+    private
+
+    def changes
+      @changes ||= {
+        type: type.presence,
+        events: events.presence,
+        columns: columns.presence,
+        constraint: constraint,
+        for_each: for_each,
+        function: function.presence,
+        initially: initially,
+        when: self.when.presence,
+        comment: comment,
+      }.compact
+    end
+
+    def inversion
+      changes
+        .each_with_object({}) { |(k, _), obj| obj[k] = send(:"from_#{k}") }
+        .tap do |i|
+          i[:for_each] ||= (%i[statement row] - [for_each]).first if for_each
+        end
+    end
+
+    def create_trigger
+      return if name.blank? || table.blank?
+
+      @create_trigger ||=
+        CreateTrigger
+        .find { |o| o.name == name && o.table == table }
+        &.tap { |o| o.attributes = { **changes, replace_existing: true } }
+    end
+  end
+end