pg_trunk 0.1.0

data/lib/pg_trunk/core/operation/ruby_helpers.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Helpers to build ruby snippet from the operation definition
+  module RubyHelpers
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # The name of the builder
+      # @return [Symbol]
+      def ruby_name
+        @ruby_name ||= name.split("::").last.underscore.to_sym
+      end
+
+      # The name of the inverted builder
+      # @return [Symbol]
+      def ruby_iname
+        "invert_#{ruby_name}".to_sym
+      end
+
+      # Get/set positional params of the ruby method
+      #
+      # @example Provide a method `add_check_constraint(table = nil, **opts)`
+      #   class AddCheckConstraint < PGTrunk::Operation
+      #     ruby_params :table
+      #     # ...
+      #   end
+      #
+      def ruby_params(*params)
+        @ruby_params = params.compact.map(&:to_sym) if params.any?
+        @ruby_params ||= []
+      end
+
+      # Gets or sets the block building a ruby snippet
+      #
+      # @yieldparam [PGTrunk::Operation::RubyBuilder]
+      #
+      # @example
+      #   ruby_snippet do |s|
+      #     s.ruby_param(comment: comment) if comment.present?
+      #     values.each { |v| s.ruby_line(:value, v) }
+      #   end
+      #
+      #   # will build something like
+      #
+      #   do_something "foo.bar", comment: "comment" do |s|
+      #     s.value "baz"
+      #     s.value "qux"
+      #   end
+      def ruby_snippet(&block)
+        @ruby_snippet ||= block
+      end
+
+      # Build the operation from arguments sent to Ruby method
+      def from_ruby(*args, &block)
+        options = args.last.is_a?(Hash) ? args.pop.symbolize_keys : {}
+        params = ruby_params.zip(args).to_h
+        new(**params, **options, &block)
+      end
+
+      private
+
+      def inherited(klass)
+        # Use params from a parent class by default (can be overloaded).
+        klass.instance_variable_set(:@ruby_params, ruby_params)
+        klass.instance_variable_set(:@ruby_snippet, ruby_snippet)
+        super
+      end
+    end
+
+    # @private
+    # Ruby snippet to dump the creator
+    # @return [String]
+    def to_ruby
+      builder = RubyBuilder.new(self.class.ruby_name)
+      instance_exec(builder, &self.class.ruby_snippet)
+      builder.build.rstrip
+    end
+
+    # List of attributes assigned that are assigned
+    # via Ruby method parameters.
+    #
+    # We can use it to announce the operation to $stdout
+    # like `create_foreign_key("users", "roles")`.
+    def to_a
+      to_h.values_at(*self.class.ruby_params)
+    end
+
+    def to_opts
+      to_h.except(*self.class.ruby_params)
+    end
+
+    # @param [IO] stream
+    def dump(stream)
+      to_ruby&.rstrip&.lines&.each { |line| stream.print(line.indent(2)) }
+    end
+  end
+end

data/lib/pg_trunk/core/operation/sql_helpers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Add helpers for building SQL queries
+  module SQLHelpers
+    extend ActiveSupport::Concern
+
+    class_methods do
+      include Enumerable
+
+      # Get/set the block to extract operation definitions
+      # from the database.
+      # @yield [Proc] the block returning sql
+      # @yieldparam [#to_s] version The current version of the database
+      def from_sql(&block)
+        @from_sql = block if block
+        @from_sql ||= nil
+      end
+
+      # Iterate by sorted operation definitions
+      # extracted from the database
+      def each(&block)
+        return to_enum unless block_given?
+
+        fetch
+          .map { |item| new(**item.symbolize_keys) }
+          .sort
+          .each { |op| block.call(op) }
+      end
+
+      private
+
+      def fetch
+        query = from_sql&.call(PGTrunk.database.server_version)
+        query.blank? ? [] : PGTrunk.database.execute(query)
+      end
+    end
+
+    def quote(str)
+      PGTrunk.database.quote(str)
+    end
+  end
+end

