feat: support the paradedb index access method (paradedb/paradedb#5706)

Author: rebasedming

CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to this project will be documented in this file. The format
 
 ## Unreleased
 
+## Unreleased
+
+### Changed
+
+- `BM25Index` now emits `USING paradedb` by default, the primary index access method name in pg_search 0.25.0+. Pass `am="bm25"` to keep the backwards-compatible `bm25` alias (required for servers on pg_search <= 0.24.x).
+
 ## [0.10.0] - 2026-07-14
 
 ### Removed

examples/autocomplete/setup.py

@@ -9,6 +9,8 @@
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from common import create_model_indexes
+
 from models import AutocompleteItem
 
 
@@ -17,7 +19,7 @@ def setup_autocomplete_table() -> int:
     from django.db import connection
 
     with connection.cursor() as cursor:
-        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search")
+        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search CASCADE")
 
         # Ensure mock_items exists first
         cursor.execute(
@@ -57,16 +59,11 @@ def setup_autocomplete_table() -> int:
         print(f"  ✓ Copied {count} products from mock_items")
 
         print("\nCreating autocomplete-optimized BM25 index...")
-    with connection.schema_editor(atomic=False) as schema_editor:
-        for index in AutocompleteItem._meta.indexes:
-            statement = index.create_sql(
-                model=AutocompleteItem, schema_editor=schema_editor
-            )
-            schema_editor.execute(statement)
-        print("  ✓ Created BM25 index with:")
-        print("    - description (standard tokenizer)")
-        print("    - description_ngram (ngram 3-8 for substring matching)")
-        print("    - category (literal for exact matching)")
+    create_model_indexes(AutocompleteItem)
+    print("  ✓ Created BM25 index with:")
+    print("    - description (standard tokenizer)")
+    print("    - description_ngram (ngram 3-8 for substring matching)")
+    print("    - category (literal for exact matching)")
 
     return count
 

examples/common.py

@@ -59,23 +59,43 @@ def configure_django() -> None:
     django.setup()
 
 
+def server_index_am() -> str:
+    """Index access method to use: `paradedb` on pg_search 0.25.0+, else `bm25`."""
+    from django.db import connection
+
+    with connection.cursor() as cursor:
+        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search CASCADE")
+        cursor.execute("SELECT 1 FROM pg_am WHERE amname = 'paradedb'")
+        return "paradedb" if cursor.fetchone() else "bm25"
+
+
+def create_model_indexes(model) -> None:
+    """Create the model's declared indexes using the server's available AM."""
+    from django.db import connection
+
+    am = server_index_am()
+    with connection.schema_editor(atomic=False) as schema_editor:
+        for index in model._meta.indexes:
+            if isinstance(index, BM25Index) and index.am != am:
+                _path, args, kwargs = index.deconstruct()
+                index = BM25Index(*args, **{**kwargs, "am": am})
+            statement = index.create_sql(model=model, schema_editor=schema_editor)
+            schema_editor.execute(statement)
+
+
 def setup_mock_items() -> int:
     """Create mock_items table with BM25 index. Returns row count."""
     from django.db import connection
 
     with connection.cursor() as cursor:
-        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search")
+        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search CASCADE")
         cursor.execute(
             "CALL paradedb.create_bm25_test_table("
             "schema_name => 'public', table_name => 'mock_items')"
         )
         cursor.execute("DROP INDEX IF EXISTS mock_items_bm25_idx;")
 
-    # Render index SQL from the unmanaged model metadata.
-    with connection.schema_editor(atomic=False) as schema_editor:
-        for index in MockItem._meta.indexes:
-            statement = index.create_sql(model=MockItem, schema_editor=schema_editor)
-            schema_editor.execute(statement)
+    create_model_indexes(MockItem)
 
     return MockItem.objects.count()
 

paradedb/indexes.py

@@ -165,8 +165,18 @@ class IndexExpression:
     tokenizer: Tokenizer | None = None
 
 
+DEFAULT_INDEX_AM = "paradedb"
+SUPPORTED_INDEX_AMS = ("paradedb", "bm25")
+
+
 class BM25Index(models.Index):
-    """BM25 index for ParadeDB."""
+    """BM25 index for ParadeDB.
+
+    By default the index is created with ``USING paradedb``, the primary
+    access method name in pg_search 0.25.0+. Pass ``am="bm25"`` to emit
+    ``USING bm25``, the permanent backwards-compatible alias supported by
+    all pg_search versions.
+    """
 
     suffix = "bm25"
 
@@ -178,10 +188,15 @@ def __init__(
         name: str,
         expressions: list[IndexExpression] | None = None,
         condition: models.Q | None = None,
+        am: str = DEFAULT_INDEX_AM,
     ) -> None:
+        if am not in SUPPORTED_INDEX_AMS:
+            supported = ", ".join(repr(name) for name in SUPPORTED_INDEX_AMS)
+            raise ValueError(f"Index access method must be one of: {supported}.")
         self.fields_config = fields
         self.key_field = key_field
         self.index_expressions = list(expressions or [])
+        self.am = am
         super().__init__(name=name, fields=list(fields.keys()), condition=condition)
 
     def deconstruct(self) -> tuple[str, Any, dict[str, Any]]:
@@ -191,6 +206,8 @@ def deconstruct(self) -> tuple[str, Any, dict[str, Any]]:
         kwargs["name"] = self.name
         if self.index_expressions:
             kwargs["expressions"] = self.index_expressions
+        if self.am != DEFAULT_INDEX_AM:
+            kwargs["am"] = self.am
         return path, args, kwargs
 
     def create_sql(
@@ -218,7 +235,7 @@ def create_sql(
             create_stmt += " CONCURRENTLY"
         template = (
             f"{create_stmt} %(name)s ON %(table)s\n"
-            "USING bm25 (\n"
+            f"USING {self.am} (\n"
             "    %(expressions)s\n"
             ")\n"
             f"WITH ({', '.join(storage_params)})"

tests/conftest.py

@@ -39,6 +39,20 @@ def pytest_configure(config: object) -> None:
     raise RuntimeError("psycopg is required to run integration tests") from exc
 
 
+_server_index_am: str | None = None
+
+
+def server_index_am() -> str:
+    """AM used by the integration suite: `paradedb` when the server has it
+    (pg_search 0.25.0+), otherwise the `bm25` alias."""
+    global _server_index_am
+    if _server_index_am is None:
+        with connection.cursor() as cursor:
+            cursor.execute("SELECT 1 FROM pg_am WHERE amname = 'paradedb';")
+            _server_index_am = "paradedb" if cursor.fetchone() else "bm25"
+    return _server_index_am
+
+
 def _require_postgres() -> None:
     engine = connection.settings_dict.get("ENGINE", "")
     if "postgresql" not in engine:
@@ -66,7 +80,7 @@ def paradedb_ready(django_db_setup: object, django_db_blocker: object) -> None:
 
     with django_db_blocker.unblock(), connection.cursor() as cursor:
         try:
-            cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search;")
+            cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search CASCADE;")
         except Exception as exc:  # pragma: no cover - defensive skip
             pytest.fail(
                 f"ParadeDB pg_search extension unavailable in target database: {exc}"
@@ -76,7 +90,7 @@ def paradedb_ready(django_db_setup: object, django_db_blocker: object) -> None:
         )
         cursor.execute("DROP INDEX IF EXISTS mock_items_bm25_idx;")
         cursor.execute(
-            "CREATE INDEX mock_items_bm25_idx ON mock_items USING bm25 ("
+            f"CREATE INDEX mock_items_bm25_idx ON mock_items USING {server_index_am()} ("
             "id, "
             "description, "
             "category, "