0.0
There's a lot of open issues
Apply PostgreSQL 19 pg_plan_advice query plan advice to ActiveRecord queries using a simple Ruby DSL.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

>= 7.2, < 9
>= 1.1
 Project Readme

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

Add the gem to your application's Gemfile:

bundle add pg_plan_advice

or add it manually:

gem "pg_plan_advice"

Usage

ActiveRecord

Call plan_advice on a model or a relation and describe the advice in a block:

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:

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:

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:

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.