Table of Contents

🐘 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:

1
2
3


POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=appdb

🧱 2. Create the Project Structure
#

The recommended project layout:

1
2
3
4
5


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):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


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:

1
2


-- 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
#

1
2
3
4
5


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

# Start the database service
docker compose up -d postgre

Check container status:

1

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:

1
2


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:

1
2
3
4


 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:

1
2
3
4
5
6
7


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:

1
2
3
4
5


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

This confirms pgvector is enabled and can execute vector searches.

✅ 8. Summary
#

Item	Value
Image	`pgvector/pgvector:pg16`
Default port	`5432`
Data persistence directory	`./postgre`
Initialization script	`init.sql`
Extension	`pgvector`

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
#

Author

ByF (BaiFan)

ByF，即 BaiFan（白帆）。系统后端工程师，专注 AI 底层原理与智能体架构。主站 baifan.site。

🐘 Installing and Deploying PostgreSQL + pgvector in Docker #

📦 1. Prepare the Environment #

🧱 2. Create the Project Structure #

⚙️ 3. Write the docker-compose.yml #

🗃️ 4. Initialize the pgvector Extension #

🚀 5. Start the Database #

🔍 6. Verify pgvector Is Enabled #

🧠 7. A Quick Functional Test #

✅ 8. Summary #

📚 References #