Skip to content

Deployment

Minimal deployment

saige needs one database and nothing else: a single PostgreSQL 18 server with two extensions.

Component Role
PostgreSQL 18 or later Conversation trees, checkpoints, RAG documents, and the knowledge graph. postgres.RunMigrations refuses older servers.
pgvector (vector) Embedding columns and HNSW vector search.
ParadeDB pg_search (pg_search) The BM25 index on rag_variant (variant text, section heading, document title), used by rag/pgstore keyword search.
LISTEN/NOTIFY Built into PostgreSQL. Cross-process notifications use it, so no separate message broker is needed.

There is no Redis, no separate search engine, and no in-process index to rebuild. Every saige process connected to the database sees the same vectors, the same BM25 index, and the same notifications.

The paradedb/paradedb image ships PostgreSQL 18 with both extensions. CI and the integration compose file pin this tag:

docker run -d --name saige-postgres -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  paradedb/paradedb:0.26.1-pg18

Then run migrations once per release, before the new version serves traffic:

pool, err := postgres.NewPool(ctx, postgres.Config{URL: dsn})
if err != nil {
    return err
}
if err := postgres.RunMigrations(ctx, pool, postgres.MigrationOptions{}); err != nil {
    return err // ErrUnsupportedServer or ErrExtensionUnavailable name the missing piece
}

RunMigrations checks server_version_num (180000 or higher) and runs CREATE EXTENSION IF NOT EXISTS for vector and pg_search. The role needs permission to create both extensions, or a superuser must create them first.

Hybrid search on Postgres

A pipeline over rag/pgstore built with rag.WithBM25 searches through Postgres: pgstore.Store implements types.KeywordSearcher, so the BM25 arm runs @@@ with pdb.score against the index, with the same scope, time-range, content-type, and metadata filters as vector search. The pipeline fuses both arms with its fuser (RRF by default). To compose retrievers by hand, use pgstore.NewKeywordRetriever(store) next to a vector retriever.

The BM25 index lives with the rows it indexes. Inserts, ReplaceDocument, and DeleteDocument update it in the same transaction, so rag.RebuildIndex is not needed. The in-memory rag/bm25retriever remains for rag/memstore.

The index idx_rag_variant_bm25 covers rag_variant (id, text, section_heading, document_title). A BM25 index covers one table, so each variant row keeps a copy of its section heading and document title, written when the variant is inserted. Databases created before these columns existed are upgraded by RunMigrations: it adds the columns, copies the heading and title onto every variant, and rebuilds the index once. The rebuild reads the whole table, so on a large deployment run that migration in a maintenance window.

Structured keyword queries (types.WithKeywordQuery, see the rag README) compile to pg_search 0.26 query builders with every value bound as a parameter:

types.KeywordQuery pg_search
default, KeywordAll paradedb.match(field, $n), with conjunction_mode => true for all terms
KeywordPhrase, Slop paradedb.phrase(field, tokens, slop => $n); one term falls back to a match
Fuzziness, Transpositions paradedb.match(..., distance => $n, transposition_cost_one => ...)
Prefix paradedb.fuzzy_term(field, token, 0, false, true) per term, or fuzzy match with prefix => true
Must, Should, MustNot paradedb.boolean(must => ..., should => ..., must_not => ...)
Fields boosts paradedb.boost($n, ...) over text, document_title, section_heading
Highlight pdb.snippet(v.text, ...) and pdb.snippet_positions(v.text)

To see what a query matches, run the same builders in psql:

SELECT v.uuid, pdb.score(v.id), pdb.snippet(v.text)
FROM rag_variant v
WHERE v.id @@@ paradedb.boolean(
  must => ARRAY[paradedb.match('text', 'connection reset')],
  should => ARRAY[paradedb.boost(3, paradedb.match('document_title', 'connection reset'))])
ORDER BY pdb.score(v.id) DESC
LIMIT 5;

Managed Postgres

A managed service works when it offers PostgreSQL 18 and lets you install both vector and pg_search. Services that offer pgvector but not pg_search cannot run the migrations.

Licensing

pg_search is licensed under AGPL-3.0, separately from saige. It runs inside the PostgreSQL server as an extension; saige talks to it over the ordinary Postgres protocol and does not link or redistribute it. Review the AGPL-3.0 terms for how you deploy and modify the database server, and see ParadeDB for commercial licensing.