samples/pgvector_1 — awesome-ai-stack

Example

pgvector — vector similarity search in Postgres

A real, runnable mini-project. Download it and run with Docker.

View samples/pgvector_1 on GitHub ↗

June 28, 2026

pgvector — vector similarity search in Postgres

A tiny pgvector demo: it creates a vector column, stores a few toy 3-dim "embeddings", and runs a nearest-neighbour query with the cosine-distance operator (<=>). Swap the toy vectors for an embedding model's output and the SQL is unchanged.

Run with Docker Compose (bundled Postgres)

The compose file starts a pgvector/pgvector Postgres and runs the app against it:

cd samples/pgvector_1
docker compose up --build

No .env is needed here — compose sets DATABASE_URL to the bundled database automatically.

Change the query word in docker-compose.yml (command: ["cat"]) — try rocket to see the neighbours flip.

Run with Docker Compose (in a devcontainer with DooD)

In a dev container that talks to the host Docker daemon (Docker-outside-of-Docker), the attached docker compose up may print nothing for the app even though it ran — the live attached stream drops output over the VM boundary. Read it back from the logs:

cd samples/pgvector_1
docker compose up --build -d
docker compose logs -f app
docker compose down -v

Run locally

Point DATABASE_URL at a Postgres that has the vector extension available:

cd samples/pgvector_1
cp .env.sample .env          # edit DATABASE_URL if needed
pip install -r requirements.txt
python app.py cat

.env is gitignored — only .env.sample is committed.

Example run

Unlike the LLM samples, this one is deterministic — the toy vectors are fixed, so the output is identical every run.

nearest to 'cat' by cosine distance:
  cat        0.0000  (query)
  kitten     0.0129
  rocket     0.8901
  airplane   0.9901

.env.sample

# pgvector needs a Postgres with the `vector` extension. The bundled
# docker-compose.yml starts one for you and sets this automatically.
#
# For a local run (`python app.py`), copy this to `.env` and point it at your
# own Postgres:
#   cp .env.sample .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

app.py

"""pgvector: vector similarity search inside Postgres.

Creates a `vector` column, stores a few toy "embeddings", and runs a
nearest-neighbour query with the cosine-distance operator (`<=>`). A real app
swaps the toy vectors for an embedding model's output — the SQL is identical.

Run (with the bundled Postgres):
    docker compose up --build
"""

import os
import sys

import psycopg
from dotenv import load_dotenv

# Load .env when running locally; docker-compose sets DATABASE_URL directly.
load_dotenv()

DSN = os.environ.get("DATABASE_URL", "postgresql://postgres:postgres@localhost:5432/postgres")

# Toy 3-dim "embeddings" — in practice these come from an embedding model.
DOCS = [
    ("cat", "[1.0, 0.1, 0.0]"),
    ("kitten", "[0.9, 0.2, 0.1]"),
    ("airplane", "[0.0, 0.1, 1.0]"),
    ("rocket", "[0.1, 0.0, 0.9]"),
]


def main() -> None:
    target = (sys.argv[1] if len(sys.argv) > 1 else "cat").lower()
    query_vec = dict(DOCS).get(target, DOCS[0][1])

    with psycopg.connect(DSN, autocommit=True) as conn:
        conn.execute("CREATE EXTENSION IF NOT EXISTS vector")
        conn.execute("DROP TABLE IF EXISTS docs")
        conn.execute("CREATE TABLE docs (id serial PRIMARY KEY, label text, embedding vector(3))")
        for label, embedding in DOCS:
            conn.execute("INSERT INTO docs (label, embedding) VALUES (%s, %s)", (label, embedding))

        rows = conn.execute(
            "SELECT label, embedding <=> %s::vector AS distance FROM docs ORDER BY distance LIMIT 4",
            (query_vec,),
        ).fetchall()

    print(f"nearest to '{target}' by cosine distance:")
    for label, distance in rows:
        marker = "  (query)" if label == target else ""
        print(f"  {label:10s} {distance:.4f}{marker}")


if __name__ == "__main__":
    main()

docker-compose.yml

# pgvector needs a Postgres with the `vector` extension. This bundles one
# (the official pgvector image) and runs the sample app against it.
#   docker compose up --build
services:
  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_PASSWORD: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      timeout: 3s
      retries: 15

  app:
    build: .
    environment:
      DATABASE_URL: postgresql://postgres:postgres@db:5432/postgres
    depends_on:
      db:
        condition: service_healthy
    # The query word — try "rocket" to see the neighbours flip.
    command: ["cat"]

Dockerfile

# Minimal image for the pgvector sample app.
# Postgres (with the vector extension) runs as a separate service — see
# docker-compose.yml.
FROM python:3.13-slim

# Stream stdout/stderr unbuffered so the output appears live.
ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

# DATABASE_URL points at your Postgres (the bundled one is set in compose):
#   docker compose up --build
ENTRYPOINT ["python", "app.py"]