data/lib/pg_trunk/core/operation/validations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class PGTrunk::Operation
+  # @private
+  # Enable validation of the operation in the Rails way
+  module Validations
+    extend ActiveSupport::Concern
+
+    class_methods do
+      extend ActiveModel::Validations
+    end
+
+    def error_messages
+      errors.messages.flat_map do |k, v|
+        Array(v).map do |msg|
+          k == :base ? msg : [k, msg].join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/pg_trunk/core/operation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: false
+
+require_relative "operation/callbacks"
+require_relative "operation/attributes"
+require_relative "operation/generators"
+require_relative "operation/validations"
+require_relative "operation/inversion"
+require_relative "operation/ruby_builder"
+require_relative "operation/ruby_helpers"
+require_relative "operation/sql_helpers"
+require_relative "operation/registration"
+
+module PGTrunk
+  # @private
+  # Base class for operations.
+  # Inherit this class to define new operation.
+  class Operation
+    include Callbacks
+    include Attributes
+    include Generators
+    include Comparable
+    include Validations
+    include Inversion
+    include RubyHelpers
+    include SQLHelpers
+    include Registration
+
+    attribute :comment, :string, desc: \
+              "The comment to the object"
+    attribute :force, :pg_trunk_symbol, desc: \
+              "How to process dependent objects"
+    attribute :if_exists, :boolean, desc: \
+              "Don't fail if the object is absent"
+    attribute :if_not_exists, :boolean, desc: \
+              "Don't fail if the object is already present"
+    attribute :name, :pg_trunk_qualified_name, desc: \
+              "The qualified name of the object"
+    attribute :new_name, :pg_trunk_qualified_name, aliases: :to, desc: \
+              "The new name of the object to rename to"
+    attribute :oid, :integer, desc: \
+              "The oid of the database object"
+    attribute :version, :integer, aliases: :revert_to_version, desc: \
+              "The version of the SQL snippet"
+
+    validates :name, presence: true
+    validates :new_name, "PGTrunk/difference": { from: :name }, allow_nil: true
+    validates :force, inclusion: { in: %i[cascade restrict] }, allow_nil: true
+
+    # By default ruby methods take the object name as a positional argument.
+    ruby_params :name
+
+    protected
+
+    # Define the order of objects
+    # @param [PGTrunk::Definitions]
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      name <=> other.name if other.is_a?(self.class)
+    end
+
+    private
+
+    # Helper to read a versioned snippet for a specific
+    # kind of objects
+    def read_snippet_from(kind)
+      return if kind.blank? || name.blank? || version.blank?
+
+      filename = format(
+        "db/%<kind>s/%<name>s_v%<version>02d.sql",
+        kind: kind.to_s.pluralize,
+        name: name.routine,
+        version: version,
+      )
+      filepath = Rails.root.join(filename)
+      File.read(filepath).sub(/;\s*$/, "")
+    end
+  end
+end

