pghybrid 0.1.0__tar.gz

pghybrid-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Node
+node_modules/
+js/dist/
+*.tsbuildinfo
+.npm/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Local
+.env
+.env.local
+
+# Scratch files
+js/dbg*.mjs
+js/e2e-check.mjs

pghybrid-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: pghybrid
+Version: 0.1.0
+Summary: Hybrid search on the Postgres you already have. Vector + full-text + Reciprocal Rank Fusion on plain pgvector, with no extensions to install.
+Project-URL: Homepage, https://github.com/pavangupta352/pghybrid
+Project-URL: Repository, https://github.com/pavangupta352/pghybrid
+Project-URL: Issues, https://github.com/pavangupta352/pghybrid/issues
+Project-URL: Changelog, https://github.com/pavangupta352/pghybrid/blob/main/CHANGELOG.md
+Author-email: Pavan Gupta <pavan.gupta.352@gmail.com>
+License: MIT
+Keywords: bm25,full-text-search,hybrid-search,pgvector,postgres,postgresql,rag,reciprocal-rank-fusion,retrieval,rrf,semantic-search,supabase,tsvector,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: SQL
+Classifier: Topic :: Database
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: cli
+Requires-Dist: psycopg[binary]>=3.1; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: langchain-core>=0.3; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: psycopg-pool>=3.2; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pghybrid
+
+**Hybrid search on the Postgres you already have.**
+
+Vector similarity + full-text search, combined by Reciprocal Rank Fusion, on plain
+`pgvector`. No `pg_search`, no VectorChord, no Elasticsearch, no vector database, no
+extension you need superuser to install.
+
+```bash
+pip install pghybrid
+```
+
+## Why
+
+Hybrid search on Postgres is a solved problem *if you can install a C extension*.
+`pg_search`, VectorChord and `pg_textsearch` are all excellent, and all of them are
+extensions — and on managed Postgres you usually cannot install extensions at all.
+
+**`pgvector` is available almost everywhere. BM25 extensions are available almost
+nowhere:** not on RDS, Aurora, Cloud SQL, Azure Database, Supabase or Heroku, and
+[removed from Neon for new projects in March 2026](https://neon.com/docs/extensions/pg_search).
+
+This is not a claim to search better than ParadeDB — `pg_search`'s BM25 genuinely beats
+`ts_rank_cd`, and if you can install it you probably should. It is search you can
+actually install.
+
+## The case it exists for
+
+A contract. Someone asks **"renewal notice period"**. The clause that answers it says
+*"sixty days written notice prior to the anniversary date"* — it never uses the word
+*renewal*. Vector search puts a plausible-but-wrong clause first. Keyword search puts the
+clause that uses all three words and answers none of them first. The right answer is
+second on both signals and first on neither, which is exactly what rank fusion is for.
+
+## Use it
+
+<!-- check:python -->
+```python
+from pghybrid import Config, HybridSearch
+
+search = HybridSearch(
+    Config(table="chunks", text_column="content", vector_column="embedding",
+           tsvector_column="fts", extra_columns=["title"], paramstyle="pyformat"),
+    execute=lambda sql, params: conn.execute(sql, params).fetchall(),
+)
+
+for row in search.search("renewal notice period", embedding=query_vector, limit=10):
+    print(row.score, row.matched_by, row.get("title"))
+```
+
+You pass the embedding in. `pghybrid` never calls a model, so it works with OpenAI,
+Cohere, Voyage, a local sentence-transformer or anything else, and needs no API key. It
+never opens a connection either — it generates SQL and hands it to the driver you already
+use. `for_psycopg`, `for_sqlalchemy`, `for_asyncpg` and `for_django` set the placeholder
+style for you.
+
+`row.matched_by` tells you which signal found each row — `both`, `vector` or `text` —
+which is usually the first thing you want when a search returns the wrong thing.
+
+## Read the statement instead of running it
+
+```python
+sql, params = search.build_sql("renewal notice period", query_vector, limit=10)
+```
+
+It is one query with a candidate CTE per signal, fused by RRF. Nothing is hidden, and
+`pghybrid sql` prints it without a database at all.
+
+## Command line
+
+```bash
+pghybrid init   --dsn "$DATABASE_URL" --table chunks   # inspects, writes the migration
+pghybrid doctor --dsn "$DATABASE_URL" --table chunks   # measured recall, read-only
+```
+
+`doctor` measures recall@k against exact search, sweeps `ef_search`/`probes`, catches
+queries that silently fall back to a sequential scan, and reports a `tsvector` that has
+stopped matching its text — a failure that returns wrong answers without erroring.
+
+`explain` decomposes a single result set: both ranks, both raw scores, each signal's
+contribution, and the near-miss band just below your cut-off.
+
+## Also in TypeScript
+
+[`npm install pghybrid`](https://www.npmjs.com/package/pghybrid) generates byte-identical
+SQL, checked on every commit rather than assumed.
+
+---
+
+**Full documentation, the reasoning, and copy-and-paste SQL:
+[github.com/pavangupta352/pghybrid](https://github.com/pavangupta352/pghybrid#readme)**
+
+MIT © Pavan Gupta

pghybrid-0.1.0/README.md

@@ -0,0 +1,93 @@
+# pghybrid
+
+**Hybrid search on the Postgres you already have.**
+
+Vector similarity + full-text search, combined by Reciprocal Rank Fusion, on plain
+`pgvector`. No `pg_search`, no VectorChord, no Elasticsearch, no vector database, no
+extension you need superuser to install.
+
+```bash
+pip install pghybrid
+```
+
+## Why
+
+Hybrid search on Postgres is a solved problem *if you can install a C extension*.
+`pg_search`, VectorChord and `pg_textsearch` are all excellent, and all of them are
+extensions — and on managed Postgres you usually cannot install extensions at all.
+
+**`pgvector` is available almost everywhere. BM25 extensions are available almost
+nowhere:** not on RDS, Aurora, Cloud SQL, Azure Database, Supabase or Heroku, and
+[removed from Neon for new projects in March 2026](https://neon.com/docs/extensions/pg_search).
+
+This is not a claim to search better than ParadeDB — `pg_search`'s BM25 genuinely beats
+`ts_rank_cd`, and if you can install it you probably should. It is search you can
+actually install.
+
+## The case it exists for
+
+A contract. Someone asks **"renewal notice period"**. The clause that answers it says
+*"sixty days written notice prior to the anniversary date"* — it never uses the word
+*renewal*. Vector search puts a plausible-but-wrong clause first. Keyword search puts the
+clause that uses all three words and answers none of them first. The right answer is
+second on both signals and first on neither, which is exactly what rank fusion is for.
+
+## Use it
+
+<!-- check:python -->
+```python
+from pghybrid import Config, HybridSearch
+
+search = HybridSearch(
+    Config(table="chunks", text_column="content", vector_column="embedding",
+           tsvector_column="fts", extra_columns=["title"], paramstyle="pyformat"),
+    execute=lambda sql, params: conn.execute(sql, params).fetchall(),
+)
+
+for row in search.search("renewal notice period", embedding=query_vector, limit=10):
+    print(row.score, row.matched_by, row.get("title"))
+```
+
+You pass the embedding in. `pghybrid` never calls a model, so it works with OpenAI,
+Cohere, Voyage, a local sentence-transformer or anything else, and needs no API key. It
+never opens a connection either — it generates SQL and hands it to the driver you already
+use. `for_psycopg`, `for_sqlalchemy`, `for_asyncpg` and `for_django` set the placeholder
+style for you.
+
+`row.matched_by` tells you which signal found each row — `both`, `vector` or `text` —
+which is usually the first thing you want when a search returns the wrong thing.
+
+## Read the statement instead of running it
+
+```python
+sql, params = search.build_sql("renewal notice period", query_vector, limit=10)
+```
+
+It is one query with a candidate CTE per signal, fused by RRF. Nothing is hidden, and
+`pghybrid sql` prints it without a database at all.
+
+## Command line
+
+```bash
+pghybrid init   --dsn "$DATABASE_URL" --table chunks   # inspects, writes the migration
+pghybrid doctor --dsn "$DATABASE_URL" --table chunks   # measured recall, read-only
+```
+
+`doctor` measures recall@k against exact search, sweeps `ef_search`/`probes`, catches
+queries that silently fall back to a sequential scan, and reports a `tsvector` that has
+stopped matching its text — a failure that returns wrong answers without erroring.
+
+`explain` decomposes a single result set: both ranks, both raw scores, each signal's
+contribution, and the near-miss band just below your cut-off.
+
+## Also in TypeScript
+
+[`npm install pghybrid`](https://www.npmjs.com/package/pghybrid) generates byte-identical
+SQL, checked on every commit rather than assumed.
+
+---
+
+**Full documentation, the reasoning, and copy-and-paste SQL:
+[github.com/pavangupta352/pghybrid](https://github.com/pavangupta352/pghybrid#readme)**
+
+MIT © Pavan Gupta

pghybrid-0.1.0/pyproject.toml

@@ -0,0 +1,105 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pghybrid"
+version = "0.1.0"
+description = "Hybrid search on the Postgres you already have. Vector + full-text + Reciprocal Rank Fusion on plain pgvector, with no extensions to install."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Pavan Gupta", email = "pavan.gupta.352@gmail.com" }]
+keywords = [
+    "postgres", "postgresql", "pgvector", "hybrid-search", "rrf",
+    "reciprocal-rank-fusion", "full-text-search", "vector-search",
+    "semantic-search", "rag", "retrieval", "tsvector", "bm25", "supabase",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: SQL",
+    "Topic :: Database",
+    "Topic :: Text Processing :: Indexing",
+    "Typing :: Typed",
+]
+# No runtime dependencies. The package generates SQL and hands it to whatever
+# driver the caller already uses.
+dependencies = []
+
+[project.optional-dependencies]
+cli = ["psycopg[binary]>=3.1"]
+dev = [
+    "psycopg[binary]>=3.1",
+    # The ORM adapters are only worth shipping if they are exercised against a real
+    # server, so the libraries they wrap are test dependencies.
+    "sqlalchemy>=2.0",
+    "asyncpg>=0.29",
+    # The concurrency test holds one HybridSearch across threads backed by a pool,
+    # which is how a web application uses it.
+    "psycopg-pool>=3.2",
+    # For examples/langchain_retriever.py. Not a dependency of the package: the glue
+    # lives in an example so this library never owns LangChain's version matrix. CI runs
+    # it so the example cannot rot unnoticed.
+    "langchain-core>=0.3",
+    "django>=4.2",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[project.urls]
+Homepage = "https://github.com/pavangupta352/pghybrid"
+Repository = "https://github.com/pavangupta352/pghybrid"
+Issues = "https://github.com/pavangupta352/pghybrid/issues"
+Changelog = "https://github.com/pavangupta352/pghybrid/blob/main/CHANGELOG.md"
+
+[project.scripts]
+pghybrid = "pghybrid.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pghybrid"]
+# PEP 561. Without this marker a consumer's type checker ignores the annotations
+# entirely and reports every symbol as Any, however strictly the package checks itself.
+artifacts = ["src/pghybrid/py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: requires a live Postgres with pgvector",
+    "needs_database: the test talks to a server and needs the demo corpus seeded",
+]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+# UP045 rewrites Optional[X] to X | None. Annotations are strings here thanks to
+# `from __future__ import annotations`, so both forms run on 3.9 — but only the
+# Optional form survives a runtime typing.get_type_hints() call there, and the
+# package supports 3.9. Not worth 65 rewrites to lose that.
+ignore = ["UP045", "UP007"]
+
+[tool.mypy]
+# mypy no longer accepts 3.9 as a target. requires-python stays >=3.9;
+# this only sets which syntax mypy assumes while checking.
+python_version = "3.10"
+strict = true
+
+# Django ships no py.typed marker. The adapter touches exactly one symbol from it and
+# is exercised against a real Django connection in the integration suite.
+[[tool.mypy.overrides]]
+module = ["django.*"]
+ignore_missing_imports = true

pghybrid-0.1.0/src/pghybrid/__init__.py

@@ -0,0 +1,100 @@
+"""Hybrid search on the Postgres you already have.
+
+Vector similarity and full-text search, combined by Reciprocal Rank Fusion, over plain
+``pgvector``. No extension beyond ``pgvector`` is required, which is the entire point:
+``pg_search`` and its peers are unavailable on most managed Postgres.
+
+    from pghybrid import Config, HybridSearch
+
+    search = HybridSearch(
+        Config(table="chunks", text_column="content", vector_column="embedding",
+               tsvector_column="fts", paramstyle="pyformat"),
+        execute=lambda sql, params: conn.execute(sql, params).fetchall(),
+    )
+    rows = search.search("renewal notice period", embedding=vector, limit=10)
+
+``execute`` is whatever driver you already have. This package opens no connections and
+calls no embedding model.
+"""
+
+from .config import (
+    COSINE,
+    INNER_PRODUCT,
+    L1,
+    L2,
+    METRICS,
+    Config,
+    Metric,
+    Recency,
+    Weights,
+)
+from .explain import ExplainReport, ExplainRow, FindReport, explain, measure_weights
+from .schema import (
+    Statement,
+    TableInfo,
+    TableNotFound,
+    build_migration,
+    dbapi_executor,
+    introspect,
+    suggest_config,
+)
+from .search import AsyncHybridSearch, HybridSearch, SearchResult
+from .sql import IdentifierError, build_search_sql, quote_ident
+from .textquery import ParsedQuery, parse_query
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Configuration
+    "Config",
+    "Metric",
+    "Recency",
+    "Weights",
+    "METRICS",
+    "COSINE",
+    "L2",
+    "INNER_PRODUCT",
+    "L1",
+    # Searching
+    "HybridSearch",
+    "AsyncHybridSearch",
+    "SearchResult",
+    # Diagnosing
+    "explain",
+    "measure_weights",
+    "ExplainReport",
+    "ExplainRow",
+    "FindReport",
+    # Schema
+    "introspect",
+    "suggest_config",
+    "build_migration",
+    "dbapi_executor",
+    "TableInfo",
+    "TableNotFound",
+    "Statement",
+    # The SQL itself, for people who want to read or steal it
+    "build_search_sql",
+    "quote_ident",
+    "IdentifierError",
+    "parse_query",
+    "ParsedQuery",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Expose ``doctor`` lazily.
+
+    It is the heaviest module in the package and the only one most callers never touch,
+    so importing it eagerly would make ``import pghybrid`` pay for a feature reserved
+    for the moment something has already gone wrong.
+    """
+    if name == "doctor":
+        from .doctor import doctor
+
+        return doctor
+    if name == "DoctorReport":
+        from .doctor import DoctorReport
+
+        return DoctorReport
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pghybrid-0.1.0/src/pghybrid/adapters.py

@@ -0,0 +1,187 @@
+"""One-line wiring for the drivers people actually have.
+
+:class:`~pghybrid.search.HybridSearch` takes an ``execute`` callable, which keeps the
+package free of driver dependencies but leaves every user writing the same lambda — and
+choosing a placeholder style, which is the single thing most likely to be got wrong.
+``$1`` and ``%s`` are not interchangeable, and picking the wrong one fails with a message
+about parameter counts that says nothing about the cause.
+
+So each helper here does both: it wires the executor for one driver *and* sets the
+placeholder style that driver needs. Nothing is imported at module scope, so the package
+keeps its promise of zero runtime dependencies whichever of these you never use.
+
+    from pghybrid.adapters import for_psycopg
+
+    search = for_psycopg(conn, table="chunks", text_column="content",
+                         vector_column="embedding", tsvector_column="fts")
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from typing import Any, Optional
+
+from .config import Config, ParamStyle
+from .search import AsyncHybridSearch, HybridSearch
+
+__all__ = [
+    "for_psycopg",
+    "for_asyncpg",
+    "for_sqlalchemy",
+    "for_django",
+    "psycopg_executor",
+    "asyncpg_executor",
+    "sqlalchemy_executor",
+    "django_executor",
+]
+
+
+def _as_mappings(cursor: Any) -> list[dict[str, Any]]:
+    """Read a DBAPI cursor as dicts, whatever row factory it was configured with.
+
+    A connection may already be returning mappings — ``psycopg.rows.dict_row`` is common
+    — and zipping column names against one of those pairs the names with the dict's keys
+    instead of its values, so every column comes back holding its own name.
+    """
+    if cursor.description is None:
+        return []
+    columns = [column[0] for column in cursor.description]
+    rows = cursor.fetchall()
+    if rows and isinstance(rows[0], Mapping):
+        return [dict(row) for row in rows]
+    return [dict(zip(columns, row)) for row in rows]
+
+
+def _resolve(config: Optional[Config], paramstyle: ParamStyle, **overrides: Any) -> Config:
+    """Build or adjust a Config, forcing the placeholder style the driver requires.
+
+    Passing ``paramstyle`` yourself is not an error worth respecting: a psycopg
+    connection cannot execute ``$1`` no matter how firmly it was requested.
+    """
+    if config is None:
+        if not overrides:
+            raise TypeError(
+                "pass a Config, or the keyword arguments to build one "
+                "(table=..., text_column=..., vector_column=...)"
+            )
+        overrides.pop("paramstyle", None)
+        return Config(paramstyle=paramstyle, **overrides)
+
+    if overrides:
+        overrides.pop("paramstyle", None)
+        config = replace(config, **overrides)
+    return replace(config, paramstyle=paramstyle)
+
+
+# ------------------------------------------------------------------------- psycopg
+
+
+def psycopg_executor(connection: Any) -> Any:
+    """An executor over a psycopg 2 or 3 connection, cursor factory notwithstanding.
+
+    Rows are returned as mappings whatever the connection was configured for, because
+    the caller asked for search results rather than for tuples they then have to zip
+    against a column list.
+    """
+
+    def execute(sql: str, params: list[Any]) -> list[dict[str, Any]]:
+        with connection.cursor() as cursor:
+            cursor.execute(sql, params)
+            return _as_mappings(cursor)
+
+    return execute
+
+
+def for_psycopg(connection: Any, config: Optional[Config] = None, **kwargs: Any) -> HybridSearch:
+    """Wire a psycopg connection. psycopg speaks ``%s``, so the style is set for you."""
+    return HybridSearch(_resolve(config, "pyformat", **kwargs), psycopg_executor(connection))
+
+
+# ------------------------------------------------------------------------- asyncpg
+
+
+def asyncpg_executor(connection: Any) -> Any:
+    """An executor over an asyncpg connection or pool.
+
+    Both expose ``fetch``, so one function covers them, and asyncpg's ``Record`` is
+    already a mapping.
+    """
+
+    async def execute(sql: str, params: list[Any]) -> list[Any]:
+        return list(await connection.fetch(sql, *params))
+
+    return execute
+
+
+def for_asyncpg(
+    connection: Any, config: Optional[Config] = None, **kwargs: Any
+) -> AsyncHybridSearch:
+    """Wire an asyncpg connection or pool. asyncpg speaks ``$1``."""
+    return AsyncHybridSearch(_resolve(config, "numeric", **kwargs), asyncpg_executor(connection))
+
+
+# ---------------------------------------------------------------------- SQLAlchemy
+
+
+def sqlalchemy_executor(bind: Any) -> Any:
+    """An executor over a SQLAlchemy Session, Connection or Engine.
+
+    Uses ``exec_driver_sql``, which hands the statement to the DBAPI untouched, rather
+    than ``text()``. ``text()`` would have to bind ``:p0`` style parameters, and in
+    Postgres ``:`` is ambiguous with the cast operator: SQLAlchemy silently declines to
+    bind ``:p0`` in ``:p0::vector`` and the server then reports a syntax error at a colon
+    that looks nothing like the cause. The alternative — emitting ``CAST(x AS vector)``
+    throughout — would make the generated SQL less idiomatic for every user in order to
+    suit one ORM.
+    """
+
+    def execute(sql: str, params: list[Any]) -> list[dict[str, Any]]:
+        # A Session has .connection(); an Engine has .connect(); a Connection is already
+        # what we need. Engines are handled last because a Session also exposes .connect
+        # on some versions.
+        if hasattr(bind, "connection") and callable(bind.connection):
+            connection = bind.connection()
+            result = connection.exec_driver_sql(sql, tuple(params))
+            return [dict(row) for row in result.mappings()]
+        if hasattr(bind, "exec_driver_sql"):
+            result = bind.exec_driver_sql(sql, tuple(params))
+            return [dict(row) for row in result.mappings()]
+        with bind.connect() as connection:
+            result = connection.exec_driver_sql(sql, tuple(params))
+            return [dict(row) for row in result.mappings()]
+
+    return execute
+
+
+def for_sqlalchemy(bind: Any, config: Optional[Config] = None, **kwargs: Any) -> HybridSearch:
+    """Wire a SQLAlchemy Session, Connection or Engine."""
+    return HybridSearch(_resolve(config, "pyformat", **kwargs), sqlalchemy_executor(bind))
+
+
+# -------------------------------------------------------------------------- Django
+
+
+def django_executor(using: str = "default") -> Any:
+    """An executor over a Django database connection.
+
+    Django's Postgres backend is psycopg, so the placeholder style is ``%s`` and the
+    connection is taken from ``django.db.connections`` at call time rather than at
+    import time — the alias may not be configured yet when the module is imported.
+    """
+
+    def execute(sql: str, params: list[Any]) -> list[dict[str, Any]]:
+        from django.db import connections
+
+        with connections[using].cursor() as cursor:
+            cursor.execute(sql, params)
+            return _as_mappings(cursor)
+
+    return execute
+
+
+def for_django(
+    config: Optional[Config] = None, using: str = "default", **kwargs: Any
+) -> HybridSearch:
+    """Wire a Django database connection by alias."""
+    return HybridSearch(_resolve(config, "pyformat", **kwargs), django_executor(using))