새로 합류한 팀원이 첫 빌드에서 막혔다. 온보딩 문서에 없던 내용이라 적어둔다.

Could not connect to Docker daemon
> Task :jooqCodegen FAILED

왜 Docker가 필요한가

jOOQ는 실제 데이터베이스 스키마를 읽어서 타입 안전한 클래스를 생성한다. 스키마 파일을 파싱하는 게 아니라, 진짜로 붙어서 메타데이터를 조회한다.

그래서 jooqCodegen이 하는 일은 이렇다.

1. Testcontainers로 pgvector/pgvector:pg18 컨테이너를 띄운다

2. 거기에 Liquibase 마이그레이션을 전부 적용한다

3. 완성된 스키마를 읽어 build/generated/jooq/에 클래스를 만든다

4. 컨테이너를 버린다

즉 빌드할 때마다 일회용 진짜 Postgres가 필요하다. 그래서 Docker 데몬이 떠 있어야 한다.

좋은 점

번거로워 보이지만 얻는 게 크다. 마이그레이션과 생성된 코드가 구조적으로 어긋날 수 없다. 컬럼 이름을 바꾸면 다음 빌드에서 생성 클래스가 바뀌고, 그걸 쓰던 코드는 컴파일 에러가 난다. 런타임에 터지지 않는다.

개발용 DB에 붙여서 코드젠하는 방식이었다면, 그 DB에 누가 손으로 컬럼을 추가해둔 순간 조용히 오염된다.

순서 주의

마이그레이션을 추가했다면 코드젠을 다시 돌려야 새 컬럼이 보인다.

docker compose -f apps/server/compose.yaml up -d
./gradlew jooqCodegen

./gradlew build는 jooqCodegen을 먼저 실행하므로 보통은 신경 쓸 일이 없다. 다만 IDE가 아직 옛 클래스를 잡고 있으면 Gradle 새로고침이 필요할 수 있다.

로컬 인프라 정리

서버 띄우기 전에 필요한 건 결국 이 셋이다.

docker compose -f apps/server/compose.yaml up -d              # PostgreSQL
docker compose -f infra/localstack/docker-compose.yml up -d   # S3
docker compose -f infra/ollama/docker-compose.yml up -d       # Ollama

환경변수는 .envrc가 direnv로 넣어준다. 클론 후 direnv allow 한 번은 꼭 필요하다.