pg_search picks one of three PostgreSQL search features per model and per scope

Two techniques, and picking the wrong one costs you the wrong index

pg_search supports two different techniques, and the README is clear that they are for different jobs.

Multi-search mixes records of many different Active Record classes into one global search index across the application. For a site with a generic search page covering several models, this is the technique the README recommends. It works through a dedicated table, and adding a model to it is a one-line declaration.

class EpicPoem < ActiveRecord::Base
  include PgSearch::Model
  multisearchable against: [:title, :author]
end

class Flower < ActiveRecord::Base
  include PgSearch::Model
  multisearchable against: :color
end

Search scopes are the other technique: advanced searching against a single Active Record class, which the README points at autocompleters and filtering a list of items in a faceted search.

So the decision is about where the results come from. If the answer needs rows from three tables, multi-search is the shape you want and a per-model scope will not give it to you. If the answer is always within one model and you want to keep composing with other scopes, search scopes fit.

Multi-search needs setup before use: a generated migration creates the pg_search_documents table, run with rails g pg_search:migration:multisearch followed by rake db:migrate. Models that already have records need a reindex to backfill, which is the step people forget on an established database.

The if: option is evaluated in an after_save hook, and that changes its meaning

A model can restrict which records enter the index by passing an if: option, either a method name or a Proc that is called on the record. The reason this needs care is documented at length, and the explanation is the most useful thing in the README.

The Proc or method name is called in an after_save hook. That has a concrete consequence: if the decision depends on a value that changes with time rather than on the save, the record's presence in the index is decided at save time and then frozen until the record is touched again.

class AntipatternExample
  include PgSearch::Model
  multisearchable against: [:contents], if: :published?

  def published?
    published_at < Time.now
  end
end

The example walks through it. A record is created with published_at ten minutes in the future. published? is false, and a global search finds nothing. Twenty minutes later published? is true, and the search still finds nothing, because no save has happened since. The record only appears after another save, which re-fires the callback and re-evaluates the condition.

For the cases where that is what you want, the option is fine. `if::available_in_red?` on a Convertible and a lambda checking model_year greater than 1970 on a Jalopy are both conditions that are true or false when the record is written.

tsearch, dmetaphone and trigram are three different answers

The feature list is the substance of this gem, because each search feature is a different PostgreSQL mechanism answering a different question.

`:tsearch` is full text search, and it carries the most options. Weighting lets you say which column matters more. `:prefix` enables prefix matching, documented as PostgreSQL 8.4 and newer only. `:negation` excludes terms. `:dictionary` selects a text search configuration, and `:normalization` controls it. `:any_word` relaxes the requirement that all terms match. `:sort_only` restricts a scope to ranking without matching. `:highlight` marks matched terms in results.

`:dmetaphone` is double metaphone soundalike search, which is how a query for a name typed approximately still finds the record. `:trigram` is trigram search, similarity on character sequences rather than words, with a `:threshold` for how close a match must be and a `:word_similarity` mode.

The README documents a specific pattern for using more than one at a time: limiting fields when combining features. That section exists because combining, say, a trigram scope with a tsearch scope on the same query otherwise returns a cross product of the two conditions rather than a sensible union, and the field limiting is what keeps the combination meaningful.

Also covered: ignoring accent marks, using tsvector columns directly when you want the vector stored and combined yourself, and configuring ranking with `:ranked_by`, breaking ties with `:order_within_rank`, or reading a record's rank as a Float through PgSearch#pg_search_rank.

Requirements are current, and some features need extensions

The stated requirements are Ruby 3.3 or newer, Active Record 8.0 or newer, and PostgreSQL 9.2 or newer. PostgreSQL extensions are listed as required for certain features, with a wiki page on installing them.

That combination is worth pausing on. The maintenance record supports that reading: the last push to the repository was on 2026-10-14 and the project is being kept current rather than held stable.

Installation is a gem install or a Gemfile line.

gem 'pg_search'

Outside Rails, you may want to load the pg_search rake tasks into your Rakefile with load "pg_search/tasks.rb". Rails applications do not need this because they pick the tasks up through a Railtie, which is the kind of small difference that costs an afternoon if you assume symmetry.

There are no GitHub releases for this repository, so versions come from RubyGems and the CHANGELOG.md at the root. The licence is MIT, and the project also carries a standard.yml for the standardrb linter and an.rspec file for RSpec.

Where pg_search is the wrong tool

The first boundary is relevance across heterogeneous content. Multi-search puts every model into one index with one set of weights, so a match in a title and a match in a paragraph are both just text in the same document. If your users need field-aware relevance across several models, this does not give it to you and no configuration in the documented list adds it.

The operational cost is the index. Multi-search means a table that grows with your data and a rebuild path when you change a model's against: list, so adding a field is a reindex, not a migration. The README documents a rebuild task for a given class, which tells you the operation is supported and also that it is expected to be run.

The alternative approaches differ in what you give up. Hand-written to_tsquery SQL through Active Record gives you full control with no dependency, and gives up the scopes, the weighting helpers and the document table management that this gem provides.

Editorial conclusion

Adopt pg_search if your search needs can be answered inside PostgreSQL and you want them expressed as model scopes instead of a separate search service. Do not adopt it expecting cross-field relevance tuning or a UI, because it is a query layer. Before starting, confirm PostgreSQL 9.2 or newer, Ruby 3.3 or newer and Active Record 8.0 or newer, and plan the multisearch migration and reindex step before you have data in the tables.

Frequently asked questions

Official sources

1. Casecommons/pg_search on GitHub
2. Issues
3. License: MIT
4. Project website
5. README