pg_plan_advice 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aff6f2b8f2ed0785002aa93c01c373f2c5ba3c38d1e4c8d8cf946b88f78d8670
+  data.tar.gz: 2a42b924f30b8ab9c945bae2860c04834fb2878ee45359d6a1d170a13b424470
+SHA512:
+  metadata.gz: a74380e604022b8a264c8d15fe9a1c05226562bcd1784531190861492c88dbba785dae1576520dd4f644849d91f2ee7d8038377ad44a4864481b8cd37e8251e2
+  data.tar.gz: 2f9b62b68344ccbf8ab308068e5c3eee742ef6af98d2066702846eb49149c6c9f4c8c29551164257cb43801af53d1ff284154a2092b1ee8af776673a1f7580f0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 moozzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# PgPlanAdvice
+
+ActiveRecord DSL for PostgreSQL pg_plan_advice.
+
+> [!WARNING]
+> This gem is in active development. The API may change without notice and it should not be used in production.
+
+## Installation
+
+Requirements:
+
+- Ruby >= 3.2
+- ActiveRecord 7.2
+- PostgreSQL 19 with the `pg_plan_advice` module loaded (for example via `shared_preload_libraries`), see the [PostgreSQL documentation](https://www.postgresql.org/docs/devel/pgplanadvice.html)
+
+Add the gem to your application's Gemfile:
+
+```bash
+bundle add pg_plan_advice
+```
+
+or install it from git:
+
+```ruby
+gem "pg_plan_advice"
+```
+
+## Usage
+
+### ActiveRecord
+
+Call `plan_advice` on a model or a relation and describe the advice in a block:
+
+```ruby
+Post.joins(:comments).plan_advice do
+  join_order :posts, :comments
+  hash_join :comments
+  seq_scan :posts
+end
+```
+
+The relation above runs with:
+
+```
+JOIN_ORDER(posts comments) HASH_JOIN(comments) SEQ_SCAN(posts)
+```
+
+### Groups
+
+Use `ordered` and `unordered` to build target groups:
+
+```ruby
+Post.plan_advice do
+  join_order :posts, ordered(:comments, unordered(:users, :tags))
+  nested_loop_plain ordered(:comments, :users)
+  foreign_join ordered(:remote_a, :remote_b)
+end
+# JOIN_ORDER(posts (comments {users tags})) NESTED_LOOP_PLAIN((comments users)) FOREIGN_JOIN((remote_a remote_b))
+```
+
+### Index advice
+
+`index_scan` and `index_only_scan` take a hash of target to index name:
+
+```ruby
+Post.plan_advice do
+  index_scan posts: :index_posts_on_user_id
+end
+# INDEX_SCAN(posts index_posts_on_user_id)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run the tests:
+
+```bash
+bundle exec rspec
+```
+
+Run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/moozzi/pg_plan_advice/issues.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+eval_gemfile "../Gemfile"
+
+gem "activerecord", "~> 7.2.0"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+eval_gemfile "../Gemfile"
+
+gem "activerecord", "~> 8.0.0"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+eval_gemfile "../Gemfile"
+
+gem "activerecord", "~> 8.1.0"

data/lib/pg_plan_advice/ar/execution.rb

@@ -0,0 +1,94 @@
+module PgPlanAdvice
+  module AR
+    module Execution
+      GUC = "pg_plan_advice.advice"
+      MIN_SERVER_VERSION = 190_000
+
+      SUPPORT = ObjectSpace::WeakMap.new
+
+      def self.with_advice(connection, advice)
+        return yield if advice.nil? || advice.empty?
+        return yield unless usable?(connection)
+
+        if connection.transaction_open?
+          previous = connection.select_value("SELECT current_setting('#{GUC}', true)")
+          apply(connection, advice)
+
+          begin
+            yield
+          ensure
+            restore(connection, previous)
+          end
+        else
+          connection.transaction do
+            apply(connection, advice)
+            yield
+          end
+        end
+      end
+
+      def self.usable?(connection)
+        support = support_for(connection)
+        return true if support == :supported
+
+        if PgPlanAdvice.on_unsupported == :raise
+          raise UnsupportedDatabaseError, unsupported_message(connection, support)
+        end
+
+        false
+      end
+
+      def self.support_for(connection)
+        return SUPPORT[connection] if SUPPORT.key?(connection)
+
+        support = detect_support(connection)
+        warn_unsupported(connection, support)
+        SUPPORT[connection] = support
+      end
+
+      def self.detect_support(connection)
+        return :adapter unless postgresql?(connection)
+        return :version if connection.database_version < MIN_SERVER_VERSION
+        return :module if connection.select_value("SELECT 1 FROM pg_settings WHERE name = '#{GUC}'").nil?
+
+        :supported
+      end
+
+      def self.postgresql?(connection)
+        defined?(::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter) &&
+          connection.is_a?(::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter)
+      end
+
+      def self.warn_unsupported(connection, support)
+        return if support == :supported || PgPlanAdvice.on_unsupported != :warn
+
+        ::ActiveRecord::Base.logger&.warn("#{unsupported_message(connection, support)}, running queries without advice")
+      end
+
+      def self.unsupported_message(connection, support)
+        case support
+        when :adapter
+          "pg_plan_advice requires PostgreSQL, got: #{connection.adapter_name}"
+        when :version
+          "pg_plan_advice requires PostgreSQL 19 or newer, got: #{server_version(connection.database_version)}"
+        when :module
+          "pg_plan_advice module is not loaded, load it with shared_preload_libraries"
+        end
+      end
+
+      def self.server_version(version_num)
+        "#{version_num / 10_000}.#{version_num % 10_000}"
+      end
+
+      def self.apply(connection, value)
+        connection.select_value("SELECT set_config('#{GUC}', #{connection.quote(value)}, true)")
+      end
+
+      def self.restore(connection, value)
+        apply(connection, value)
+      rescue ::ActiveRecord::StatementInvalid
+        # ?
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ar/querying.rb

@@ -0,0 +1,9 @@
+module PgPlanAdvice
+  module AR
+    module Querying
+      def plan_advice(&blk)
+        all.plan_advice(&blk)
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ar/relation.rb

@@ -0,0 +1,39 @@
+module PgPlanAdvice
+  module AR
+    module Relation
+      attr_accessor :plan_advice_value
+
+      def plan_advice(&blk)
+        advice = PgPlanAdvice.build(resolver: Resolver.new(klass), &blk)
+        spawn.tap do |rel|
+          rel.plan_advice_value = plan_advice_value ? plan_advice_value.merge(advice) : advice
+        end
+      end
+
+      def exec_explain(...) = with_plan_advice { super }
+      def pluck(...)        = with_plan_advice { super }
+      def exists?(...)      = with_plan_advice { super }
+      def update_all(...)   = with_plan_advice { super }
+      def delete_all(...)   = with_plan_advice { super }
+      def calculate(...)    = with_plan_advice { super }
+
+      private
+
+      def with_plan_advice(&blk)
+        return yield unless plan_advice_value
+
+        klass.with_connection do |conn|
+          Execution.with_advice(conn, plan_advice_value.to_s, &blk)
+        end
+      end
+
+      def exec_main_query(*args, **kwargs, &blk)
+        return super unless plan_advice_value
+
+        klass.with_connection do |conn|
+          Execution.with_advice(conn, plan_advice_value.to_s) { super(*args, **kwargs, &blk) }
+        end
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ar/resolver.rb

@@ -0,0 +1,20 @@
+module PgPlanAdvice
+  module AR
+    class Resolver
+      def initialize(model)
+        @model = model
+      end
+
+      def resolve(item)
+        name = case item
+               when Class  then item.table_name
+               when Symbol then @model.reflect_on_association(item)&.klass&.table_name || item.to_s
+               when String then item
+               else raise InvalidAdviceError, "Invalid advice target: #{item.inspect}"
+               end
+
+        Ast::Target.new(alias_name: name)
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast/advice_set.rb

@@ -0,0 +1,33 @@
+module PgPlanAdvice
+  module Ast
+    class AdviceSet
+      attr_reader :nodes
+
+      def initialize(nodes)
+        @nodes = nodes
+      end
+
+      def to_s
+        @nodes.map { |node| "#{node.class.tag}(#{serialize_targets(node.targets)})" }.join(" ")
+      end
+
+      def merge(advice_set)
+        self.class.new(nodes + advice_set.nodes)
+      end
+
+      private
+
+      def serialize_targets(targets)
+        targets.map do |target|
+          case target
+          when Ast::Target         then target.to_s
+          when Ast::IndexTarget    then "#{serialize_targets([target.target])} #{target.index_name}"
+          when Ast::OrderedGroup   then "(#{serialize_targets(target.items)})"
+          when Ast::UnorderedGroup then "{#{serialize_targets(target.items)}}"
+          else raise InvalidAdviceError, "unable to serialize: #{target.class}"
+          end
+        end.join(" ")
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast/bitmap_heap_scan.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class BitmapHeapScan < Node
+      accepts Target
+      advice_name "BITMAP_HEAP_SCAN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/do_not_scan.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class DoNotScan < Node
+      accepts Target
+      advice_name "DO_NOT_SCAN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/foreign_join.rb

@@ -0,0 +1,15 @@
+module PgPlanAdvice
+  module Ast
+    class ForeignJoin < Node
+      accepts OrderedGroup
+      advice_name "FOREIGN_JOIN"
+
+      def initialize(targets:)
+        super
+
+        single = targets.select { _1.items.one? }
+        invalid!("targets must contain more than one relation identifier, got: #{single.inspect}") if single.any?
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast/gather.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class Gather < Node
+      accepts Target, OrderedGroup
+      advice_name "GATHER"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/gather_merge.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class GatherMerge < Node
+      accepts Target, OrderedGroup
+      advice_name "GATHER_MERGE"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/hash_join.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class HashJoin < Node
+      accepts Target, OrderedGroup
+      advice_name "HASH_JOIN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/index_only_scan.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class IndexOnlyScan < Node
+      accepts IndexTarget
+      advice_name "INDEX_ONLY_SCAN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/index_scan.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class IndexScan < Node
+      accepts IndexTarget
+      advice_name "INDEX_SCAN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/index_target.rb

@@ -0,0 +1,20 @@
+module PgPlanAdvice
+  module Ast
+    class IndexTarget < Data.define(:target, :index_name)
+      def initialize(target:, index_name:)
+        unless target.is_a?(Target)
+          raise InvalidAdviceError, "Index advice target must be a single target, got #{target.inspect}"
+        end
+
+        index_name = index_name.to_s
+        raise InvalidAdviceError, "Index name must not be empty" if index_name.empty?
+
+        super(target:, index_name: index_name.freeze)
+      end
+
+      def to_s
+        "#{target} #{index_name}"
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast/join_order.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class JoinOrder < Node
+      accepts Target, OrderedGroup, UnorderedGroup, allow_nesting: true
+      advice_name "JOIN_ORDER"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/merge_join_materialize.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class MergeJoinMaterialize < Node
+      accepts Target, OrderedGroup
+      advice_name "MERGE_JOIN_MATERIALIZE"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/merge_join_plain.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class MergeJoinPlain < Node
+      accepts Target, OrderedGroup
+      advice_name "MERGE_JOIN_PLAIN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/nested_loop_materialize.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class NestedLoopMaterialize < Node
+      accepts Target, OrderedGroup
+      advice_name "NESTED_LOOP_MATERIALIZE"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/nested_loop_memoize.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class NestedLoopMemoize < Node
+      accepts Target, OrderedGroup
+      advice_name "NESTED_LOOP_MEMOIZE"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/nested_loop_plain.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class NestedLoopPlain < Node
+      accepts Target, OrderedGroup
+      advice_name "NESTED_LOOP_PLAIN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/no_gather.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class NoGather < Node
+      accepts Target
+      advice_name "NO_GATHER"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/node.rb

@@ -0,0 +1,62 @@
+module PgPlanAdvice
+  module Ast
+    class Node < Data.define(:targets)
+      class << self
+        attr_reader :tag
+
+        def accepts(*matchers, allow_nesting: false)
+          @accepted = matchers.freeze
+          @allow_nesting = allow_nesting
+        end
+
+        def advice_name(tag)
+          @tag = tag
+        end
+
+        def accepts?(item)
+          @accepted.any? { _1 === item }
+        end
+
+        def nesting_in?(group)
+          @allow_nesting && group.is_a?(OrderedGroup)
+        end
+      end
+
+      def initialize(targets:)
+        invalid!("targets must not be empty") if targets.empty?
+
+        unexpected = targets.reject { self.class.accepts?(_1) }
+        invalid!("accepts only target, got: #{unexpected.inspect}") if unexpected.any?
+
+        validate_groups!(targets)
+
+        super(targets: targets.dup.freeze)
+      end
+
+      private
+
+      def validate_groups!(items)
+        items.select { group?(_1) }.each do |group|
+          nesting = self.class.nesting_in?(group)
+          unexpected = group.items.reject { _1.is_a?(Target) || (nesting && group?(_1)) }
+          invalid_group!(group, nesting, unexpected) if unexpected.any?
+
+          validate_groups!(group.items)
+        end
+      end
+
+      def invalid_group!(group, nesting, unexpected)
+        allowed = nesting ? "targets and groups" : "targets"
+        invalid!("#{group.class.name.split("::").last} may contain only #{allowed}, got: #{unexpected.inspect}")
+      end
+
+      def group?(item)
+        item.is_a?(OrderedGroup) || item.is_a?(UnorderedGroup)
+      end
+
+      def invalid!(message)
+        raise InvalidAdviceError, "#{self.class.tag} #{message}"
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast/ordered_group.rb

@@ -0,0 +1,11 @@
+module PgPlanAdvice
+  module Ast
+    OrderedGroup = Data.define(:items) do
+      def initialize(items:)
+        raise InvalidAdviceError, "OrderedGroup must not be empty" if items.empty?
+
+        super
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast/partitionwise.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class Partitionwise < Node
+      accepts Target, OrderedGroup
+      advice_name "PARTITIONWISE"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/semijoin_non_unique.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class SemijoinNonUnique < Node
+      accepts Target, OrderedGroup
+      advice_name "SEMIJOIN_NON_UNIQUE"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/semijoin_unique.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class SemijoinUnique < Node
+      accepts Target, OrderedGroup
+      advice_name "SEMIJOIN_UNIQUE"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/seq_scan.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class SeqScan < Node
+      accepts Target
+      advice_name "SEQ_SCAN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/target.rb

@@ -0,0 +1,39 @@
+module PgPlanAdvice
+  module Ast
+    Target = Data.define(:alias_name, :occurrence_number, :partition_schema, :partition_name, :plan_name) do
+      def initialize(alias_name:, occurrence_number: nil, partition_schema: nil, partition_name: nil, plan_name: nil)
+        invalid!("alias_name can't be empty") if alias_name.empty?
+
+        if partition_schema.nil? != partition_name.nil?
+          invalid!("partition_schema and partition_name must be given together")
+        end
+
+        unless occurrence_number.nil? || positive_integer?(occurrence_number)
+          invalid!("occurrence_number must be a positive integer, got: #{occurrence_number.inspect}")
+        end
+
+        super
+      end
+
+      def to_s
+        result = alias_name.to_s
+        result += "##{occurrence_number}" if occurrence_number
+        result += "/#{partition_schema}" if partition_schema
+        result += ".#{partition_name}" if partition_name
+        result += "@#{plan_name}" if plan_name
+
+        result
+      end
+
+      private
+
+      def positive_integer?(value)
+        value.is_a?(Integer) && value.positive?
+      end
+
+      def invalid!(message)
+        raise InvalidAdviceError, "Target #{message}"
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast/tid_scan.rb

@@ -0,0 +1,8 @@
+module PgPlanAdvice
+  module Ast
+    class TidScan < Node
+      accepts Target
+      advice_name "TID_SCAN"
+    end
+  end
+end

data/lib/pg_plan_advice/ast/unordered_group.rb

@@ -0,0 +1,11 @@
+module PgPlanAdvice
+  module Ast
+    UnorderedGroup = Data.define(:items) do
+      def initialize(items:)
+        raise InvalidAdviceError, "UnorderedGroup must not be empty" if items.empty?
+
+        super
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/ast.rb

@@ -0,0 +1,32 @@
+require_relative "./ast/node"
+require_relative "./ast/target"
+require_relative "./ast/index_target"
+require_relative "./ast/ordered_group"
+require_relative "./ast/unordered_group"
+
+require_relative "./ast/advice_set"
+require_relative "./ast/bitmap_heap_scan"
+require_relative "./ast/do_not_scan"
+require_relative "./ast/foreign_join"
+require_relative "./ast/gather"
+require_relative "./ast/gather_merge"
+require_relative "./ast/hash_join"
+require_relative "./ast/index_only_scan"
+require_relative "./ast/index_scan"
+require_relative "./ast/join_order"
+require_relative "./ast/merge_join_materialize"
+require_relative "./ast/merge_join_plain"
+require_relative "./ast/nested_loop_materialize"
+require_relative "./ast/nested_loop_memoize"
+require_relative "./ast/nested_loop_plain"
+require_relative "./ast/no_gather"
+require_relative "./ast/partitionwise"
+require_relative "./ast/semijoin_non_unique"
+require_relative "./ast/semijoin_unique"
+require_relative "./ast/seq_scan"
+require_relative "./ast/tid_scan"
+
+module PgPlanAdvice
+  module Ast
+  end
+end

data/lib/pg_plan_advice/builder.rb

@@ -0,0 +1,142 @@
+require_relative "./ast"
+require_relative "./default_resolver"
+
+module PgPlanAdvice
+  class Builder
+    def initialize(resolver: DefaultResolver.new)
+      @items = []
+      @resolver = resolver
+    end
+
+    #
+    # Scan method advice
+    #
+    # SEQ_SCAN(target [ ... ])
+    # TID_SCAN(target [ ... ])
+    # INDEX_SCAN(target index_name [ ... ])
+    # INDEX_ONLY_SCAN(target index_name [ ... ])
+    # FOREIGN_JOIN((target [ ... ]) [ ... ])
+    # BITMAP_HEAP_SCAN(target [ ... ])
+    # DO_NOT_SCAN(target [ ... ])
+    #
+    def seq_scan(*targets)         = add(Ast::SeqScan, targets)
+    def tid_scan(*targets)         = add(Ast::TidScan, targets)
+    def index_scan(targets)        = add_index(Ast::IndexScan, targets)
+    def index_only_scan(targets)   = add_index(Ast::IndexOnlyScan, targets)
+    def foreign_join(*targets)     = add(Ast::ForeignJoin, targets)
+    def bitmap_heap_scan(*targets) = add(Ast::BitmapHeapScan, targets)
+    def do_not_scan(*targets)      = add(Ast::DoNotScan, targets)
+
+    #
+    # Join order advice
+    #
+    # JOIN_ORDER(join_order_item [ ... ])
+    #
+    # where join_order_item is:
+    #
+    # advice_target |
+    # ( join_order_item [ ... ] ) |
+    # { join_order_item [ ... ] }
+    #
+    def join_order(*targets) = add(Ast::JoinOrder, targets)
+
+    #
+    # Join method advice
+    #
+    # join_method_name(join_method_item [ ... ])
+    #
+    # where join_method_name is:
+    #
+    # { MERGE_JOIN_MATERIALIZE | MERGE_JOIN_PLAIN | NESTED_LOOP_MATERIALIZE | NESTED_LOOP_MEMOIZE | NESTED_LOOP_PLAIN | HASH_JOIN }
+    #
+    # and join_method_item is:
+    #
+    # { advice_target |
+    # ( advice_target [ ... ] ) }
+    #
+    def merge_join_materialize(*targets)  = add(Ast::MergeJoinMaterialize, targets)
+    def merge_join_plain(*targets)        = add(Ast::MergeJoinPlain, targets)
+    def nested_loop_materialize(*targets) = add(Ast::NestedLoopMaterialize, targets)
+    def nested_loop_memoize(*targets)     = add(Ast::NestedLoopMemoize, targets)
+    def nested_loop_plain(*targets)       = add(Ast::NestedLoopPlain, targets)
+    def hash_join(*targets)               = add(Ast::HashJoin, targets)
+
+    #
+    # Partitionwise advice
+    #
+    # PARTITIONWISE(partitionwise_item [ ... ])
+    #
+    # where partitionwise_item is:
+    #
+    # { advice_target |
+    # ( advice_target [ ... ] ) }
+    #
+    def partitionwise(*targets) = add(Ast::Partitionwise, targets)
+
+    #
+    # Semijoin uniqueness advice
+    #
+    # SEMIJOIN_UNIQUE(sj_unique_item [ ... ])
+    # SEMIJOIN_NON_UNIQUE(sj_unique_item [ ... ])
+    #
+    # where sj_unique_item is:
+    #
+    # { advice_target |
+    # ( advice_target [ ... ] ) }
+    #
+    def semijoin_unique(*targets)     = add(Ast::SemijoinUnique, targets)
+    def semijoin_non_unique(*targets) = add(Ast::SemijoinNonUnique, targets)
+
+    #
+    # Parallel query advice
+    #
+    # GATHER(gather_item [ ... ])
+    # GATHER_MERGE(gather_item [ ... ])
+    # NO_GATHER(advice_target [ ... ])
+    #
+    # where gather_item is:
+    #
+    # { advice_target |
+    # ( advice_target [ ... ] ) }
+    #
+    def gather(*targets)       = add(Ast::Gather, targets)
+    def gather_merge(*targets) = add(Ast::GatherMerge, targets)
+    def no_gather(*targets)    = add(Ast::NoGather, targets)
+
+    def result = Ast::AdviceSet.new(@items)
+
+    def ordered(*targets)   = Ast::OrderedGroup.new(targets.map { |target| normalize(target) })
+    def unordered(*targets) = Ast::UnorderedGroup.new(targets.map { |target| normalize(target) })
+
+    private
+
+    def add(node_class, targets)
+      @items << node_class.new(targets.map { |target| normalize(target) })
+      self
+    end
+
+    def add_index(node_class, targets)
+      raise "invalid argument for index_scan/index_only_scan in #{targets}" unless targets.is_a?(Hash)
+
+      @items << node_class.new(normalize(targets))
+      self
+    end
+
+    def normalize(item)
+      case item
+      when Ast::Target, Ast::OrderedGroup, Ast::UnorderedGroup then item
+      when Hash
+        item.map do |target, index_name|
+          Ast::IndexTarget.new(normalize(target), index_name)
+        end
+      else @resolver.resolve(item)
+      end
+    end
+  end
+
+  def self.build(resolver: DefaultResolver.new, &block)
+    builder = Builder.new(resolver:)
+    builder.instance_exec(&block)
+    builder.result
+  end
+end

data/lib/pg_plan_advice/default_resolver.rb

@@ -0,0 +1,15 @@
+module PgPlanAdvice
+  class DefaultResolver
+    def resolve(item)
+      case item
+      when Ast::Target    then item
+      when Symbol, String then Ast::Target.new(alias_name: item.to_s)
+      when Hash
+        item.map do |target, index_name|
+          Ast::IndexTarget.new(resolve(target), index_name)
+        end
+      else raise InvalidAdviceError, "Invalid advice target: #{item.inspect}"
+      end
+    end
+  end
+end

data/lib/pg_plan_advice/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PgPlanAdvice
+  VERSION = "0.1.0"
+end

data/lib/pg_plan_advice.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "pg_plan_advice/version"
+require_relative "pg_plan_advice/builder"
+require_relative "pg_plan_advice/ar/execution"
+require_relative "pg_plan_advice/ar/querying"
+require_relative "pg_plan_advice/ar/relation"
+require_relative "pg_plan_advice/ar/resolver"
+
+module PgPlanAdvice
+  class Error < StandardError; end
+  class InvalidAdviceError < Error; end
+  class UnsupportedDatabaseError < Error; end
+
+  ON_UNSUPPORTED = %i[raise warn ignore].freeze
+
+  class << self
+    attr_reader :on_unsupported
+
+    def on_unsupported=(value)
+      unless ON_UNSUPPORTED.include?(value)
+        raise ArgumentError, "on_unsupported must be one of #{ON_UNSUPPORTED.inspect}, got: #{value.inspect}"
+      end
+
+      @on_unsupported = value
+    end
+  end
+
+  self.on_unsupported = :raise
+end
+
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Relation.prepend(PgPlanAdvice::AR::Relation)
+  extend PgPlanAdvice::AR::Querying
+end

data/sig/pg_plan_advice.rbs

@@ -0,0 +1,4 @@
+module PgPlanAdvice
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: pg_plan_advice
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- moozzi
+bindir: exe
+cert_chain: []
+date: 2026-11-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: Apply PostgreSQL 19 pg_plan_advice query plan advice to ActiveRecord
+  queries using a simple Ruby DSL.
+email:
+- bieniek.milosz0@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- lib/pg_plan_advice.rb
+- lib/pg_plan_advice/ar/execution.rb
+- lib/pg_plan_advice/ar/querying.rb
+- lib/pg_plan_advice/ar/relation.rb
+- lib/pg_plan_advice/ar/resolver.rb
+- lib/pg_plan_advice/ast.rb
+- lib/pg_plan_advice/ast/advice_set.rb
+- lib/pg_plan_advice/ast/bitmap_heap_scan.rb
+- lib/pg_plan_advice/ast/do_not_scan.rb
+- lib/pg_plan_advice/ast/foreign_join.rb
+- lib/pg_plan_advice/ast/gather.rb
+- lib/pg_plan_advice/ast/gather_merge.rb
+- lib/pg_plan_advice/ast/hash_join.rb
+- lib/pg_plan_advice/ast/index_only_scan.rb
+- lib/pg_plan_advice/ast/index_scan.rb
+- lib/pg_plan_advice/ast/index_target.rb
+- lib/pg_plan_advice/ast/join_order.rb
+- lib/pg_plan_advice/ast/merge_join_materialize.rb
+- lib/pg_plan_advice/ast/merge_join_plain.rb
+- lib/pg_plan_advice/ast/nested_loop_materialize.rb
+- lib/pg_plan_advice/ast/nested_loop_memoize.rb
+- lib/pg_plan_advice/ast/nested_loop_plain.rb
+- lib/pg_plan_advice/ast/no_gather.rb
+- lib/pg_plan_advice/ast/node.rb
+- lib/pg_plan_advice/ast/ordered_group.rb
+- lib/pg_plan_advice/ast/partitionwise.rb
+- lib/pg_plan_advice/ast/semijoin_non_unique.rb
+- lib/pg_plan_advice/ast/semijoin_unique.rb
+- lib/pg_plan_advice/ast/seq_scan.rb
+- lib/pg_plan_advice/ast/target.rb
+- lib/pg_plan_advice/ast/tid_scan.rb
+- lib/pg_plan_advice/ast/unordered_group.rb
+- lib/pg_plan_advice/builder.rb
+- lib/pg_plan_advice/default_resolver.rb
+- lib/pg_plan_advice/version.rb
+- sig/pg_plan_advice.rbs
+homepage: https://github.com/moozzi/pg_plan_advice
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/moozzi/pg_plan_advice
+  source_code_uri: https://github.com/moozzi/pg_plan_advice
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: ActiveRecord DSL for PostgreSQL pg_plan_advice.
+test_files: []