🐘 Installing and Deploying PostgreSQL + pgvector in Docker

This article shows how to quickly deploy a PostgreSQL database with the pgvector extension in a Docker Compose environment, so your local or development setup can support vector retrieval and AI applications (LangChain, RAG, semantic search, and the like).

📦 1. Prepare the Environment

Make sure your system has:

• Docker
• Docker Compose
• A .env file with database environment variables, for example:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=appdb

🧱 2. Create the Project Structure

The recommended project layout:

dev-tools/
│
├── docker-compose.yml
├── .env
└── init.sql

⚙️ 3. Write the docker-compose.yml

Use the official pgvector/pgvector image (based on PostgreSQL 16/17, with the pgvector extension built in):

services:
  postgre:
    image: pgvector/pgvector:pg16
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s
    volumes:
      - ./postgre:/var/lib/postgresql/data/pgdata
      - ./init.sql:/docker-entrypoint-initdb.d/00_init.sql:ro
    env_file:
      - .env
    ports:
      - "5432:5432"
    environment:
      - PGDATA=/var/lib/postgresql/data/pgdata
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD?Variable not set}
      - POSTGRES_USER=${POSTGRES_USER?Variable not set}
      - POSTGRES_DB=${POSTGRES_DB?Variable not set}

🗃️ 4. Initialize the pgvector Extension

Create the init.sql file:

-- Automatically enable the pgvector extension when the database initializes
CREATE EXTENSION IF NOT EXISTS vector;

This file runs automatically when the container first starts and the database initializes.

🚀 5. Start the Database

# Create the persistence directory (if it doesn't exist)
mkdir -p ./postgre

# Start the database service
docker compose up -d postgre

Check container status:

docker compose ps

When the status shows healthy, the database is up and running.

🔍 6. Verify pgvector Is Enabled

Run the following to confirm the extension exists:

docker compose exec -T postgre bash -lc \
'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT extname, extversion FROM pg_extension WHERE extname='\''vector'\'';"'

Example output:

 extname | extversion
---------+------------
 vector  | 0.8.0
(1 row)

🧠 7. A Quick Functional Test

Create a simple table in the database and run a vector similarity search:

docker compose exec -T postgre bash -lc '
psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" <<EOF
CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));
INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');
SELECT id, embedding FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;
EOF
'

Example output:

 id | embedding
----+------------
  1 | [1,2,3]
  2 | [4,5,6]
(2 rows)

This confirms pgvector is enabled and can execute vector searches.

✅ 8. Summary

With these steps you have successfully deployed PostgreSQL + pgvector in Docker. From here you can plug it straight into LangChain, LlamaIndex, or your own RAG application.

📚 References

• pgvector official documentation
• Docker Hub: pgvector/pgvector
• Official PostgreSQL image