feat!: rename bm25 APIs to paradedb and always use the paradedb access method (paradedb/paradedb#5706)

Author: rebasedming

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING**: Renamed the `bm25`-named migration helpers to `paradedb`: `add_bm25_index` is now `add_paradedb_index`, `remove_bm25_index` is now `remove_paradedb_index`, and `reindex_bm25` is now `reindex_paradedb_index`. The old names were removed; update migrations and `schema.rb` files to the new names.
+- **BREAKING**: Index creation always emits `USING paradedb`, which requires pg_search 0.25.0+. There is no option to select the legacy `bm25` access method.
+
 [0.9.0] - 2026-07-14
 
 ### Added

README.md

@@ -36,7 +36,7 @@
 
 ## ParadeDB for Rails
 
-The official ActiveRecord integration for [ParadeDB](https://paradedb.com) (powered by the [`pg_search`](https://github.com/paradedb/paradedb) Postgres extension), including first-class support for managing BM25 indexes and running queries using the full ParadeDB API. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#rails) to begin.
+The official ActiveRecord integration for [ParadeDB](https://paradedb.com) (powered by the [`pg_search`](https://github.com/paradedb/paradedb) Postgres extension), including first-class support for managing ParadeDB indexes and running queries using the full ParadeDB API. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#rails) to begin.
 
 ## Requirements & Compatibility
 

examples/autocomplete/setup.rb

@@ -20,13 +20,13 @@ class AutocompleteExampleApp < Rails::Application
 module AutocompleteSetup
   module_function
 
-  def drop_bm25_indexes!(conn, table_name)
+  def drop_paradedb_indexes!(conn, table_name)
     indexes = conn.select_values(<<~SQL)
       SELECT indexname
       FROM pg_indexes
       WHERE schemaname = 'public'
         AND tablename = #{conn.quote(table_name.to_s)}
-        AND indexdef LIKE '%USING bm25%'
+        AND (indexdef LIKE '%USING bm25%' OR indexdef LIKE '%USING paradedb%')
     SQL
 
     indexes.each do |index_name|
@@ -61,7 +61,7 @@ def setup_mock_items!
     conn.execute(
       "CALL paradedb.create_bm25_test_table(schema_name => 'public', table_name => 'mock_items');"
     )
-    drop_bm25_indexes!(conn, :mock_items)
+    drop_paradedb_indexes!(conn, :mock_items)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 
     MockItem.reset_column_information
@@ -97,7 +97,7 @@ def setup_autocomplete_table!
     puts "  + Copied #{count} products from #{MockItem.table_name}"
 
     puts "\nCreating autocomplete-optimized BM25 index..."
-    conn.remove_bm25_index(:autocomplete_items, name: :autocomplete_items_idx, if_exists: true)
+    conn.remove_paradedb_index(:autocomplete_items, name: :autocomplete_items_idx, if_exists: true)
     conn.create_paradedb_index(AutocompleteItemIndex, if_not_exists: true)
 
     puts "  + Created BM25 index with:"

examples/faceted_search/setup.rb

@@ -48,7 +48,7 @@ def setup_mock_items!
     )
     conn.execute("DROP TABLE IF EXISTS mock_items_faceted_search CASCADE;")
     conn.execute("CREATE TABLE mock_items_faceted_search AS TABLE mock_items;")
-    conn.remove_bm25_index(:mock_items_faceted_search, name: :mock_items_faceted_search_bm25_idx, if_exists: true)
+    conn.remove_paradedb_index(:mock_items_faceted_search, name: :mock_items_faceted_search_bm25_idx, if_exists: true)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 
     MockItem.reset_column_information

examples/hybrid_rrf/setup.rb

@@ -56,7 +56,7 @@ def setup_mock_items!
     )
     conn.execute("DROP TABLE IF EXISTS mock_items_hybrid_rrf CASCADE;")
     conn.execute("CREATE TABLE mock_items_hybrid_rrf AS TABLE mock_items;")
-    conn.remove_bm25_index(:mock_items_hybrid_rrf, name: :mock_items_hybrid_rrf_bm25_idx, if_exists: true)
+    conn.remove_paradedb_index(:mock_items_hybrid_rrf, name: :mock_items_hybrid_rrf_bm25_idx, if_exists: true)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 
     MockItem.reset_column_information

examples/more_like_this/setup.rb

@@ -19,13 +19,13 @@ class MoreLikeThisExampleApp < Rails::Application
 module MoreLikeThisSetup
   module_function
 
-  def drop_bm25_indexes!(conn, table_name)
+  def drop_paradedb_indexes!(conn, table_name)
     indexes = conn.select_values(<<~SQL)
       SELECT indexname
       FROM pg_indexes
       WHERE schemaname = 'public'
         AND tablename = #{conn.quote(table_name.to_s)}
-        AND indexdef LIKE '%USING bm25%'
+        AND (indexdef LIKE '%USING bm25%' OR indexdef LIKE '%USING paradedb%')
     SQL
 
     indexes.each do |index_name|
@@ -60,7 +60,7 @@ def setup_mock_items!
     conn.execute(
       "CALL paradedb.create_bm25_test_table(schema_name => 'public', table_name => 'mock_items');"
     )
-    drop_bm25_indexes!(conn, :mock_items)
+    drop_paradedb_indexes!(conn, :mock_items)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 
     MockItem.reset_column_information

examples/quickstart/setup.rb

@@ -19,13 +19,13 @@ class QuickstartExampleApp < Rails::Application
 module QuickstartSetup
   module_function
 
-  def drop_bm25_indexes!(conn, table_name)
+  def drop_paradedb_indexes!(conn, table_name)
     indexes = conn.select_values(<<~SQL)
       SELECT indexname
       FROM pg_indexes
       WHERE schemaname = 'public'
         AND tablename = #{conn.quote(table_name.to_s)}
-        AND indexdef LIKE '%USING bm25%'
+        AND (indexdef LIKE '%USING bm25%' OR indexdef LIKE '%USING paradedb%')
     SQL
 
     indexes.each do |index_name|
@@ -60,7 +60,7 @@ def setup_mock_items!
     conn.execute(
       "CALL paradedb.create_bm25_test_table(schema_name => 'public', table_name => 'mock_items');"
     )
-    drop_bm25_indexes!(conn, :mock_items)
+    drop_paradedb_indexes!(conn, :mock_items)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 
     MockItem.reset_column_information

examples/rag/setup.rb

@@ -19,13 +19,13 @@ class RagExampleApp < Rails::Application
 module RagSetup
   module_function
 
-  def drop_bm25_indexes!(conn, table_name)
+  def drop_paradedb_indexes!(conn, table_name)
     indexes = conn.select_values(<<~SQL)
       SELECT indexname
       FROM pg_indexes
       WHERE schemaname = 'public'
         AND tablename = #{conn.quote(table_name.to_s)}
-        AND indexdef LIKE '%USING bm25%'
+        AND (indexdef LIKE '%USING bm25%' OR indexdef LIKE '%USING paradedb%')
     SQL
 
     indexes.each do |index_name|
@@ -60,7 +60,7 @@ def setup_mock_items!
     conn.execute(
       "CALL paradedb.create_bm25_test_table(schema_name => 'public', table_name => 'mock_items');"
     )
-    drop_bm25_indexes!(conn, :mock_items)
+    drop_paradedb_indexes!(conn, :mock_items)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 
     MockItem.reset_column_information

lib/generators/parade_db/index/index_generator.rb

@@ -15,7 +15,7 @@ class IndexGenerator < Rails::Generators::NamedBase
       class_option :concurrent, type: :boolean, default: false,
                                 desc: "Add disable_ddl_transaction! to the migration (required for concurrent index creation)"
 
-      desc "Creates a ParadeDB::Index class and a BM25 index migration for MODEL."
+      desc "Creates a ParadeDB::Index class and a ParadeDB index migration for MODEL."
 
       def self.next_migration_number(dirname)
         ActiveRecord::Generators::Base.next_migration_number(dirname)

lib/generators/parade_db/index/templates/migration.rb.tt

@@ -10,6 +10,6 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
   end
 
   def down
-    remove_bm25_index :<%= table_name %>, name: :<%= index_name %>, if_exists: true
+    remove_paradedb_index :<%= table_name %>, name: :<%= index_name %>, if_exists: true
   end
 end