Deploy pgvector

Deploy and Host pgvector on Railway

pgvector is the open-source PostgreSQL extension that turns Postgres into a vector database. It adds vector, halfvec, sparsevec and bit column types plus HNSW and IVFFlat approximate-nearest-neighbour indexes, so embeddings live in the same tables and transactions as the rows they describe. With ~22.5k GitHub stars, a permissive PostgreSQL License and clients for 40+ languages, it is the default retrieval layer for RAG, semantic search and AI agents that need memory.

Self-host pgvector on Railway as one service on the official pgvector/pgvector:0.8.6-pg18 image — PostgreSQL 18.4 with pgvector 0.8.6 — plus a persistent volume and a TCP proxy. A boot script reads the container's real cgroup limits at every start and derives shared_buffers, effective_cache_size, maintenance_work_mem, work_mem and parallel worker counts from them, generates a TLS keypair, and pre-creates the vector and pg_stat_statements extensions. Services in the project connect privately at ${{RAILWAY_PRIVATE_DOMAIN}}:5432; laptops use the proxy with sslmode=require.

Getting Started with pgvector on Railway

pgvector has no web UI — you verify a database over a connection. When the deploy goes green, copy DATABASE_URL from the Variables tab for clients inside the project, or DATABASE_PUBLIC_URL for anything outside Railway. Both use the least-privilege app role; DATABASE_ADMIN_URL is there when you need the superuser. Connect and run this smoke test:

SELECT extversion FROM pg_extension WHERE extname = 'vector';  -- 0.8.6
CREATE TABLE docs (id bigserial PRIMARY KEY, body text, embedding vector(384));
CREATE INDEX ON docs USING hnsw (embedding vector_cosine_ops);
SELECT id, body, embedding <=> $1 AS distance
FROM docs ORDER BY embedding <=> $1 LIMIT 10;

EXPLAIN ANALYZE on the last statement should report Index Scan using docs_embedding_idx; a sequential scan means your operator class and distance operator disagree — vector_cosine_ops pairs with <=>, vector_l2_ops with <->. Always load rows before creating the index.

About Hosting pgvector

Vectors are just another Postgres column type, so you filter by tenant, join to metadata, enforce row-level security and rank by cosine distance in one query — and the embedding and its source row commit or roll back together, which no standalone vector store offers.

• vector/halfvec to 16,000 dimensions, sparsevec and bit for sparse and binary data
• HNSW and IVFFlat indexes, plus exact search with no index at all
• Distance operators for L2 <->, cosine <=>, inner product <#>, L1, Hamming and Jaccard
• halfvec roughly halves index size — 22 MB against 39 MB on identical data
• vector is enabled in template1, so every new database inherits it

The topology is one service, one volume, no pooler and no sidecars. The volume mounts at /var/lib/postgresql: PostgreSQL 18 moved PGDATA to /var/lib/postgresql/18/docker, so the old PG≤17 path /var/lib/postgresql/data silently gives an ephemeral database. PG18 also turns on data checksums.

Why Deploy pgvector on Railway

Railway removes the Postgres operations work without hiding the database.

• One-click deploy of a pinned, reproducible pgvector image
• Volume mounted at the correct PostgreSQL 18 path
• Private networking to your app services, no egress cost
• TCP proxy for psql, notebooks and loaders
• Vertical scaling by slider — tuning re-derives at next boot
• Usage-based pricing, no vector database subscription

Common Use Cases for pgvector

• RAG and chatbot retrieval — store chunks with embeddings, fetch top-k neighbours filtered by tenant or recency in one query.
• Semantic and hybrid search — combine <=> ranking with Postgres full-text search for dense plus lexical results.
• Recommendations and deduplication — surface similar products or tickets and catch near-duplicates on write.
• AI agent memory — long-term memory beside structured state, updated in one transaction.

Dependencies for pgvector

• pgvector/pgvector:0.8.6-pg18 — PostgreSQL 18.4 with pgvector 0.8.6 built in. Pinning the tag is a correctness decision: pgvector 0.8.3 and 0.8.4 fixed HNSW index corruption during vacuuming.
• A Railway volume — without one at /var/lib/postgresql, every redeploy starts an empty cluster.
• A TCP proxy — Postgres speaks its own wire protocol and needs a TCP endpoint.

Environment Variables Reference

The app role owns the public schema and can run migrations and install trusted extensions, but cannot create roles or databases, read pg_authid, or COPY ... FROM PROGRAM. BOOT_SH holds the tuning and TLS script.

Deployment Dependencies

• github.com/pgvector/pgvector
• hub.docker.com/r/pgvector/pgvector
• postgresql.org/docs/18

Hardware Requirements for Self-Hosting pgvector

Index builds drive sizing, not queries. Postgres reads neither cgroup memory limits nor CPU quota, so stock defaults leave shared_buffers at 128 MB on a container of any size; this template recomputes it at every boot. A 1,536-dimension vector costs about 6 KB per row and an HNSW index runs 1.5–2× the raw data, so give maintenance_work_mem room to hold the graph — a build that spills to disk is an order of magnitude slower.

Self-Hosting pgvector With Docker

The same image runs anywhere. A minimal docker run:

docker run -d --name pgvector \
  -e POSTGRES_PASSWORD=changeme -e POSTGRES_DB=vectors \
  -p 5432:5432 -v pgvector_data:/var/lib/postgresql \
  --shm-size=1g pgvector/pgvector:0.8.6-pg18

Mount /var/lib/postgresql, not /var/lib/postgresql/data — the PostgreSQL 18 trap. To build from source on Postgres 13+ with development headers:

git clone --branch v0.8.6 https://github.com/pgvector/pgvector.git
cd pgvector && make && sudo make install
psql -d yourdb -c "CREATE EXTENSION vector;"

In production use CREATE INDEX CONCURRENTLY so writes are not blocked, and tune recall with SET hnsw.ef_search = 100 — HNSW is approximate, and ef_search trades speed for recall. halfvec helps when index size is the constraint.

How Much Does pgvector Cost to Self-Host?

pgvector is free and open source under the PostgreSQL License — no seats, no vector quotas, no metering. On Railway you pay only for the compute, memory and volume storage used, so a development instance costs a few dollars a month. Managed alternatives price the same workload differently: Pinecone's paid tiers start at a $50/month minimum plus about $0.33/GB/month of storage, and Qdrant or Weaviate mean a second cluster to run. Below roughly ten million vectors, one Postgres usually wins on cost and operations.

pgvector FAQ

What is pgvector?

An open-source PostgreSQL extension that adds vector types and approximate-nearest-neighbour indexes to Postgres, so you run similarity search in SQL rather than operating a separate vector database.

What does this Railway template deploy?

One PostgreSQL 18.4 service on pgvector/pgvector:0.8.6-pg18 with the extension pre-enabled, a persistent volume, TLS, a TCP proxy, container-aware memory tuning, and both a superuser and a least-privilege app role.

Why does this template need a volume, and where must it mount?

Railway containers are ephemeral and Postgres writes to disk. On PostgreSQL 18 the volume must mount at /var/lib/postgresql, because PGDATA moved to /var/lib/postgresql/18/docker; the older .../data path loses everything on redeploy.

Does this pgvector template include automatic backups?

No — there is no WAL archiving or scheduled dump here. Add a scheduled pg_dump before you store anything irreplaceable.

Should I use HNSW or IVFFlat for my pgvector index?

HNSW gives better query performance and needs no data present at creation, at the cost of slower builds and more memory. IVFFlat builds faster but wants representative data first and degrades as the table grows. Start with HNSW.