data/lib/pg_trunk/core/qualified_name.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # The qualified name of an object consists from schema (namespace) and name.
+  # The class contains several helper methods for ruby and sql snippets.
+  QualifiedName = Struct.new(:schema, :name) do
+    include Comparable
+
+    # Build qualified name structure from a string
+    #
+    # @example
+    #   QualifiedName["bar"].to_h
+    #   # => { schema: "public", name: "bar" }
+    #
+    #   QualifiedName["foo.bar(a int, b int)"].to_h
+    #   # => { schema: "foo", name: "bar(a int, b int)" }
+    #
+    def self.wrap(string)
+      schema = /^([^.(]+)[.]/.match(string).to_a[1]
+      name = string.sub(/^[^.(]*[.]/, "")
+      new(schema, name)
+    end
+
+    # Get the current schema
+    def current_schema
+      @current_schema ||= PGTrunk.database.current_schema
+    end
+
+    private def initialize(schema, name)
+      super(schema.to_s.presence || current_schema, name.to_s.presence)
+    end
+
+    # If the schema is current (which is usually 'public')
+    # This schema would be ignored in +lean+
+    def current_schema?
+      schema == current_schema
+    end
+
+    # If the qualified name is blank (not specified)
+    def blank?
+      routine.blank?
+    end
+
+    # If the name matches the regex
+    def match?(regex)
+      routine.match?(regex)
+    end
+
+    # If the name is present but not matches the regexp
+    # (used to check if it is not generated by some pattern)
+    def differs_from?(regex)
+      !routine.match?(regex) if present?
+    end
+
+    # Quoted representation of the name for SQL snippets
+    #
+    #   QualifiedName.wrap("foo.bar(a int, OUT b int) record").to_sql
+    #   # => '"foo"."bar" (a int)'
+    #
+    #   qname = QualifiedName.wrap("public.foo")
+    #   qname.to_sql
+    #   # => '"foo"'
+    #   qname.to_sql(true)
+    #   # => '"foo"()'
+    def to_sql(with_args = nil)
+      @to_sql ||= begin
+        str = [
+          *(schema unless current_schema?),
+          routine,
+        ].map(&:inspect).join(".")
+        str = "#{str} (#{args})" if args.present? || with_args
+        str
+      end
+    end
+
+    # The qualified name with unquoted parts
+    # (to be used in ruby snippets)
+    #
+    #   QualifiedName.wrap("bar.foo").full
+    #   # => "bar.foo"
+    #
+    #   QualifiedName.wrap("public.foo(int, int) int").full
+    #   # => "foo(int, int) int"
+    def full
+      @full ||= [schema, name].join(".")
+    end
+
+    # Exclude current schema from a qualified name
+    #
+    #   QualifiedName.wrap("public.foo").lean
+    #   # => "foo"
+    #
+    #   QualifiedName.wrap("bar.baz").lean
+    #   # => "bar.baz"
+    def lean
+      @lean ||= [*(schema unless current_schema?), name].join(".")
+    end
+
+    # Name of the routine for function definition
+    #   QualifiedName.wrap("foo.bar(a int, b int) int").routine
+    #   # => "bar"
+    def routine
+      @routine ||= name[/^[^(]+/]&.strip
+    end
+
+    # Args from the function definition
+    #   QualifiedName.wrap("foo.bar(a int, b int DEFAULT = 0) int").args
+    #   # => "a int, b int DEFAULT = 0"
+    def args
+      @args ||= name&.match(/\(([^)]+)/).to_a.last&.gsub(/\s+/, " ")&.strip
+    end
+
+    # Arg types from the function definition
+    #   QualifiedName.wrap("foo.bar(a int, b int DEFAULT = 0) int").args
+    #   # => %w[int int]
+    def arg_types
+      @arg_types ||= args.to_s.split(",").map { |a| a.strip.split(/\s+/).last }
+    end
+
+    # Type of returned value of a routine
+    #   QualifiedName.wrap("foo.concat(a int, b int) text").returns
+    #   # => "text"
+    def returns
+      @returns ||= name&.match(/\)(.+)/).to_a.last&.strip
+    end
+
+    # Quote the name (to compare to text fields in the database)
+    #   QualifiedName.wrap("foo.concat(a int, b int) text").quoted
+    #   # => "'concat'"
+    def quoted
+      @quoted ||= PGTrunk.database.quote(routine)
+    end
+
+    # Transform the namespace (to compare to oid fields in the database)
+    #   QualifiedName.wrap("foo.bar").namespace
+    #   # => "'foo'::regnamespace"
+    def namespace
+      @namespace ||= "#{PGTrunk.database.quote(schema)}::regnamespace"
+    end
+
+    # Make qualified names comparable by their full representation
+    # @return [Integer, NilClass]
+    def <=>(other)
+      sort_order <=> other.sort_order if other.is_a?(self.class)
+    end
+
+    # Checks if partially qualified <function>
+    # have the same schema/name as another function
+    def maybe_eq?(other)
+      sort_order.first(2) == other.sort_order.first(2)
+    end
+
+    # Build the name with a changed part (either a name or a schema)
+    def merge(**args)
+      self.class.new(args.fetch(:schema, schema), args.fetch(:name, name))
+    end
+
+    protected
+
+    def sort_order
+      [schema.to_s, routine.to_s, *arg_types]
+    end
+  end
+end

data/lib/pg_trunk/core/railtie/command_recorder.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # The module record commands done during a migration.
+  module CommandRecorder
+    # @param [PGTrunk::Operation] klass
+    def self.register(klass)
+      define_method(klass.ruby_name) do |*args, &block|
+        record(klass.ruby_name, args, &block)
+      end
+    end
+
+    # @param [PGTrunk::Operation] klass
+    def self.register_inversion(klass)
+      define_method(klass.ruby_iname) do |args, &block|
+        original = klass.from_ruby(*args, &block)
+        inverted = original.invert!
+        # for example (skip_inversion(:validate_foreign_key))
+        return [:skip_inversion, [klass.ruby_name]] unless inverted
+
+        # list of attributes `to_a` is added for reporting to stdout
+        params = inverted.to_a
+        opts = inverted.to_opts
+        params << opts if opts.present?
+        [inverted.class.ruby_name, params]
+      end
+    end
+  end
+end

data/lib/pg_trunk/core/railtie/custom_types.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # The module adds custom type casting
+  module CustomTypes
+    # All custom types are typecasted to strings in Rails
+    TYPE = ActiveRecord::ConnectionAdapters::PostgreSQL::OID::SpecializedString
+
+    def self.known
+      @known ||= Set.new([])
+    end
+
+    def enable_pg_trunk_types
+      execute(<<~SQL).each { |item| enable_pg_trunk_type item["name"] }
+        SELECT (
+          CASE
+          WHEN t.typnamespace = 'public'::regnamespace THEN t.typname
+          ELSE t.typnamespace::regnamespace || '.' || t.typname
+          END
+        ) AS name
+        FROM pg_trunk e JOIN pg_type t ON t.oid = e.oid
+        WHERE e.classid = 'pg_type'::regclass
+      SQL
+    end
+
+    def enable_pg_trunk_type(type)
+      type = type.to_s
+      CustomTypes.known << type
+      type_map.register_type(type, TYPE.new(type)) unless type_map.key?(type)
+    end
+
+    def valid_type?(type)
+      CustomTypes.known.include?(type.to_s) || super
+    end
+  end
+end

data/lib/pg_trunk/core/railtie/migration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # The module goes around the ActiveRecord::Migration's `method_missing`.
+  #
+  # This is necessary because +ActiveRecord::Migration#method_missing+
+  # forces the first argument to be a proper table name.
+  #
+  # In Rails migrations the first argument specifies the +table+,
+  # while the +name+ of the object can be specified by option:
+  #
+  #    pg_trunk_create_index :users, %w[id name], name: 'users_idx'
+  #
+  # in PGTrunk the positional argument is always specify the name
+  # of the the current object (type, function, table etc.):
+  #
+  #    pg_trunk_create_index 'users_ids', table: 'users', columns: %w[id name]
+  #    create_enum 'currency', values: %w[USD EUR BTC]
+  #
+  # With this fix we can also use the options-only syntax like:
+  #
+  #    pg_trunk_create_enum name: 'currency', values: %w[USD EUR BTC]
+  #
+  # or even skip any name when it can be generated from options:
+  #
+  #    pg_trunk_create_index do |i|
+  #      i.table 'users'
+  #      i.column 'id'
+  #    end
+  #
+  module Migration
+    # @param [PGTrunk::Operation] klass
+    def self.register(klass)
+      define_method(klass.ruby_name) do |*args, &block|
+        say_with_time "#{klass.ruby_name}(#{_pretty_args(*args)})" do
+          connection.send(klass.ruby_name, *args, &block)
+        end
+      end
+    end
+
+    private
+
+    def _pretty_args(*args)
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      opts = opts.map { |k, v| "#{k}: #{v.inspect}" if v.present? }.compact
+      [*args.map(&:inspect), *opts].join(", ")
+    end
+  end
+end

data/lib/pg_trunk/core/railtie/migrator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # This module extends the ActiveRecord::Migrator
+  # to clean the gem-specific registry `pg_trunk`:
+  #
+  # - set version to rows added by the current migration
+  # - delete rows that refer to objects deleted by the migration
+  #
+  # We need this because some objects (like check constraints,
+  # indexes etc.) can be dropped along with the table
+  # they refer to. This depencency is implicit-ish.
+  # That's why we have to check the presence of all objects in `pg_trunk`
+  # after every single migration.
+  module Migrator
+    def record_version_state_after_migrating(*)
+      super
+      PGTrunk::Registry.finalize
+    end
+  end
+end

data/lib/pg_trunk/core/railtie/schema_dumper.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # Overloads methods defined in ActiveRecord::SchemaDumper
+  # to redefine how various objects must be dumped.
+  module SchemaDumper
+    class << self
+      def operations
+        @operations ||= []
+      end
+
+      def register(operation)
+        operations << operation unless operations.include?(operation)
+      end
+    end
+
+    # Here we totally redefining the way a schema is dumped.
+    #
+    # In Rails every table definition is dumped as an `add_table`
+    # creator including all its columns, indexes, type casts and foreign keys.
+    #
+    # In some circumstances, these objects can have inter-dependencies
+    # with others (like functions, custom types and constraints).
+    # For example, we could define a function getting table raw as an argument,
+    # and then use this function to define check constraint for the table.
+    # In this case we must insert the definition of the function between
+    # the table's and constraint's ones.
+    #
+    # That's why we can neither rely on the method, defined in ActiveRecord
+    # nor reuse it through fallback to `super` like both Scenic and F(x) do.
+    # Instead of it, we fetch object definitions from the database,
+    # and then resolve their inter-dependencies.
+    def dump(stream)
+      pg_trunk_register_custom_types
+      header(stream)
+      extensions(stream)
+      pg_trunk_objects(stream)
+      trailer(stream)
+      stream
+    end
+
+    private
+
+    # Before dumping the schema extract from SQL all custom types
+    # to enable their usage in table columns in the schema.
+    def pg_trunk_register_custom_types
+      @connection.enable_pg_trunk_types
+    end
+
+    def pg_trunk_objects(stream)
+      # Fetch operation definitions from the database.
+      #
+      # Operations of different kind are fetched
+      # in the order of their definitions (see `lib/pg_trunk/definitions.rb`).
+      # Operations of the same kind are sorted in a kind-specific order.
+      operations = SchemaDumper.operations.flat_map(&:to_a)
+      # Limit operations by oids known in `pg_trunk`
+      oids = PGTrunk::Registry.pluck(:oid)
+      operations = operations.select { |op| oids.include?(op.oid) }
+      # Resolve dependencies between fetched commands.
+      operations = PGTrunk::DependenciesResolver.resolve(operations)
+      # provide the content of the schema.
+      operations.each do |cmd|
+        cmd.dump(stream)
+        stream.puts
+        stream.puts
+      end
+    end
+
+    # Prevent indexes and check constraints from being added to the table
+    def indexes_in_create(_table, _stream); end
+    def check_constraints_in_create(_table, _stream); end
+  end
+end

data/lib/pg_trunk/core/railtie/schema_migration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # The module makes `pg_trunk` gem-specific registry
+  # to be created and dropped along with the native schema.
+  module SchemaMigration
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def create_table
+        super
+        PGTrunk::Registry.create_table
+      end
+
+      def drop_table
+        PGTrunk::Registry.drop_table
+        super
+      end
+    end
+  end
+end

data/lib/pg_trunk/core/railtie/statements.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # The module adds commands to execute DDL operations in PostgreSQL.
+  module Statements
+    # @param [PGTrunk::Operation] klass
+    def self.register(klass)
+      define_method(klass.ruby_name) do |*args, &block|
+        operation = klass.from_ruby(*args, &block)
+        operation.validate!
+        PGTrunk.database.execute_operation(operation)
+      end
+    end
+
+    # A command does nothing when a unidirectional command is inverted
+    # (for example, when a foreign key validation is inverted).
+    # This case is different from those when an inversion cannot be made.
+    def skip_inversion(*); end
+  end
+end