From 47466a6c61afb2f01fd08487cd4ddec0b2c28469 Mon Sep 17 00:00:00 2001 From: kasun Date: Mon, 29 Jun 2026 22:27:32 +0200 Subject: [PATCH] added pgvector implementation and updated doc --- backend/build.gradle.kts | 3 + backend/src/main/resources/application.yaml | 6 + .../02-Spring-Boot-and-database-setup.md | 135 ++++++++++++++---- 3 files changed, 117 insertions(+), 27 deletions(-) diff --git a/backend/build.gradle.kts b/backend/build.gradle.kts index b94c328..7fd5dfb 100644 --- a/backend/build.gradle.kts +++ b/backend/build.gradle.kts @@ -48,6 +48,9 @@ dependencies { implementation("org.springframework.boot:spring-boot-starter-webmvc") implementation("org.springframework.ai:spring-ai-starter-model-openai") implementation("org.postgresql:postgresql:$postgresqlVersion") + implementation("org.springframework.ai:spring-ai-starter-vector-store-pgvector") + + compileOnly("org.projectlombok:lombok") diff --git a/backend/src/main/resources/application.yaml b/backend/src/main/resources/application.yaml index 398cf02..5053f2a 100644 --- a/backend/src/main/resources/application.yaml +++ b/backend/src/main/resources/application.yaml @@ -21,6 +21,12 @@ spring: api-key: ${OPENAI_KEY} chat: model: gpt-4o-mini + vectorstore: + pgvector: + dimensions: 1536 + distance-type: COSINE_DISTANCE + index-type: HNSW + initialize-schema: true session: store-type: jdbc jdbc: diff --git a/docs/02-Preparation/02-Spring-Boot-and-database-setup.md b/docs/02-Preparation/02-Spring-Boot-and-database-setup.md index 3b00f95..0fa8894 100644 --- a/docs/02-Preparation/02-Spring-Boot-and-database-setup.md +++ b/docs/02-Preparation/02-Spring-Boot-and-database-setup.md @@ -165,43 +165,124 @@ services: restart: unless-stopped ``` -Note that I'm using my own locally hosted PostgreSQL instances for the main and test database. Just add databases via SQL or PgAdmin and install the pgvector extension to each database manually. There is an offical ready-made pgvector docker image but if you already host a PostGreSQL database you need to add the extension yourself. +Note that I'm using my own locally hosted PostgreSQL instances for the main and test database. Just add databases via SQL or PgAdmin and install the pgvector extension to each database manually. There is an official ready-made pgvector docker image but if you already host a PostgreSQL database you need to add the extension yourself. -Check the name of your PostGreSQL container: -``` -docker ps +## Installing pgvector on a self-hosted PostgreSQL container + +pgvector is a PostgreSQL extension that adds a `vector` data type. It does not create a new database — it adds a `vector_store` table to your existing database. The shared library (`vector.so`) must be installed on the PostgreSQL server itself. + +**Do not install it manually inside a running container.** Manual installations do not survive container recreation (e.g. after a `docker compose up --force-recreate` or image update). Instead, bake it into a custom Docker image. + +### Step 1: Create a custom Dockerfile for PostgreSQL + +Create a `Dockerfile.postgres` next to your `docker-compose.yaml`: + +```dockerfile +FROM postgres:18.4 + +RUN apt-get update && apt-get install -y --no-install-recommends \ + ca-certificates git build-essential postgresql-server-dev-18 \ + && git clone --branch v0.8.3 https://github.com/pgvector/pgvector.git \ + && cd pgvector && make && make install \ + && cd .. && rm -rf pgvector \ + && apt-get purge -y ca-certificates git build-essential postgresql-server-dev-18 \ + && apt-get autoremove -y \ + && rm -rf /var/lib/apt/lists/* ``` -Enter your container via bash: +- `FROM postgres:18.4` — this is still the standard postgres image, not the pgvector image +- `ca-certificates` — required for git to verify GitHub's SSL certificate during build +- `postgresql-server-dev-18` — provides the PostgreSQL header files needed to compile pgvector -``` -docker exec -it 876fb382969f bash -``` -Before working on your database backup your databases: -``` -su - postgres -c "pg_dumpall > /tmp/backup200526.sql" +### Step 2: Update docker-compose.yaml to use the custom image -#exit the container and copy the backup file to local file system -docker cp 876fb382969f:/tmp/backup200526.sql . + +```yaml +services: + db: + container_name: postgres + labels: + - "com.centurylinklabs.watchtower.enable=false" + build: + context: . + dockerfile: Dockerfile.postgres + network: host + restart: always + environment: + POSTGRES_USER: ${DB_USER} + POSTGRES_PASSWORD: ${DB_PASSWORD} + POSTGRES_DB: ${DB_NAME} + networks: + - pg_network + volumes: + - /home/pi/docker/postgresql:/var/lib/postgresql + ports: + - "5432:5432" + +networks: + pg_network: + external: true ``` -Install dependencies, build and install pgvector: -apt-get update -apt-get install -y build-essential git postgresql-server-dev-all -``` -git clone https://github.com/pgvector/pgvector.git -cd pgvector -make -make install -docker restart 876fb382969f -``` -Enter PostGreSQL container and create pgvector extension for each databse: -``` -docker exec -it psql -h localhost -U -d +### Step 3: Build the image and recreate the container -CREATE EXTENSION vector; +Before recreating, back up your databases: + +```bash +docker exec -it bash +su - postgres -c "pg_dumpall > /tmp/backup.sql" +exit +docker cp :/tmp/backup.sql . ``` +Build the image. Use `--network=host` to ensure the build container can reach GitHub: + +```bash +docker build --network=host -t postgres-pgvector -f Dockerfile.postgres . +``` + +Recreate the container + +```bash +docker compose up -d --force-recreate +``` + +### Step 4: Enable the extensions in each database + +Run this once per database that needs pgvector: + +```bash +docker exec -it psql -U -d +``` + +```sql +CREATE EXTENSION IF NOT EXISTS vector; +CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; +``` + +`uuid-ossp` is also required — Spring AI's `vector_store` table uses `uuid_generate_v4()` for its primary key. + +### Step 5: Add pgvector config to application.yaml + +Spring AI's pgvector auto-configuration requires these properties: + +```yaml +spring: + ai: + vectorstore: + pgvector: + dimensions: 1536 # must match your embedding model output size + distance-type: COSINE_DISTANCE + index-type: HNSW + initialize-schema: true # auto-creates the vector_store table on startup +``` + +`dimensions` depends on the embedding model: +- `text-embedding-ada-002` / `text-embedding-3-small` → 1536 +- `text-embedding-3-large` → 3072 + +`initialize-schema: true` means Spring AI will create the `vector_store` table automatically on first startup — no manual SQL needed. + # Appendix: Additional config for developing in Code-Server When using the code-server container there are additional config steps to mind: