Production Hosting: Supabase and pgvector
From a local folder to Supabase + pgvector: managed vs self-hosted, the walkthrough, the operations.
Everything you have built so far lives in a folder. persist_directory="./chroma_db/" is a development posture: one process, one disk, no concurrency, no backup, no access control, and a corpus that evaporates the moment you docker build without a volume. The course marks the transition with one sentence:
"So, you've built locally. Now, let's deploy." 03:33:18
This part is that move. It answers three questions in order: whose Postgres do I buy, how do I get the exact pipeline I already have onto it, and what did I just take on operationally that I did not have when the store was a folder. The hands-on spine is the course's Supabase walkthrough at 03:36:00–03:54:27.
In terms of the mental model from Part 1, this part touches exactly one box — Phase A's Store + Index — and does not touch any other. The loaders, the splitter, the embedding model, the retriever, the prompt and the chain are all unchanged. What changes is the physical address of the vectors and, less obviously, the third budget: money stops being an API bill and starts being a monthly line item, plus egress, plus your time.
The one-line claim, and why it is only half true
The central pedagogical claim of the Supabase chapter is that moving to production changes exactly one line of Python:
"Exactly the same thing that we had locally… now we have it somewhere we can connect to in the cloud." 03:52:22
At the level of the retrieval code this is genuinely true, and it is true because of a design decision you inherited for free: LangChain's VectorStore interface is a real seam. The Chroma constructor and the PGVector constructor take different kwargs but expose the same add_documents / similarity_search / similarity_search_with_score / as_retriever surface, so every consumer downstream of the store is indifferent to which one is behind it.
Here is the "before" — real, shipped, local code:
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py (persist_chroma)
def persist_chroma():
persist_dir = "./chroma_db/"
vectorstore = Chroma.from_documents(
documents=SAMPLE_DOCS,
embedding=embeddings_model,
persist_directory=persist_dir,
)
original_count = vectorstore._collection.count()
print(f"Persisted vector store with {original_count} documents.")
print(f"Vector store persisted at: {persist_dir}")
# simulate restart - load from disk
del vectorstore
reloaded = Chroma(
embedding_function=embeddings_model,
persist_directory=persist_dir,
)
And the "after" is the same shape with a DSN where the directory was. The integration package is langchain-postgres (uv add langchain-postgres), which pulls in SQLAlchemy 2, the pgvector Python bindings, and psycopg 3 — not psycopg2, which matters in a moment. Note the import path carefully: it is langchain_postgres, not langchain_community, exactly as it appears on screen at 03:42:35. This is the same install-time trap as langchain-chroma versus langchain-community in Part 2, and it produces the same confusing deprecation-shaped errors when you get it wrong.
# The production swap. Same interface, different engine.
from langchain_postgres import PGVector # NOT langchain_community
vectorstore = PGVector(
embeddings=embeddings_model, # note: `embeddings=`, not `embedding=`
collection_name="production_docs",
connection=DATABASE_URL, # postgresql+psycopg://postgres:...@db.<ref>.supabase.co:5432/postgres
embedding_length=1536, # text-embedding-3-small; without it you cannot index
use_jsonb=True,
)
Three of those five arguments are traps, and the course only discusses one of them.
| Concept | Chroma | PGVector |
|---|---|---|
| Embeddings kwarg | embedding= (and embedding_function= when re-opening) | embeddings= |
| Where the data lives | persist_directory= | connection= (a DSN string, or a SQLAlchemy Engine) |
| Logical partition | collection_name → a real Chroma collection | collection_name → a row in langchain_pg_collection |
| Metadata storage | implicit | use_jsonb=True |
| Vector dimension | inferred, invisible | embedding_length= — omitted by default, and then nothing can be indexed |
So the code claim holds. What does not hold is the implication that the migration is therefore free. Between the constructor and a system you would put a user in front of, you have acquired: row-level security you have to turn on by hand, a connection-pooling decision the course explicitly skips, an ANN index nobody created for you, a storage cap measured in megabytes, an egress cap, and a network round trip where there used to be a page-cache read. Those are the rest of this part.
Managed or self-hosted: the trade you are actually making
Part 8 tuned the index and Part 9 priced it. The short version you need here, so the vendor comparison has a frame: the source's scale bands put under 100K vectors on local Chroma, 100K–1M on Pinecone serverless, 1M–10M on managed pgvector, and 10M+ on self-hosted pgvector 03:31:53. The three hosting options in this part are the concrete vendors for that managed pgvector band — which is where almost every real system starts and most of them stay.
Invariant 5 — every layer is a "pick 2" — shows up here as money / ops burden / control:
| Managed (Supabase, Neon, RDS) | Self-hosted Postgres + pgvector | |
|---|---|---|
| Ops burden | Near zero — no patching, no pg_upgrade, no backup cron, no replication wiring | "Very significant" 03:21:10 |
| Cost at 500K vectors | ~$35/mo | ~$20/mo, plus your hours |
| Cost at 5M / 50M vectors | ~$100 / ~$400 per month | ~$75 / ~$300 per month |
| Control | Limited — you get the knobs the vendor exposes | Full |
| Failure ownership | Vendor's pager | Yours |
Those figures are Part 9's divergence chart 03:24:59–03:26:20. Read the shape, not the digits: the managed premium is roughly $15/month at 500K and $100/month at 50M — a rounding error next to a single engineer-day per month of Postgres administration. The gap that does explode on that chart is Pinecone versus pgvector ($1,500+ vs $300 at 50M), not managed versus self-hosted pgvector.
The instructor's position, carried forward from the cost chapter, is unambiguous: start managed. The time you save is worth more than the price delta, and you can move later precisely because pgvector is the same extension in both worlds.
"We focus mostly on pgvector because it's open source and it's easy to attach as an extension to a Postgres database, and it works." 03:52:22
That sentence is the whole strategic argument. pgvector is not a new operational surface. It is a column type in a database your organisation already knows how to back up, replicate, monitor, grant on and restore. A dedicated vector database is a second stateful system with a second backup story, a second auth model and a second on-call runbook. Every one of the three hosting options below is a managed Postgres — no dedicated vector database survives the shortlist, and that is the point being made by omission.
The three paths to production
The source narrows the market to three, and is honest that it is a market shortlist rather than a benchmark result:
"Of course, there's more, but I narrow down to three that are the most sought out." 03:33:18
The selection criterion is stated as demand, not technical superiority. Railway, Fly.io, Render, Crunchy Bridge, Timescale/Tiger, DigitalOcean Managed Postgres, Cloud SQL, AlloyDB and plain self-hosted Docker Postgres all exist, all run pgvector, and none of them were evaluated and rejected — they were simply not on the slide.
| Supabase | Neon | AWS RDS | |
|---|---|---|---|
| Slide tag | ★ Recommended | 🏷 Serverless | 🏷 Enterprise |
| Slide headline price | $25/mo | $19/mo | $60/mo |
| Free tier | $0, 500 MB database | $0, 512 MB storage | no permanently-free plan |
| First paid tier | Pro $25/mo, ~8 GB database | Pro ~$19/mo | small ~$30/mo, mid-tier ~$60/mo |
| Larger tier | Team ~$599/mo | — | scales into the hyperscaler's catalogue |
| pgvector | included, all tiers | included | supported on the Postgres engine |
| Differentiator | best value per dollar; a genuinely free free tier; auth + REST + storage in the same product | scale to zero — you stop paying for idle compute | completeness: Multi-AZ, PITR, IAM, VPC, read replicas |
| Picks it | default; anything steady-state | variable / bursty / idle-heavy workloads | teams already inside AWS |
One row in that table is noise and you should ignore it: the free tiers are a tie. Supabase's 500 MB and Neon's 512 MB differ by 12 MB — 2.4%, and 512 MB is simply 0.5 GiB expressed exactly against a round marketing number. Nothing is decided there.
Prices are as printed on the slide and as spoken at 03:33:18–03:35:20. The instructor hedges them himself — "about 8 GB", "as of recording this video" — and the video was published 2026-05-26. Treat these as the shape of the market, not as quotes. Vendor pricing pages are the only source of truth for the number you will actually pay.
Three corrections to the source, stated plainly rather than laundered:
- The Supabase Team tier is $599/month, not $5.99. The auto-generated captions render it as "$5.99" in both chapter 17 03:34:19 and chapter 18 03:37:00 — the same figure spoken twice, with a dropped decimal point. A team tier priced below the $25 Pro tier is impossible. Print $599.
- AWS RDS pricing is stated inconsistently by the instructor. At 03:34:19 the "starting point is $60 a month"; at 03:35:20 "the mid-tier instance… is about $60 a month and the small is about $30 a month." The coherent reading is ~$30 small / ~$60 mid-tier, with the slide headlining the mid-tier. Note also that the cost chapter's independent figure — pgvector on RDS ≈ $32/month at 500K vectors 03:23:35 — agrees with the "small ≈ $30" reading, which is good corroboration.
- "Teams already on AWS or Google Cloud Platform" 03:35:20 is loose: RDS is AWS-only. The correct generalisation is stay inside the cloud your org already uses; on GCP the analogues are Cloud SQL for PostgreSQL and AlloyDB, both of which support pgvector.
The decision procedure, which is short enough to memorise:
- Default to Supabase. Free tier to learn and prototype; $25 Pro when you outgrow 500 MB.
- Choose Neon instead if your workload is variable or idle-heavy and you can absorb a cold start.
- Choose RDS (or Cloud SQL / AlloyDB) if your team already lives in that hyperscaler. The deciding factor is your perimeter, not the price.
- Re-run the arithmetic on your own numbers before accepting the default — the recommendation is a starting point, not a law.
- Verify pgvector is available on the tier you pick. All three include it. A fourth vendor might not.
- Learn on the free tier; upgrade on a measured limit — storage, connections, or egress — not on a feeling.
The last one is a promise the course keeps: every remaining hands-on chapter is designed to fit inside Supabase Free, and the instructor says so — "you won't need to spend a dime" 03:35:20.
Supabase, concretely
Supabase describes itself as "the Postgres development platform" — build in a weekend, scale to millions — and the bundle is: a Postgres database, authentication, instant auto-generated APIs, Edge Functions, realtime subscriptions, file storage, and vector embeddings 03:36:00. That last bullet is pgvector. You are not adopting a new vector database; you are moving the same extension from your laptop to somebody else's managed Postgres.
That bundling is most of the reason it wins the recommendation. A real RAG application usually also needs auth, an API layer and somewhere to put the source PDFs. If you would otherwise buy those from three vendors, the $25 comparison is not $25-vs-$19.
Free tier, in full (03:36:00–03:37:00, read off the pricing page):
| Free tier line item | Value |
|---|---|
| Price | $0/month |
| Database size | 500 MB (sub-line on the card: Shared CPU • 500 MB RAM) |
| API requests | Unlimited |
| Monthly active users | 50,000 |
| Egress | 5 GB |
| Cached egress | 5 GB |
| File storage | 1 GB |
| Support | Community |
Paid steps: Pro $25/month (labelled "most popular", ~8 GB database), Team $599/month.
The walkthrough, end to end
The teaching device the course uses here is deliberate repetition on a different backend — same documents, same embedding model, same similarity search, new store:
"…do exactly what we've done earlier. So you can see the full picture." 03:35:20
That is worth copying when you migrate for real. Re-run a workload you already know the answers to, so that anything that changes is attributable to the store and nothing else.
What follows is the 03:36:00–03:54:27 sequence, reorganised so that the two security decisions sit next to each other instead of fifteen minutes apart.
Step 1 — Create the organisation and the project
- supabase.com → Pricing → read the Free card → Start for free → log in.
- Create an organisation first — organisations wrap projects. Name it (the course uses
VectorCourse), type Personal, plan $0/month. - New project. A project is "its own dedicated instance": name it, then handle the three things below. When it finishes provisioning you land on branch
main, badgedPRODUCTION.
The database password. The form has a Generate a password button. Copy it before you click anything else. It is shown once and is not retrievable — only resettable. It becomes the [PASSWORD] slot in every connection string you will ever paste.
"I'm going to copy this password because you will actually going to need that password later." 03:38:02
Lost it? Database → Settings → Reset database password → Generate → Reset. Generating a new value is not enough; you must click Reset for it to take effect 03:43:06, then update .env.
The region. The form says to select the region closest to your users. The course picks East US (North Virginia) us-east-1, which carries a RECOMMENDED badge; the Americas list on screen also shows us-west-1 (N. California), us-west-2 (Oregon), us-east-2 (Ohio), ca-central-1, and eu-west-1 in Europe.
Refine that advice one step: choose for where your application server runs, not where you or your users sit. A user makes one round trip to your app; your app makes several to the database per request (fetch the collection row, run the ANN search, pull the chunk text), and each one is multiplied by every retry and every extra query. Co-locate app and database, then worry about the user. Region is also effectively permanent — Supabase has no in-place region move, so changing it means a new project and a full re-ingest.
(Source noise, flagged: at 03:38:02 the captions have the instructor offer "West North Carolina" as an alternative region. No such Supabase region exists. Treat it as a mis-speak or a caption artefact; only us-east-1 is confirmed on screen.)
The two security switches — read this before you click Create. The new-project form has:
- Enable Data API — checked by default. It "autogenerate[s] a RESTful API for your public schema", which is what makes
supabase-jswork from a browser. - Enable automatic RLS — unchecked by default. It creates an event trigger that turns on Row Level Security for every new table in the
publicschema.
Step 2 — Harvest the credentials
Click Connect in the top bar. The modal offers four tabs, and they are not interchangeable 03:39:02:
| Tab | What it gives you | Use when |
|---|---|---|
| Framework | client-library snippets (supabase-js etc.) | you are calling Supabase from app code via the Data API |
| Direct | a raw Postgres connection string | this is the one you want — LangChain speaks Postgres |
| ORM | Prisma/Drizzle-style config | your app already has an ORM |
| MCP | connect an agent to the project | agent tooling |
Inside Direct, there are three connection methods, and picking wrong is a production incident rather than a syntax error. Supabase's own copy maps them onto process lifetime:
| Method | Vendor's framing | Choose it for |
|---|---|---|
| Direct connection | persistent, long-lived connections | a long-running FastAPI/uvicorn service, a worker, a VM, "long-standing containers" |
| Transaction pooler | stateless callers, each interaction "brief and isolated" | Lambda, Vercel/Cloudflare functions, anything that cold-starts per request |
| Session pooler | an alternative to direct "when connecting via an IPv4 network" | your network or platform cannot reach the IPv6-only direct host |
The Type toggle switches the same information between URI and PSQL packaging. It is worth understanding the five facts rather than memorising the blob 03:40:02:
| Piece | Value |
|---|---|
| database | postgres |
| user | postgres |
| port | 5432 — "the port is very important" |
| host | db.<project-ref>.supabase.co |
| password | the one you saved at project creation |
The project ref is the random subdomain identifying your instance — the course's is yynnyoubueyfbvgnpzpq; yours differs. It appears in the host and in every dashboard URL. While you are here, also copy the Project URL and the publishable key — not needed for the pgvector path, but needed the moment you touch the Data API.
Step 3 — Enable the vector extension
Database → Extensions → search vector → toggle → "Enable vector" dialog → keep schema extensions (DEFAULT) → Enable extension 03:41:02.
Two things make this step nearly redundant, and one thing makes it worth doing anyway. Supabase pre-installs pgvector — the instructor's own source file carries the comment # Note: Supabase has pgvector pre-installed — and PGVector ships with create_extension=True by default, so the library itself issues CREATE EXTENSION IF NOT EXISTS vector (guarded by a Postgres advisory lock) on construction. Click it anyway: it makes the dependency visible in the dashboard, and it is the difference between "it works on my project" and a documented setup step someone else can reproduce. It also matters the day your application connects as a restricted or read-only role that has no right to create extensions — then you enable it here once, by hand, and pass create_extension=False in code.
The SQL equivalent, if you prefer the SQL Editor:
-- Equivalent of the Extensions-page toggle.
CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA extensions;
-- Verify:
SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';
Before you run any code, look at Database → Schema Visualizer: it says "No tables in schema." Remember that. It is what makes the two tables that appear in Step 6 legible as something LangChain built rather than something that was always there.
There are two doors into the schema and the course deliberately picks the second: the SQL Editor (paste CREATE EXTENSION / CREATE TABLE by hand) and your application code (PGVector(...) creates what it needs). "We can actually go to SQL editor and start running those commands… But we're doing everything in code." 03:50:17
Step 4 — Wire the DSN into .env
# .env — never commit this file
SUPABASE_DATABASE_URL=postgresql://postgres:YOUR_REAL_PASSWORD@db.yynnyoubueyfbvgnpzpq.supabase.co:5432/postgres
OPENAI_API_KEY=sk-...
Step 5 — Connect from code and smoke-test
The course's file is pg_vector_section/6-supabase/01_supabase_connection.py.
# RECONSTRUCTED from screen frames at [03:42:35]-[03:45:40]
# pg_vector_section/6-supabase/01_supabase_connection.py
import os
from dotenv import load_dotenv
from langchain_postgres import PGVector # note: langchain_postgres, NOT langchain_community
from langchain_openai import OpenAIEmbeddings
load_dotenv()
# Supabase connection string format:
# postgresql://postgres:[PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres
SUPABASE_URL = os.getenv("SUPABASE_DATABASE_URL")
# For demo, use local if Supabase not configured
DATABASE_URL = SUPABASE_URL or os.getenv(
"DATABASE_URL", "postgresql://postgres:postgres@localhost:5432/postgres"
)
def connect_to_supabase():
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
# Note: Supabase has pgvector pre-installed
vectorstore = PGVector(
embeddings=embeddings,
collection_name="production_docs",
connection=DATABASE_URL,
use_jsonb=True,
)
return vectorstore
Two details in there are worth stealing outright, and one is worth fixing.
SUPABASE_URL or DATABASE_URL is a genuinely reusable pattern 03:44:07. The same script runs against a laptop Postgres with no cloud account and against production with zero edits. It gives you a local integration-test target that is the same engine as production — which a Chroma-locally / pgvector-in-prod split never can.
use_jsonb=True is not decoration 03:44:07, 03:48:13. It stores document metadata as Postgres JSONB — a parsed binary form that supports containment operators and GIN indexes — rather than plain json, which is stored as text and re-parsed on every predicate. That is what lets metadata filters (search_kwargs["filter"]) be evaluated by the database rather than by brute force. Metadata filtering was the Part 4 lesson that semantic proximity is not topical correctness; use_jsonb=True is the switch that keeps that lesson affordable on Postgres. It appears in every PGVector(...) call in the chapter. Keep writing it — although note that in current langchain-postgres the argument has become vestigial: passing use_jsonb=False now raises NotImplementedError, because the plain-JSON path was removed.
The fix: pass embedding_length=1536. The course never does, and the consequence is Step 9's whole problem. The library's own docstring is blunt about it: defining the length prevents differently-sized vectors from being inserted, "but without it, the embeddings can't be indexed." Set it at first construction, before the table exists, and the column is created as vector(1536); forget it and you get a dimensionless vector column that no ANN index can be built on.
The smoke test itself is the right shape, and it is worth naming as a pattern: write → read back → assert → delete. The frames show the call sequence but not the whole function body; this is that sequence written out.
# The verification routine narrated at [03:44:07]-[03:46:09], written to the pattern he describes.
from langchain_core.documents import Document
def verify_collection(vectorstore):
ids = vectorstore.add_documents(
[Document(page_content="test document", metadata={"source": "smoke-test"})]
)
hits = vectorstore.similarity_search("test document", k=1)
assert hits, "connected, but the write is not readable back"
vectorstore.delete(ids=ids) # cleanup, so the smoke test is idempotent
return hits
Expected output on a good run: 🔗 Connecting to Supabase… / Host: db.<ref>.supabase.co / ✅ Connected!. The instructor runs it twice — once clean, then once with the delete commented out so there is a row left to look at in the dashboard 03:46:09. That is a teaching device, not a pattern: keep the cleanup in. A smoke test that leaves residue is a smoke test you will stop running against production.
Step 6 — Look at the schema LangChain built for you
Refresh Database → Tables. There are now two tables you did not write 03:46:09, 03:51:40, 03:53:35:
| Table | Columns | Role |
|---|---|---|
langchain_pg_collection | 3: uuid, name, cmetadata | one row per logical collection; name is the collection_name you passed in Python |
langchain_pg_embedding | 5: id, collection_id, embedding, document, cmetadata | one row per chunk: the vector, the original text, the metadata, and an FK to its collection |
embedding holds the pgvector vector values — on screen they render truncated, as [0.010925293, -0.0…], [-0.057647705, 0.0…], [-0.075805664, 0.0…]. The collection's uuid is a real Postgres UUID (693b2e31-0d86-4b03-9998-43b67d2c3f1… on screen); the embedding row's id is a string primary key that happens to hold a UUID (c2d2b085-5c61-40db-b762-4df9e6a35ebb) — which is why you can supply your own stable ids at add_documents time and make re-ingestion idempotent. The foreign key collection_id → langchain_pg_collection.uuid is declared ON DELETE CASCADE.
Two consequences fall straight out of that, and both are the kind of thing you only learn by having been burned:
- Deleting a collection does not shrink your table's index. Rows go (via the cascade), index bloat stays until a
REINDEXorVACUUM FULL. On a 500 MB free tier that matters. - Multi-tenancy by collection is not isolation. If tenant separation is a requirement, use separate projects/databases or a real RLS policy on
cmetadata, not separatecollection_names.
Step 7 — The production shape: a config object and a service class
The second file the course walks, 03_production_example.py, is the one worth internalising — not because the RAG in it is good (it explicitly is not) but because the shape is right.
"This is not necessarily an optimized RAG system, but it's to show you how to use pgvector from Supabase." 03:48:13
The shape is: one @dataclass Config holding every tunable, and one service class holding the lazily-initialised store plus the four verbs your application actually needs.
The reconstructed Config + RAGService (from frames at 03:47:40–03:50:05)
# RECONSTRUCTED from screen frames — pg_vector_section/6-supabase/03_production_example.py
# Ellipses mark code that was never visible on screen. See the notes below: as printed,
# this class does not run.
@dataclass
class Config:
# Database - use pooler URL in production
database_url: str = os.getenv(
"SUPABASE_DATABASE_URL",
os.getenv("DATABASE_URL", "postgresql://postgres:postgres@localhost:5432/postgres"),
)
collection_name: str = "production_documents"
# Model settings
embedding_model: str = "text-embedding-3-small"
chat_model: str = "gpt-4o-mini"
temperature: float = 0.0
# Search settings
default_k: int = 5
min_similarity: float = 0.5
class RAGService:
"""Production-ready RAG service with pgvector"""
def __init__(self, config: Optional[Config] = None):
self.config = config or Config()
self._vectorstore = None
@property
def vectorstore(self) -> PGVector:
"""Lazy initialization of vectorstore"""
if self._vectorstore is None:
embeddings = OpenAIEmbeddings(model=self.config.embedding_model)
self._vectorstore = PGVector(
embeddings=embeddings,
collection_name=self.config.collection_name,
connection=self.config.database_url,
use_jsonb=True,
)
return self._vectorstore
def _create_chain(self):
... # retriever, prompt, llm are built here, off-screen
def format_docs(docs):
return "\n\n".join(doc.page_content for doc in docs)
return (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt # ChatPromptTemplate
| llm
| StrOutputParser()
)
def add_documents(self, documents: list[Document]) -> list[str]:
"""Add documents to the vectorstore"""
return self.vectorstore.add_documents(documents)
def search(self, query, k=None, filter_dict=None):
search_kwargs = {"k": k or self.config.default_k}
if filter_dict:
search_kwargs["filter"] = filter_dict
return self.vectorstore.similarity_search_with_score(query, **search_kwargs)
def ask(self, question: str) -> str:
"""Ask a question using RAG"""
return self.chain.invoke(question) # `self.chain` is never assigned on screen
def ask_with_sources(self, question: str) -> dict:
"""Ask a question and return sources"""
answer = self.ask(question)
return {
"answer": answer,
"sources": [
{"content": doc.page_content, "metadata": doc.metadata, "similarity": score}
for doc, score in docs_with_scores # undefined here — see note
],
}
Two of those methods cannot run as reconstructed, and you should fix them in your own copy rather than assume the frames were complete. ask() calls self.chain, which nothing on screen assigns — give the class a second lazy property that memoises _create_chain(), mirroring vectorstore. ask_with_sources() iterates docs_with_scores, a name that is not in scope — it must call self.search(question) first and build the answer from those same documents, otherwise the citations it returns are unrelated to the answer it returns. That second bug is the more dangerous one: a citation payload that does not correspond to the retrieved context is worse than no citations, because it looks like provenance and is not.
The config values, verified on screen at 03:47:40 and 03:48:05:
| Field | Value |
|---|---|
collection_name | "production_documents" |
embedding_model | "text-embedding-3-small" |
chat_model | "gpt-4o-mini" |
temperature | 0.0 |
default_k | 5 |
min_similarity | 0.5 |
use_jsonb | True |
Four things to take from this file:
Lazy initialisation is the load-bearing detail. vectorstore is a @property guarded by if self._vectorstore is None: 03:48:25. Constructing RAGService() therefore opens no socket and builds no OpenAI client — which is what lets you import the module in a unit test, instantiate it at FastAPI module scope, or hand it to a worker that may handle a job which never retrieves anything. Import time is not the same as first use, and only the second one should cost you a database connection.
The chain is the *same* LCEL chain from Part 1. {"context": retriever | format_docs, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser() is the exact shape in rag_pipeline.py (lines 110–113). Nothing about hosting touched it. That is the portability claim being cashed.
search() exposes metadata filtering deliberately — "some filtering for metadata to make our retrieved documents more relevant" 03:49:15 — and returns (Document, score) tuples rather than bare documents, so the caller can see how good the match was. Both choices are what make ask_with_sources possible at all.
min_similarity: float = 0.5 is declared and, on screen, never used. No code path reads it. Say that plainly rather than pretending it is a working threshold — and if you implement it yourself, remember Part 4's warning: similarity_search_with_score on PGVector returns a *distance*, not a similarity. With the default cosine strategy, lower is better. A threshold you calibrated against Chroma is not transferable, and a naive if score > 0.5: keep will retain precisely your worst matches. Re-derive it by printing scores on a corpus you know.
Step 8 — Run it and verify in the dashboard
Clear any rows left over from the smoke test first, so the count you are about to read means something. Then:
RAGService initializes → "Service is ready"
main() builds 3 sample Documents → metadata={"source": …, "topic": …}
service.add_documents(sample_docs)→ "✅ Added 3 documents"
service.search("How do I make pgvector faster?", k=2) → prints (doc, score) pairs
service.ask("What is pgvector and how to use it?") → prints the grounded answerRefresh the dashboard: langchain_pg_collection has one row named production_documents; langchain_pg_embedding has 3 records, each with document text, a vector, and the topic / source metadata preserved in cmetadata 03:50:17, 03:53:35. Row order is arbitrary — "the order doesn't really matter."
Step 9 — Give the table an ANN index
This step is not in the course, and it is the difference between a demo and a system. Start by confirming the two facts from Step 6's callout against your own database:
-- 1. Does the embedding column have a declared dimension?
SELECT format_type(atttypid, atttypmod) AS embedding_type
FROM pg_attribute
WHERE attrelid = 'langchain_pg_embedding'::regclass
AND attname = 'embedding';
-- 'vector' -> dimensionless: NO ANN index can be built on it
-- 'vector(1536)' -> good
-- 2. What indexes actually exist?
SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'langchain_pg_embedding';
-- expect langchain_pg_embedding_pkey and ix_cmetadata_gin — and nothing on `embedding`
If the type comes back as bare vector, you skipped embedding_length= and the column has no dimension. Building an index on it fails with pgvector's own error, verbatim: column does not have dimensions. Fix an existing table in place, then build the index:
-- Only needed if the column was created without a dimension.
ALTER TABLE langchain_pg_embedding
ALTER COLUMN embedding TYPE vector(1536);
-- HNSW index. The operator class MUST match the distance your queries use:
-- vector_cosine_ops → <=> (cosine distance — PGVector's DEFAULT strategy)
-- vector_l2_ops → <-> (Euclidean)
-- vector_ip_ops → <#> (inner product)
CREATE INDEX ON langchain_pg_embedding
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
ANALYZE langchain_pg_embedding;
-- Query-time effort. Session-scoped; pgvector's default is 40.
SET hnsw.ef_search = 100;
Use vector_cosine_ops unless you changed distance_strategy=: PGVector's default is DistanceStrategy.COSINE, so its queries emit <=>. An index built with the wrong operator class is simply never used, and nothing tells you — your latency stays exactly where it was.
Those numbers are not arbitrary. They are Part 8's preset table 03:16:04–03:17:04, and the pgvector code values the course prints for them 03:17:04–03:18:05:
| Regime | m | ef_search | Priority |
|---|---|---|---|
| Prototype | 16 | 40 | Speed |
| Production | 16 | 100 | Balanced |
| High accuracy | 32 | 200 | Accuracy |
Read that table against pgvector's own defaults — m = 16, ef_construction = 64, hnsw.ef_search = 40 — and it collapses into something you can actually remember: the "prototype" preset is just pgvector out of the box, and going to production means raising one session variable from 40 to 100. The division of labour is what makes this manageable: m and ef_construction are build-time and require a rebuild to change; ef_search is query-time and free to experiment with. If recall is short, raise ef_search first. Only pay for an index rebuild and the extra RAM of a higher m when ef_search alone cannot get you there.
pgvector also ships an IVFFlat index type, which the course never mentions. It builds much faster and uses far less memory than HNSW, but it has three sharp edges: it must be built after the table already holds data (it clusters the vectors it can see), its lists parameter has to be sized to the row count (rows / 1000 up to 1M rows, sqrt(rows) beyond), and its query-time ivfflat.probes defaults to 1, which gives terrible recall until you raise it (start around sqrt(lists)). Recall also decays as you insert past the point where it was trained. HNSW is slower and hungrier to build and is the right default for a corpus that keeps growing — which is every RAG corpus. Reach for IVFFlat only when index build time or RAM is the binding constraint.
If you would rather own the schema outright — which you should, once the system matters — the hand-written version is small. The course's earlier local pgvector lessons build something like it in the SQL Editor (referenced at 03:50:17, outside this chapter):
-- A hand-owned schema. You control the names, the dimension, the index and the constraints.
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE documents (
id bigserial PRIMARY KEY,
content text NOT NULL,
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
embedding vector(1536) NOT NULL, -- must match your embedding model, forever
created_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
-- Metadata filtering: a GIN index makes jsonb predicates cheap.
-- (LangChain's own table already has this one, as ix_cmetadata_gin.)
CREATE INDEX ON documents USING gin (metadata jsonb_path_ops);
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
The vector(1536) in that DDL is invariant 2 written into your schema as a constraint. Change the embedding model and the database itself will refuse the insert — which is exactly the loud failure you want, instead of the silent same-dimension-different-model failure from Part 4.
Supabase's dashboard also surfaces an Index Advisor button on the table view 03:53:35. The course never clicks it. It is worth a look on a table with real traffic, but it reasons about conventional Postgres indexes and is no substitute for choosing your own ANN parameters.
Step 10 — Turn on Row Level Security — both tables
Open the Table editor. The two fresh LangChain tables carry a red UNRESTRICTED badge and an "RLS disabled" button. Hover it:
"This table can be accessed by anyone via the Data API as RLS is disabled." 03:53:25
This is the checkbox from Step 1 coming home. The Data API is on, RLS is off, so anyone holding your publishable key can read every document and every vector in your store — your corpus, your customers' text, and everything the embeddings encode about it.
Fix, per table: click the badge → View policies → Enable RLS → confirm "Are you sure you want to enable Row Level Security on this table?" → Enable. Then do it again for the second table 03:54:27. Enabling RLS on langchain_pg_collection does nothing for langchain_pg_embedding. The badge disappears when both are done.
The SQL equivalent, which is what you should actually put in a migration so it is not a thing someone forgets:
-- Do this for BOTH LangChain tables, on every new deployment.
ALTER TABLE langchain_pg_collection ENABLE ROW LEVEL SECURITY;
ALTER TABLE langchain_pg_embedding ENABLE ROW LEVEL SECURITY;
"You should always enable RLS. That way your data is protected." 03:53:25
The operational trade-offs you just bought
The chapter's framing is "you don't have to worry about anything" 03:34:19. That is sales language, and even the source's own walkthrough contradicts it within fifteen minutes. Managed hosting removes host operations. It does not remove database decisions. Here is the honest list of what is now yours.
| You no longer own | You now own |
|---|---|
OS patching, pg_upgrade, disk provisioning | Schema design, the vector column's dimension, and index parameters (m, ef_construction, ef_search) |
| Backup cron, replication setup, failover wiring | Connection pooling mode — direct vs transaction vs session |
| Hardware capacity planning | The 500 MB / 8 GB storage cap and what counts against it |
| Physical security | RLS, per table, on every deployment |
| Uptime engineering | Egress (5 GB free) and the cost of returning document text on every query |
| — | Network latency between app and database, which is now a real number in your p95 |
| — | Vendor lock-in surface: how much of Supabase's platform (auth, Data API, Edge Functions) you adopt |
Connection pooling is the biggest genuine gap in the source. The Config dataclass carries the comment # Database - use pooler URL in production 03:47:40 — so the course knows it matters — and the file that would teach it, 02_connection_pooling.py, is explicitly skipped: "I'm skipping the connection pooling because it's something that you can look into" 03:46:09. It is never taught anywhere else. Fill that gap yourself, because it is the failure that takes a working RAG service down under load:
- Postgres connections are expensive and capped. A small managed instance may allow tens, not thousands. Every uvicorn worker, every Lambda invocation and every background task that constructs a
PGVectoropens one — andPGVectorbuilds a new SQLAlchemy engine, with its own pool, for every DSN string you hand it. Construct the store once per process, or pass a sharedEngineasconnection=instead of a string. - A long-lived service (VM, container, FastAPI behind uvicorn) should use the direct connection plus that application-side pool, sized to your worker count — not one connection per request.
- A serverless deployment must use the transaction pooler, because there is no process to hold a connection between invocations, and a thousand concurrent cold starts will otherwise exhaust the server's connection slots and start returning errors to users. Note the constraint that comes with it: transaction-mode pooling gives you no session-level state, so a bare
SET hnsw.ef_search = …will not survive to the next statement. UseSET LOCAL hnsw.ef_search = 100inside the transaction that runs the query, or set the value as a role/database default withALTER ROLE … SET. - Session pooler exists for one reason: you are on an IPv4-only network and cannot reach the direct host. It is a compatibility fallback, not a scaling strategy.
Latency changes character. A local Chroma query is a page-cache read. A Supabase query is a TCP round trip to another region, on shared CPU, plus the ANN search, plus returning the chunk text over the wire. Put the application in the same region as the database. Part 7's instrumentation is what makes this visible: if your retrieval p95 jumped after the migration, the first suspects are a missing ANN index, region mismatch, and connection setup per request.
Egress is a real budget line. 5 GB free. Every retrieval returns document text, not just vectors, and if you are retrieving k=5 chunks of ~1,000 characters per query, that is ~5 KB per request before overhead. A million requests is ~5 GB. It is not a wall you will hit in development, and it is one you should be able to compute before it surprises you.
Backups. Managed Postgres gives you automated backups on paid tiers, and free tiers typically do not give you point-in-time recovery. Your vectors are derived data — you can always re-embed from source documents — so the thing you must actually back up is the source corpus and the ingestion code, not the database.
Migrating an existing Chroma corpus
The source never covers this — it re-runs a demo from scratch — but you will need it, and it is short. Because vectors are derived data, there are only two honest options:
- Re-embed from source (recommended). Run your existing load → split → embed → store pipeline with the
PGVectorconstructor in place ofChroma. Cost: one full re-embed of the corpus (attext-embedding-3-small, $0.02 per 1M tokens — cheap enough that this is almost always the right answer). Benefit: you get to fix chunking at the same time, and you know exactly what is in the new store. - Copy vectors across. Pull
documents,embeddings,metadatasandidsout of Chroma and insert them withadd_embeddings(), which takes pre-computed vectors and skips the embedding call. Cheaper in dollars, more fragile: you must guarantee that the vectors were produced by the same model at the same dimension, and you are depending on a table layout LangChain owns and has already changed once.
Either way, run the same set of retrieval probes against both stores before and after and compare the top-k document IDs. A migration that silently changes what gets retrieved is a migration that silently changes every answer your system gives — and per invariant 4, nothing will throw.
What the source does not cover, stated plainly
Being clear about the edges of the material is more useful than papering over them:
- Connection pooling implementation — flagged as important, explicitly skipped 03:46:09, never taught.
- ANN index creation on the hosted instance — the course says LangChain "created some indexes automatically" and never inspects them. It does not create a vector index; Step 9 exists to fill that gap.
- The
embedding_lengthargument — never mentioned, and without it the column cannot be indexed at all. - Migration of an existing corpus — not covered anywhere.
- Backups, PITR, restore drills — not covered.
- RLS policies — only RLS enablement is shown. Writing an actual policy is out of scope.
- Multi-tenancy — not discussed; the collection abstraction invites a wrong answer here.
- Neon and RDS hands-on — named on a slide, never demonstrated. Everything in the walkthrough is Supabase-specific UI; only the DSN and the SQL transfer.
- Cold-start behaviour on scale-to-zero — never mentioned.
None of that is a criticism of the source — it says so itself, and the scoping is deliberate:
"Obviously, this is not a Supabase or pgvector course… This is a course about vector databases." 03:52:22
It is a list of the things you have to go and learn elsewhere before this stack carries traffic.
Checklist: taking a RAG system from a folder to a hosted database
Choose
- Estimate your vector count and put it on the scale ladder: <100K → local is still fine; 100K–10M → managed pgvector; 10M+ → consider self-hosting.
- Default to Supabase unless (a) your workload is idle-heavy and cold starts are acceptable → Neon, or (b) your org already lives in a hyperscaler → RDS / Cloud SQL / AlloyDB.
- Re-derive the cost on your numbers. Free 500 MB ≈ tens of thousands of 1536-d chunks.
- Confirm pgvector is available on the tier you are buying, and that your embedding dimension is ≤ 2,000 if you intend to index a
vectorcolumn.
Provision
- Create the organisation, then the project.
- Copy the database password at creation. It is shown once. (Recovery: Database → Settings → Reset database password → Generate → Reset.)
- Pick the region closest to your application servers; it is effectively permanent.
- Tick "Enable automatic RLS" at project creation, or write down that you will enable it by hand on both LangChain tables.
- Enable the
vectorextension (Database → Extensions, schemaextensions), even though Supabase pre-installs it andPGVectorwould issue theCREATE EXTENSIONitself.
Connect
- Connect → Direct tab. Pick direct connection for long-lived services, transaction pooler for serverless, session pooler only if you are stuck on IPv4.
- Put the DSN in
.envasSUPABASE_DATABASE_URL. Strip the[…]brackets from the password placeholder. Confirm port 5432. Confirm the project ref. - Rewrite the scheme to
postgresql+psycopg://before handing it toPGVector, or SQLAlchemy will reach for psycopg2 and fail. - Never commit
.env. - Keep the
SUPABASE_DATABASE_URL or DATABASE_URLfallback so the same code runs against local Postgres.
Wire the code
- Swap
Chroma(...)forPGVector(embeddings=…, collection_name=…, connection=…, embedding_length=1536, use_jsonb=True). Noteembeddings=, notembedding=. - Define
collection_nameonce, inConfig. Two files with two names create two collections. - Keep the embedding model identical to the one that built your local index (
text-embedding-3-small, 1536 dims). - Lazily initialise the vector store behind a
@property, and construct it once per process. - Make
ask_with_sourcescite the documents it actually answered from — one retrieval, reused. - Smoke-test: add → search → assert → delete. Keep the cleanup.
Harden
- Inspect the schema:
langchain_pg_collection(3 cols) andlangchain_pg_embedding(5 cols). - Check
format_type(atttypid, atttypmod)onembedding: barevectormeans no dimension →ALTER … TYPE vector(1536)before anything can be indexed. - List
pg_indexesfor the table. Expect a PK andix_cmetadata_gin, and nothing onembeddinguntil you build it. - Create the ANN index yourself with the matching operator class:
USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64), thenANALYZE. - Set
hnsw.ef_search = 100for production (default is 40); raise it further if you filter on metadata, and only then touchm. ENABLE ROW LEVEL SECURITYon both tables, in a migration, not by clicking.- Size the connection pool to your worker count; do not open a connection per request. Under a transaction pooler, use
SET LOCALfor session GUCs.
Verify
- Run the same retrieval probes against the old and new stores and diff the top-k document IDs.
- Re-measure retrieval p95 (Part 7's instrumentation). Investigate the index, then the region, then pooling, in that order if it regressed.
- Re-derive any similarity threshold against pgvector scores — they are cosine distances, so lower is better, and nothing transfers from Chroma.
- Confirm the storage, egress and connection headroom you have left, and write down the number that will trigger an upgrade.
Then go to Part 9 and put the embedding cache and the response cache in front of all of this, because the cheapest query against a hosted database is the one you never send.