docker run –name pgvector-db -e POSTGRES_PASSWORD=secret -p 5432:5432 -d pgvector\/pgvector:pg17<\/strong><\/p>\n\n\n\nThis pulls a PostgreSQL 17 image with pgvector v0.8.3 already compiled and ready. No build step required.<\/p>\n\n\n\n
Install the Python packages you need:<\/p>\n\n\n\n
pip install psycopg pgvector openai<\/strong><\/p>\n\n\n\nEnabling pgvector in Your Database<\/strong><\/h2>\n\n\n\nConnect to your database and run:<\/p>\n\n\n\n
Sql<\/strong><\/p>\n\n\n\nCREATE EXTENSION IF NOT EXISTS vector;<\/code><\/pre>\n\n\n\nThat is the entire installation step at the database level. From this point, you can use the vector<\/strong> type in any table definition.<\/p>\n\n\n\nCreating a Table with a Vector Column<\/strong><\/h2>\n\n\n\nSql<\/strong><\/p>\n\n\n\nCREATE TABLE documents (\n id BIGSERIAL PRIMARY KEY,\n content TEXT NOT NULL,\n embedding vector(1536)\n);\n<\/code><\/pre>\n\n\n\nThe number inside vector(1536)<\/strong> must match the dimensions of your embedding model. For OpenAI’s text-embedding-3-small<\/strong>, that is 1536. For sentence-transformers MiniLM, it is 384. Choose your embedding model before writing any schema, because the vector dimension is baked into the column definition and changing it later means re-embedding your entire dataset.<\/p>\n\n\n\nInserting Vectors with Python<\/strong><\/h2>\n\n\n\nPython<\/strong><\/p>\n\n\n\nimport psycopg\nfrom pgvector.psycopg import register_vector\nfrom openai import OpenAI\n\nopenai_client = OpenAI()\nconn = psycopg.connect(\"postgresql:\/\/postgres:secret@localhost:5432\/postgres\")\nregister_vector(conn)\n\ndef get_embedding(text):\n return openai_client.embeddings.create(\n model=\"text-embedding-3-small\", input=text\n ).data[0].embedding\n\nwith conn.cursor() as cur:\n content = \"pgvector adds vector search to PostgreSQL\"\n embedding = get_embedding(content)\n cur.execute(\n \"INSERT INTO documents (content, embedding) VALUES (%s, %s)\",\n (content, embedding)\n )\nconn.commit()\n<\/code><\/pre>\n\n\n\nCalling register_vector(conn)<\/strong> tells psycopg how to handle the pgvector type automatically. Without it, you get type errors on insert.<\/p>\n\n\n\nRunning a Similarity Search<\/strong><\/h2>\n\n\n\nThe <=><\/strong> operator calculates cosine distance. Ordering by it ascending returns the most similar documents first.<\/p>\n\n\n\nSql<\/strong><\/p>\n\n\n\nSELECT content, 1 - (embedding <=> %s) AS similarity\nFROM documents\nORDER BY embedding <=> %s\nLIMIT 5;\n<\/code><\/pre>\n\n\n\nThe <=><\/strong> operator returns cosine distance where 0 is identical and 2 is opposite, so 1 – distance<\/strong> gives you cosine similarity as a score between 0 and 1.<\/p>\n\n\n\nPass your query embedding as the parameter using the same Python setup as above.<\/p>\n\n\n\n
Adding an HNSW Index for Performance<\/strong><\/h2>\n\n\n\nWithout an index, every similarity query performs a full table scan comparing the query vector against every row. That is fine at ten thousand rows. At hundreds of thousands, it gets slow.<\/p>\n\n\n\n
HNSW builds a multi-layer graph where each vector is connected to its neighbors, giving much better query performance than IVFFlat in terms of the speed-recall tradeoff.<\/p>\n\n\n\n
Create it with:<\/p>\n\n\n\n
Sql<\/strong><\/p>\n\n\n\nCREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);<\/code><\/pre>\n\n\n\nEnsure the operator class in your index matches the operator in your queries, because a mismatch produces no error, only a silent regression to full-table scans. If you query with <=><\/strong>, index with vector_cosine_ops<\/strong>. If you query with <-><\/strong>, use vector_l2_ops<\/strong>.<\/p>\n\n\n\nWhen to Use pgvector vs a Dedicated Vector Database<\/strong><\/h2>\n\n\n\nScenario<\/strong><\/td>Best Choice<\/strong><\/td><\/tr>Already using PostgreSQL, under 10M vectors<\/td> pgvector<\/td><\/tr> Need auto-vectorization at import time<\/td> Weaviate<\/td><\/tr> Need sub-millisecond latency at 100M+ vectors<\/td> Qdrant<\/td><\/tr> Need hybrid search without extra setup<\/td> pgvector or Weaviate<\/td><\/tr> Multi-tenant SaaS with strict data isolation<\/td> pgvector (one schema per tenant)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
\ud83d\udca1 Did You Know?<\/h3>\n \n Each vector in pgvector takes 4 bytes per dimension plus 8 bytes of overhead. A 1536-dimension embedding therefore uses about 6.1 KB per row. A table of one million documents with 1536-dimension embeddings uses roughly 6 GB of storage, entirely within standard PostgreSQL capacity.<\/li>\n <\/ul>\n<\/div>\n\n\n\nCommon Mistakes to Avoid<\/strong><\/h2>\n\n\n\n\nForgetting to call register_vector() in Python.<\/strong> Without this call, psycopg does not know how to serialise Python lists into the pgvector type and raises a type error on every insert. Call it once immediately after opening your connection.<\/li>\n\n\n\nIndexing before you have enough data.<\/strong> The IVFFlat index requires a training step and was likely created with too little data for the number of lists. Drop the index until the table has more data. For HNSW, you can create the index on an empty table, but it performs best once there are at least a few thousand rows.<\/li>\n\n\n\nMismatching distance operators and index operator classes.<\/strong> Using <=><\/strong> in queries but vector_l2_ops<\/strong> in the index causes PostgreSQL to silently fall back to a full table scan. Always match the operator class in your CREATE INDEX<\/strong> to the distance operator in your queries.<\/li>\n<\/ul>\n\n\n\nConclusion<\/strong><\/h2>\n\n\n\nThis pgvector tutorial covered the complete beginner path: running PostgreSQL with pgvector in Docker, enabling the extension, creating a table with a vector column, inserting embeddings from Python, running cosine similarity search, and adding an HNSW index for production performance. If you already use PostgreSQL, pgvector is the fastest, lowest-overhead way to add semantic search to your application in 2026.<\/p>\n\n\n\n
FAQs<\/strong><\/h2>\n\n\n\n
\n
\n
1. What is pgvector?<\/strong><\/h3>\n\n\n
pgvector is an open-source PostgreSQL extension that adds a vector data type and similarity search operators, enabling semantic search and RAG directly inside your existing PostgreSQL database.<\/p>\n\n<\/div>\n<\/div>\n
\n
2. Is pgvector free?<\/strong>\u00a0<\/h3>\n\n\n
Yes. pgvector is open-source under the PostgreSQL License. It is also available pre-installed on managed services including AWS RDS, Azure Database for PostgreSQL, and Supabase.<\/p>\n\n<\/div>\n<\/div>\n
\n
3. What distance operators does pgvector support?<\/strong>\u00a0<\/h3>\n\n\n
pgvector supports cosine distance (<=><\/strong>), L2 Euclidean distance (<-><\/strong>), and negative inner product (<#><\/strong>). Cosine distance is the most common choice for text embeddings generated by LLMs.<\/p>\n\n<\/div>\n<\/div>\n\n
4. What is the difference between HNSW and IVFFlat in pgvector?<\/strong><\/h3>\n\n\n
HNSW builds a graph-based index with better query performance and no training step but uses more memory. IVFFlat partitions vectors into clusters and requires training data before the index is created. HNSW is the recommended default for most use cases.<\/p>\n\n<\/div>\n<\/div>\n
\n
5. Should I use pgvector or a dedicated vector database like Qdrant?<\/strong>\u00a0<\/h3>\n\n\n
If you already run PostgreSQL and have fewer than 10 million vectors, pgvector gives you semantic search with no new infrastructure. For very large datasets or use cases requiring sub-millisecond latency at massive scale, a dedicated vector database like Qdrant or Weaviate may perform better.<\/p>\n\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
Most vector database tutorials tell you to spin up an entirely new database just for embeddings. If you already run PostgreSQL in production, there is a much simpler path. This pgvector tutorial shows you how to add vector similarity search directly to the database you already have, with no new infrastructure, no new connection string, […]<\/p>\n","protected":false},"author":65,"featured_media":121110,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[325,959],"tags":[],"views":"32","authorinfo":{"name":"Jebasta","url":"https:\/\/www.guvi.in\/blog\/author\/jebasta\/"},"thumbnailURL":"https:\/\/www.guvi.in\/blog\/wp-content\/uploads\/2026\/06\/pgvector-300x116.webp","_links":{"self":[{"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/posts\/119462"}],"collection":[{"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/users\/65"}],"replies":[{"embeddable":true,"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/comments?post=119462"}],"version-history":[{"count":3,"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/posts\/119462\/revisions"}],"predecessor-version":[{"id":121115,"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/posts\/119462\/revisions\/121115"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/media\/121110"}],"wp:attachment":[{"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/media?parent=119462"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/categories?post=119462"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.guvi.in\/blog\/wp-json\/wp\/v2\/tags?post=119462"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}