Skip to main content
Esta página ainda está em inglês. A tradução para português está em andamento.

​
Knowledge — database setup

The Knowledge base stores chunked documents with vector embeddings in PostgreSQL + pgvector. This page collects the gotchas you need to know before pointing it at a managed database.

​
Requirements

  • PostgreSQL 14+ with the pgvector extension available.
  • Session mode connections. Transaction pooling (PgBouncer in transaction-pooling mode) is not supported, see below.
  • Privileges sufficient to run CREATE EXTENSION IF NOT EXISTS vector, CREATE INDEX ... USING hnsw, and Alembic migrations on first connect.

​
Provider cheat-sheet

​
Supabase

Supabase exposes two Postgres endpoints per project: Use the direct connection string Supabase shows in Project Settings → Database → Connection string → URI. It looks like:
If you pasted the pooler URL (port 6543 or hostname containing pooler) the wizard fails fast with a Knowledge is not compatible with PgBouncer in transaction pooling mode error. That’s by design — the Alembic migrations and CREATE INDEX ... USING hnsw statements rely on prepared statements and session-scoped state that PgBouncer’s transaction pooling silently drops. If you genuinely need pooling (for example, your Supabase project is on a plan with a connection limit), use the session pooler endpoint Supabase exposes on port 5432. It keeps prepared statements working while still bounding the number of backend connections.

​
IPv6-only direct connection

New Supabase projects default to IPv6-only on the direct endpoint. If your host does not have IPv6 connectivity the connection will fail with
Workarounds:
  1. Enable the IPv4 add-on in Supabase (paid feature).
  2. Use the session pooler URL on port 5432 — it is dual-stack.
  3. Run Knowledge on a host with native IPv6 (most cloud providers do).

​
Neon, Railway, Render, Fly, Heroku

Same rule: give Knowledge the session-mode connection string. Neon and Railway both expose a pooler; pick the non-pooler URL from the dashboard. The fast-fail check triggers on port 6543 and on hostnames containing pooler.

​
Self-hosted Postgres

Nothing special — just make sure pgvector is installed (CREATE EXTENSION vector runs as superuser or owner of the target database) and that the user in your connection string can create extensions and indexes.

​
Error reference

  • Wizard: Knowledge → Connections → New in the dashboard.
  • Source for the validation: dashboard/backend/knowledge/auto_migrator.py.