Postgres and ParadeDB

Copy Markdown View Source

Postgres is Exograph's built-in backend. Exograph uses Ecto migrations, schemas, Repo operations, and transactions for source files, fragments, comments, definitions, references, package metadata, and call graph facts.

ParadeDB's pg_search extension is optional and accelerates BM25 text/code-fact retrieval when available.

Indexing with Postgres

{:ok, index} =
  Exograph.index("lib",
    repo: MyApp.Repo,
    migrate?: true,
    bm25?: true
  )

backend: :postgres is accepted explicitly, but Postgres is the only built-in backend.

Tables

The canonical migration creates normalized Ecto-backed tables including:

  • exograph_packages
  • exograph_package_versions
  • exograph_files
  • exograph_fragments
  • exograph_comments
  • exograph_definitions
  • exograph_references
  • exograph_graph_nodes
  • exograph_call_edges
  • exograph_tree_nodes

Fragments store package, package version, and file IDs. Source text is stored once in exograph_files.

When ParadeDB's pg_search extension is available, migrate?: true can create BM25 indexes over source files, comments, definitions, and references. Source files use ParadeDB's pdb.source_code tokenizer; symbol names use tokenizers such as pdb.ngram for prefix/partial matching.

Raw SQL is limited to areas Ecto cannot express directly:

  • CREATE EXTENSION
  • ParadeDB USING bm25
  • ParadeDB tokenizer casts such as source::pdb.source_code
  • ParadeDB operators such as ||| and &&&
  • ParadeDB scoring such as pdb.score(...)

Fallback behavior

Exograph remains usable without ParadeDB. Text/code-fact search falls back to Postgres-backed candidate retrieval plus verification where applicable.

CLI examples

mix exograph.index --backend postgres --repo MyApp.Repo --migrate lib test
mix exograph.search 'Repo.get!(_, _)' --backend postgres --repo MyApp.Repo --migrate lib
mix exograph.search 'running shoes' --text --backend postgres --repo MyApp.Repo --migrate lib

Testing

The test suite validates real indexing, structural search, selector search, text search, tree-node lookup, code-fact lookup, similarity search, and DSL queries against Postgres.

EXOGRAPH_DATABASE_URL=postgres://postgres:postgres@localhost:5432/exograph_test \
  mix test