pgsemantic

Turn any PostgreSQL database into a semantic search engine. Set up in 60 seconds. No migrations, no new infrastructure.

pgsemantic connects to your existing PostgreSQL database, picks up your text columns, and makes them searchable by meaning. No data migration, no vector database, no pgvector expertise. It works on your live tables and keeps everything in sync automatically.

3,000 news articles visualized by semantic similarity. Each dot is a row in the database. Colors are auto-detected topic clusters. This is what your data looks like when you can search it by meaning.

What makes this different

Most vector search tools ask you to set up a separate vector database, write ETL pipelines, and maintain sync logic. pgsemantic works directly on your existing PostgreSQL tables:

No new database — embeddings live alongside your data (inline column or shadow table)
No ETL — a database trigger keeps embeddings in sync as rows change
No expertise needed — point it at a table, pick a column, done
Free by default — runs a local embedding model on your machine (no API keys)

See it in action

Connect to any PostgreSQL database

Paste your connection string, test it, done. Works with localhost, Supabase, Neon, RDS — anything with pgvector.

Browse and explore your tables

See every table, column types, and row counts. Click Inspect to score columns for semantic search suitability.

Set up with chunking for long documents

Pick columns, choose a model, enable chunking for long text. Chunking splits documents into overlapping paragraphs so search finds the best paragraph, not just the best document.

Search by meaning, not keywords

Query: "economic recession" — returns articles about inflation, unemployment, consumer prices. These results share the concept, not the exact words.

Search across all your tables at once

"health treatment side effects" across clinical_trials and news_articles. Results ranked by similarity regardless of source table. Purple badges show where each result came from.

See how your data clusters

3,000 embeddings reduced to 2D with PCA. K-means clustering auto-labels each group with its top keywords. Click any point to see the full row.

Run SQL queries directly

Built-in SQL query tool. Read-only, 10-second timeout, 100-row limit. Safe to explore.

Monitor everything from one dashboard

Coverage, pending queue, worker health — all in one view.

10 MCP tools for AI agents

Connect Claude Desktop, Cursor, or any MCP-compatible AI agent. They can search semantically, run SQL queries, and explore your schema.

Quick start

pip install pgsemantic

# Launch the web UI
pgsemantic ui

# Or use the CLI
pgsemantic inspect   # Scan your DB, score columns
pgsemantic apply --table articles --column body   # Set up semantic search
pgsemantic index --table articles                  # Embed existing rows
pgsemantic search "climate policy effects"         # Search by meaning

Open http://localhost:8080 and walk through setup visually:

Connection — paste your PostgreSQL URL
Tables — browse your database
Apply — pick columns, choose a model, one click
Index — embed all rows (progress bar, resumable)
Search — natural language queries, instantly

Features

Core

| Feature | Description | |---------|-------------| | Semantic search | Search by meaning, not keywords. "budget travel" finds "affordable hostels" | | Cross-table search | Search all configured tables at once — results merged by similarity | | Auto-chunking | Split long documents into overlapping chunks for precise paragraph-level search | | Hybrid search | Combine semantic similarity with SQL WHERE filters in one query | | Multi-column embedding | Embed title + description + tags as one combined vector | | Automatic sync | Database triggers keep embeddings fresh on every INSERT/UPDATE/DELETE |

Operations

| Feature | Description | |---------|-------------| | Zero-downtime model migration | Switch embedding models without breaking search — atomic swap | | Pipelined indexing | Embeds batch N+1 while writing batch N — ~2x throughput | | Background worker | Daemon process for continuous embedding sync with retry logic | | Shadow table storage | Store embeddings separately without modifying your source table |

Visualization & Analytics

| Feature | Description | |---------|-------------| | Embedding scatter plot | 2D PCA visualization with auto-detected clusters and keyword labels | | SQL query tool | Run read-only queries from the UI (10s timeout, 100-row limit) | | Status dashboard | Coverage %, pending queue, failed jobs, worker health — all in one view |

AI Agent Integration (MCP)

10 tools for Claude Desktop, Cursor, and any MCP-compatible agent:

| Tool | What it does | |------|-------------| | semantic_search | Find rows by meaning | | hybrid_search | Semantic + SQL filters | | search_all_tables | Cross-table search | | get_schema_context | Table schemas for SQL generation | | execute_safe_sql | Run read-only SQL queries safely | | get_embedding_status | Check embedding coverage | | list_tables | Browse all tables | | get_sample_rows | Preview table data | | inspect_columns | Score columns for search suitability | | list_configured_tables | List configured tables |

Embedding models

| Model | Dimensions | Cost | Best for | |-------|-----------|------|---------| | Local Fast (all-MiniLM-L6-v2) | 384 | Free | Getting started, most use cases | | Local Better (all-mpnet-base-v2) | 768 | Free | Higher accuracy | | OpenAI Small (text-embedding-3-small) | 1536 | ~$0.02/1M tokens | Production, multilingual | | OpenAI Large (text-embedding-3-large) | 3072 | ~$0.13/1M tokens | Maximum accuracy | | Ollama (nomic-embed-text) | 768 | Free | Self-hosted, privacy-sensitive |

Switch models anytime with zero-downtime migration:

pgsemantic migrate --table articles --model openai

Works with any PostgreSQL

Local PostgreSQL + pgvector
Supabase (enable pgvector in Dashboard > Database > Extensions)
Neon
Amazon RDS / Aurora PostgreSQL
Google Cloud SQL for PostgreSQL
Any self-hosted PostgreSQL with pgvector

Architecture

Your App ──────────────────────────────────────────────────┐
                                                           │
CLI (Typer) ─┐                                             │
Web UI (FastAPI) ─┤──> Embedding Providers ──> PostgreSQL + pgvector
MCP Server (FastMCP) ─┘   (local/openai/ollama)    │
                                                    ├── Source tables (your data)
Background Worker ──> Job Queue ────────────────────├── Shadow tables (embeddings)
                                                    └── HNSW indexes (fast search)

No external services — everything runs locally (unless you choose OpenAI)
No build step — the web UI is vanilla HTML/JS/CSS in a single file
No external dependencies in the frontend — no React, no Tailwind, no CDN

Security

Database URL never sent to the browser — stays server-side only
CSRF protection on all POST endpoints
SQL injection prevention via Pydantic validation + regex on identifiers
Rate limiting — 120 requests/minute per IP
Content Security Policy, X-Frame-Options, and security headers on all responses
SQL Query tool enforces read-only transactions with 10-second timeout
.env written with chmod 600 — owner-read-only

CLI reference

pgsemantic inspect          # Scan DB, score columns
pgsemantic apply            # Set up semantic search on a table
pgsemantic index            # Bulk embed exi

Pgsemantic

Install / Use

README