AI 도슨트의 RAG 파이프라인 구축을 위한 첫걸음으로, 기존 MySQL 환경을 벡터 검색에 최적화된 PostgreSQL(pgvector)로 마이그레이션하고 기존 애플리케이션과의 완벽한 연동을 검증하는 과정입니다.
Table of Content
1. 마이그레이션 배경 및 목표 (Background & Objective)
왜 PostgreSQL과 pgvector인가?
•
현재 가상 전시관 서비스는 관계형 데이터베이스인 MySQL을 기반으로 운영되고 있다.
•
하지만 향후 도입할 RAG 시스템은 문서를 임베딩한 고차원 배열인 '벡터(Vector)' 데이터를 저장하고, 벡터 간의 '코사인 유사도'를 밀리초 단위로 계산해 낼 수 있는 특수한 기능이 필요하다.
•
기존 MySQL 환경에서는 이러한 고속 벡터 연산이 매우 비효율적이거나 지원되지 않으므로, Spring AI 생태계에서 가장 널리 쓰이고 호환성이 뛰어난 PostgreSQL과 그 확장 프로그램인 pgvector로 데이터베이스를 전면 마이그레이션하기로 결정했다.
해당 세션의 목표
•
OS 환경에 구애받지 않는 Docker 기반의 PostgreSQL 및 pgvector 환경 구축
•
기존 MySQL에 적재된 전시관(Exhibition) 및 작품(Production) 데이터의 손실 없는 이전
•
Spring Boot 백엔드와 새로운 DB의 JPA 연동 및 기존 API 정상 동작 검증
2. 왜 Docker로 환경을 구축해야 하는가? (Why Docker?)
•
pgvector는 PostgreSQL 내장 기능이 아닌 C 언어 기반의 확장 플러그인임.
Windows 환경의 C++ 의존성 문제 해결
•
Mac/Linux: 패키지 매니저(brew, apt)로 이미 컴파일된 완성본을 쉽게 설치 가능함.
•
Windows: 로컬 환경에 설치하려면 Visual Studio C++ 빌드 툴을 설치하고 소스 코드를 직접 컴파일(빌드)해야 함.
◦
이 과정에서 수많은 환경 변수 에러와 버전 충돌이 발생할 확률이 매우 높음.
◦
강의 및 다수의 개발자가 참여하는 프로젝트 환경에서는 "내 컴퓨터에서는 되는데 네 컴퓨터에서는 안 되는" 파편화 문제가 발생함.
◦
따라서, 운영체제(OS) 상관없이 pgvector 가 이미 완벽하게 세팅된 공식 Docker 컨테이너를 띄우는 것이 가장 안전하고 표준적인 실무 방식임.
3. Docker 기반 환경 구축 및 실행 (Environment Setup)
•
도커 이미지를 생성 또는 Pull 받고 컨테이너로 실행 시키는 방법은 GUI 환경인 Docker Desktop을 활용하는 방법 또는 CLI 터미널 명령어를 사용하는 방법 두가지 모두 사용 할 수 있다.
•
아래 내용에서는 편의상 Windows 환경 먼저 설명한 후, MacOS의 Unix 환경의 Homebrew를 통한 환경 구축 이후에 EC2와 같은 ubuntu 환경에서는 Docker Compose를 사용한 방법 CLI 명령어로 사용해야 하는 사례 세 가지 모두 설명하고자 한다.
◦
로컬 개발 PC인 경우 아래 3.1, 3.2장 참고
▪
▪
◦
3.1 [Windows] Docker Desktop GUI를 활용한 인프라 세팅
3.1.1 Docker Desktop 설치
Docker Desktop 설치하기
•
OS(Windows/Mac)에 맞는 Docker Desktop을 공식 홈페이지에서 다운로드 후 설치 및 실행함.
•
설치 후 실행 시 다음과 같은 화면이 나타나며 , Docker 회원 가입 및 로그인으로 Docker Hub Cloud도 사용 할 수도 있으니 미리 회원가입과 로그인 해두도록 한다.(public 사용 무료, private 저장소 환경은 유료)
3.1.2 GUI 이미지 검색 및 다운로드 (Pull)
Docker Cloud에 public 오픈소스로 공개되어 있는 Postgres+pgvector이미지 다운로드
•
Docker Desktop에서 상단 검색 탭 → pgvector/pgvector 검색 → Tag에서 pg16-trixie 선택 → Pull 을 통해 이미지 불러오기
•
Docker Desktop에서 좌측 메뉴 탭의 Images → Pull 받아진 pgvector 이미지 확인
3.1.3 GUI 컨테이너 설정 및 실행 (Run)
Docker Cloud에 public 오픈소스로 공개되어 있는 Postgres+pgvector이미지 다운로드
•
다운로드가 완료되면 [Run] 버튼을 클릭. 바로 실행하지 말고,
•
"Optional settings" (추가 설정)를 펼쳐서 다음 항목들을 필수로 기입.
◦
Container name: vexhibition-db
◦
Ports: 5432
◦
Environment variables (환경 변수): + 버튼을 눌러 3개의 변수를 추가.
▪
POSTGRES_USER: root
▪
POSTGRES_PASSWORD: 1234
▪
POSTGRES_DB: vexhibition
•
위 설정 후 Run 클릭 시 해당 Image → Container 화 되어 실행되며 아래와 같은 화면이 나타남
◦
이 부분은 VMWare인 Docker 가상 환경이 패키지화 되어있는 Image를 Container라는 공간에서 실행 시키고 있는 상태로 VMWare 내부 Port를 OS가 인식 할 수 있도록 포트포워딩하여 실행됨
3.1.4 데이터베이스 환경 구축 상태 확인
3.1.4.A Docker 컨테이너 내부의 터미널로 진입하여 PostgreSQL 접속하기
Docker Desktop 프로그램 내에서 접근
•
좌측 Containers 탭에서 실행중인 현재 데이터베이스를 선택하거나, 더보기의 View details로 실행중인 컨테이너 아래 사진으로 넘어갈 수 있다. (또는 Open in terminal로 바로 접근도 가능)
•
해당 컨테이너의 상세 정보를 확인 할 수 있는 부분이다. 로그, 상태 등을 기본적으로 확인 할 수 있다.
•
우리는 여기에서 현재 데이터베이스가 실행중 이라는 것을 보다 직접적으로 확인하기 위해서 접근하려고 한다.
•
Exec 탭을 들어가면 # .. 상태로 빈 상태의 터미널이 실행된다. 이 부분이 Docker가 만든 가상 환경 내부 터미널로 접근한 상태이다.
◦
설치된 PostgreSQL 데이터베이스의 버전을 확인해본다. (MySQL에서의 mysql --version)
psql --version
Shell
복사
◦
데이터베이스 콘솔내부 접근. (MySQL에서의 mysql -u root -p)
psql -U root -d vexhibition
Shell
복사
◦
psql 콘솔에 들어간 상태에서 기본적인 명령어 사용
▪
이를 통해서 정상 동작 하는지 직접 더블체크 하기 위함이다.
▪
데이터베이스 목록 조회(MySQL에서의 show databases;)
\l
Shell
복사
▪
데이터베이스 내 테이블 조회(MySQL에서의 show tables;)
\dt
Shell
복사
▪
psql 콘솔 종료, 외부 터미널로 탈출(MySQL에서의 quit;)
\q
Shell
복사
3.1.4.B 개발 컴퓨터 OS의 터미널(CMD/PowerShell/Mac zshell 등)에서 Docker 환경 내 → PostgreSQL 접속하기
OS와 직접 연결된 터미널과 Docker내부의 터미널은 격리된 다른 공간임을 인식해야 한다.
•
Docker는 기본적으로 OS 위에 Docker Engine이라는 가상 OS 레이어에서 각 Container라는 공간에 Image를 독립적으로 실행시키는 가상화 기술이다.
•
위 말로는 어려워 보일 수 있어, 간단한 비유로는 한 번 쯤 윈도우에서 모바일 게임을 즐기기 위한 가상 앱 플레이어를 사용해 본 경험이 있을 것이다.
◦
예로 블루스택(BlueStack)이나 녹스(Nox) 앱 플레이어 같은 것. 사실상 윈도우 내에 안드로이드 폰 환경을 가상으로 만든 상황.
◦
Docker는 상황과 유사한 다른 용도의 프로그램으로 생각하면 된다.
◦
하지만 안드로이드의 App 단위는 Docker에서의 Container라고 보면 되고 그 안에 프로그램 내용들이 Docker의 Image 단위인데 실행 만을 위해 경량화 되어 있다로 처음엔 이해하는것이 좋다.
외부 터미널에서 docker exec 명령어를 사용해 실행 중인 컨테이너에 직접 명령
•
아래 예시는 Windows 환경의 기본 명령 프롬프트(cmd) 터미널을 사용한 사례이다.
•
Windows에서 cmd.exe를 통해 터미널을 열고 다음 명령어로 Docker내부의 psql에 접근 할 수 있다.
docker exec -it vexhibition-db psql -U root -d vexhibition
Shell
복사
•
3.2 [MacOS] 터미널(CLI) 환경에서 인프라 세팅 (Homebrew 활용)
Mac 환경에서 터미널 기반으로 Docker 세팅하기
•
Mac 사용자도 Windows 사용자와 마찬가지로 Docker 홈페이지를 통해서 Docker Desktop을 설치하여 간편히 Docker 환경을 설치 할 수도 있다.
•
다만, GUI 대신 Mac 사용자 중 터미널 환경이 더 익숙한 개발자를 위한 가이드이다.
◦
Mac은 Unix기반의 OS로 대부분의 명령어가 Unix와 비슷하다.
◦
이에 따라 Linux기반의 Ubuntu OS의 CLI 명령어와도 유사한 점이 있다.(POSIX 표준 규격)
•
MacOS와 Ubuntu의 핵심적인 차이는 MacOS에서는 패키지 매니저인 Homebrew를 통해서 다양한 개발 프로그램 설치하는 것이 관례적으로 활용되고 있다.
3.2.1 Homebrew 설치
Mac의 패키지 매니저 Homebrew 설치
•
https://brew.sh/ 홈페이지에서 아래 명령어를 확인 할 수 있다.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Shell
복사
•
MacOS의 터미널을 열면 zsh(zshell) 또는 사용자 설정에 따라 iTerm2 등이 설치 되어 있을 수도 있다.
◦
본인의 주로 사용하는 터미널이 무엇인지 종류를 이해하고 있어야 한다.(환경변수 설정과 연관되어 있기 때문)
◦
본 예시는 zsh를 기반으로 작성하고 있으며, 환경변수 설정 파일은 .zshrc 파일이다.
•
터미널을 열고, 위 명령어를 붙여넣고 실행하면 Homebrew가 설치된다.
◦
중간에 확인용 엔터를 한번 쳐주자.
•
명렁어로 설치 했기 때문에 설치 상태를 확인하기 위해서 아래 명령어로 버전 정보를 확인.
brew --version
Shell
복사
◦
Homebrew 는 brew라는 키워드로 CLI 명령어를 사용하게 된다.
3.2.2 Homebrew를 통한 Docker 설치
패키지 매니저인 brew 명령어로 Docker 설치
•
이제 MacOS 터미널에서 brew 명령어로 다양한 프로그램을 설치할 준비가 되어있다.
동일한 설치 환경을 보여주기 위해서 기존 설치되어 있던 Docker를 제거하고 진행했다. 혹시나 (기존 설치를 제거하고자 하는 경우 토글 열어보기)
•
아래 명령어로 Docker를 설치한다.
brew install --cask docker
Shell
복사
◦
다음과 같이 CLI 환경에서 설치 파일이 다운로드 되며, Mac용 Docker Desktop 도 설치된다.
◦
설치 완료 시 아래와 같이 docker-desktop was successfully installed! 라는 로그가 나타나며,
◦
docker --version 명령어를 통해서 설치 상태를 확인
◦
맥의 탐색기인 finder의 응용프로그램 폴더에 실제 Docker Desktop이 설치된 것도 확인
•
Docker.app을 실행해보면 Docker Desktop(GUI)도 실행된다.
3.2.3 CLI 이미지 다운로드 (Pull)
원하는 버전의 이미지 Docker Hub에서 Pull(다운로드) 하기
•
Docker Compose는 명령어들의 집합으로 대체 할 수 있지만, 아직 여기에서는 MacOS에서 CLI 명령어 만으로 GUI에서의 실행을 대체해보고자 한다.
◦
zsh 터미널에서 Docker Hub의 PostgreSQL 이미지 풀 명령어
docker pull pgvector/pgvector:pg16-trixie
Shell
복사
◦
이미지 Pull 확인
docker images
Shell
복사
◦
추가적으로 GUI에서도 동일하게 이미지가 Pull 되었으며 준비된 상태를 확인 할 수 있다.
3.2.4 CLI 컨테이너 설정 및 실행 (Run)
다운로드 받은 이미지를 바탕으로 컨테이너를 실행
•
아래 명령어는 한 줄로 길게 이어지는 명령어로 도커 컨테이너의 이름과 설정을 GUI로 하나씩 설정하던 부분을 명령어로 모두 작성한 부분이다.
docker run --name vexhibition-db \
-e POSTGRES_USER=root \
-e POSTGRES_PASSWORD=1234 \
-e POSTGRES_DB=vexhibition \
-p 5432:5432 \
-v pgdata:/var/lib/postgresql/data \
-d pgvector/pgvector:pg16-trixie
Shell
복사
◦
해당 명령어는 각각 다음과 같은 설정이다.
▪
-name vexhibition-db : 컨테이너의 이름을 지정
▪
e (Environment) : DB 구동에 필요한 환경 변수(유저, 비밀번호, DB명)를 주입
▪
p 5432:5432 (Port) : 내 컴퓨터의 5432 포트와 컨테이너 내부의 5432 포트를 연결(포워딩).
▪
v pgdata:/... (Volume) : 컨테이너가 삭제되어도 데이터가 날아가지 않도록 볼륨을 마운트
▪
d (Detached) : 터미널을 종료해도 컨테이너가 백그라운드에서 계속 실행
▪
pgvector/pgvector:pg16-trixie : 실행할 이미지의 이름과 태그
•
실행 하면 다음과 같은 난수같은 것이 나타나고 터미널로 돌아온다. 해당 난수는 Container ID이다.
•
해당 컨테이너가 실제로 생성되었으며 실행 되고 있는지 아래 명령어로 확인 할 수 있다.
docker ps
Shell
복사
•
그 외 아래 명령어들로 컨테이너 실행을 제어 할 수 있다.
◦
컨테이너(이름 작성) 일시 정지 버튼을 대체하는 명령어
docker stop vexhibition-db
Shell
복사
◦
해당 컨테이너 시작 명령어
docker start vexhibition-db
Shell
복사
◦
해당 컨테이너 삭제 명령어 (삭제 전 반드시 stop 필요)
docker rm vexhibition-db
Shell
복사
▪
각 명령어를 사용하면 역시 동일하게 Docker Desktop 앱에서도 동일하게 적용되는 것을 확인 할 수 있을 것이다.
3.2.5 GUI MacOS에서 GUI(Docker.app)을 통한 PostgreSQL 설치
Docker Desktop을 이용한 PostgreSQL 설치는 윈도우와 동일하다.
•
사실 위 CLI 명령어로 복잡하게 진행 할 필요 없이 GUI가 지원되는 MacOS에서는 Docker Desktop을 사용해도 된다.
•
윈도우와 마찬가지로 간단히 클라우드 이미지로 PostgreSQL을 찾아 설치 하고 실행 할 수 있다.
•
동일한 부분이므로 다음 장을 참고하여 설치 및 실행 상태 확인 진행
3.3 [Ubuntu] 환경에서 Docker Compose를 활용한 인프라 세팅
3.2.1 배포 환경(Ubuntu)에 인프라 이해
AWS EC2(Ubuntu)와 같은 CLI 전용 배포 환경에서의 인프라 구축
•
실제 서비스 배포를 위해 사용하는 클라우드 서버(예: AWS EC2 리눅스 환경)에는 마우스로 조작할 수 있는 GUI(화면)가 존재하지 않는다. 따라서 오직 키보드 타이핑(CLI)만으로 Docker를 설치하고, 데이터베이스 환경을 구축해야 한다.
◦
이를 위해서 MacOS에서는 CLI 명령어만으로 Image Pull과 Container 구성 등을 진행해보았었다.
•
이런 CLI 명령어들을 모아서 통합 관리하며 사용하기 위해서 docker-compose.yml이라는 설정 파일을 활용할 수 있다.
•
앞서 GUI나 CLI 단일 명령어들을 순차적인 코드로 기록해 두고 명령어 한 줄로 똑같이 실행할 수 있다. 이를 코드로서의 인프라(IaC, Infrastructure as Code)라고 부른다.
3.2.2 EC2 Ubuntu 서버 터미널 접근
AWS EC2(Ubuntu)와 CLI 터미널 접근
•
클라우드 PC 서버에 접근하는 방법은 다양한 방법이 있지만, 가장 간단한 방법은 AWS가 제공하는 웹 브라우저에서 접근 할 수 있는 EC2 Instance Connect를 활용하는 것이 가장 간단하다.
◦
이 방법 외에 로컬 컴퓨터에서 SSH 프로토콜 등을 활용하여 로컬 터미널→원격 컴퓨터 터미널로의 접속을 하고 싶은 경우 별도 검색을 통해 환경 구축 하도록 한다. 참고로 EC2의 인바운딩 IP 설정과 키페어 등록 등의 작업이 추가된다.
◦
아래 예시에서는 초심자를 위해서 간단히 EC2 Instance Connect로 간단히 EC2 컴퓨터에 접근하는 방법을 사용하고자 한다.
•
AWS Console → EC2 → 실행중인 Instance Check → Connect
•
첫 번째 탭인 EC2 Instance Connect에서 별다른 설정 없이 기본 선택값에서 아래 Connect를 누르면 웹 브라우저에서 실행되는 클라우드 쉘 터미널을 실행 시킬 수 있다.
•
이미 AWS 로그인 정보 등을 통해서 접근한 상태이므로 부가적인 인증 등 설정 없이 곧바로 해당 EC2 컴퓨터의 터미널로 접근된 상태이다.
3.2.3 Docker 및 Docker Compose 설치
Ubuntu에서 Docker 설치
•
현재 브라우저에 나타나있는 클라우드 쉘에서는 CLI 명령어 만으로 환경을 구축해야한다. 이에 따라 MacOS 에서 CLI 명령어 만으로 환경을 구축하던 부분과 유사하게 진행된다.
•
다만, MacOS, Unix, Ubuntu, Linux 등 일부 명령어 차이가 있기 때문에 실행되지 않는다면 EC2의 시스템 환경에 따라서 검색하여 진행하면 된다.
1.
시스템 패키지 매니저 업데이트
sudo apt update
Shell
복사
2.
Ubuntu Docker 및 Docker Compose 설치
sudo apt install docker.io docker-compose -y
Shell
복사
3.
서버 재부팅 시 Docker 자동 실행 설정 및 즉시 시작 설정 및 설치 상태 확인
sudo systemctl enable docker
sudo systemctl start docker
Shell
복사
docker --version
docker-compose --version
Shell
복사
4.
docker-compose.yml 작성 및 실행
mkdir vexhibition-db
cd vexhibition-db
vim docker-compose.yml
Shell
복사
version: '3.8'
services:
postgres-vector:
image: pgvector/pgvector:pg16-trixie
container_name: vexhibition-db
ports:
- "5432:5432"
environment:
POSTGRES_USER: root
POSTGRES_PASSWORD: 1234
POSTGRES_DB: vexhibition
volumes:
- pgdata:/var/lib/postgresql/data
restart: always
volumes:
pgdata:
Shell
복사
•
위 작성 후 ESC→ :wq→ Enter로 에디터 탈출
•
docker-compose 실행
sudo docker-compose up -d
Shell
복사
◦
실행중인 컨테이너 확인
sudo docker ps
Shell
복사
3.2.4 컨테이너 실행 및 상태 확인
실행중인 컨테이너 확인
•
실행중인 컨테이너 확인
sudo docker ps
Shell
복사
•
실행중인 데이터베이스 내부 콘솔 접근
sudo docker exec -it vexhibition-db psql -U root -d vexhibition
Shell
복사
4. Vector 확장 활성화 (공통 필수)
•
위 3장 에서 다양한 개발 환경에 따른 Docker 기반의 PostgreSQL 데이터베이스 개발 환경 구축했다.
•
PostgreSQL은 기본적으로 관계형 데이터베이스(RDBMS) 역할만 하므로 RAG를 위해서는 Vector 데이터베이스 플러그인을 필수적으로 활성화 해야 한다.
확장 기능 활성화 쿼리 실행
•
데이터베이스 콘솔 접속
docker exec -it vexhibition-db psql -U root -d vexhibition
Shell
복사
•
SQL 쿼리 창(또는 psql 프롬프트)에서 아래 명령어를 순서대로 실행
◦
pgvector 확장 기능 활성화 명령
CREATE EXTENSION IF NOT EXISTS vector;
Shell
복사
◦
설치가 정상적으로 완료되었는지 확인
SELECT extname FROM pg_extension;
Shell
복사
Related Posts
Search
