[Mac/PostgreSQL] 설치 및 초기 셋팅

 또 다시 새로운 걸 들고 돌아온 나다. 진행 중인 프로젝트는 뷔폐에서 남긴 접시만큼 쌓여가지만, 언제나 그렇듯 다른 뭔가는 더 맛있겠지 하며 새 접시를 들고 간다...

 

(올해 말에 잔반 처리를 좀 해야하긴 하겠다..)

 

오늘은 Homebrew를 이용해 내 M4 맥북에 PostgreSQL을 설치하고, 세팅하고, 마주쳤던 오류들을 해결한 과정을 기록해 보려고 한다.

1. Homebrew로 PostgreSQL 설치

가장 먼저 할 일은 역시나 Homebrew를 통해 PostgreSQL을 설치하는 것이다. 특정 버전을 사용하기 위해 @를 붙여 명시적으로 설치를 진행했다.

brew install postgresql@17

터미널에 위 명령어를 입력하면 Homebrew가 알아서 최신 버전의 PostgreSQL(현재 17)을 설치해 준다. 여기까지는 아주 순조롭다.

2. 데이터베이스 초기화 (initdb)

설치만 하면 끝인 줄 알았는데, PostgreSQL은 데이터를 저장할 공간을 만들어주는 '초기화' 과정이 필요했다. initdb 명령어를 사용해 데이터베이스 클러스터라는 것을 생성해 줘야 한다.

initdb -D /opt/homebrew/var/postgresql@17

-D 옵션은 데이터베이스 파일들을 저장할 디렉토리를 지정하는 옵션이다. Homebrew로 설치 시 위 경로가 기본 경로가 된다.

(Intel Mac의 경우 /usr/local/var/postgresql@17 이다.)

3. 서버 실행 및 자동 시작 등록 

이제 데이터베이스 서버를 켤 차례. 매번 컴퓨터를 켤 때마다 직접 켜주기는 귀찮으니, brew services를 이용해 컴퓨터가 켜질 때마다 자동으로 실행되도록 등록해 주자.

# 서버 시작 및 자동 실행 등록
brew services start postgresql@17

# 서버가 잘 켜졌는지 상태 확인
brew services list

postgresql@17의 상태가 started로 나오면 성공이다. 참고로 중지하고 싶을 땐 brew services stop postgresql@17을 사용하면 된다.

4. 접속 및 프로젝트용 DB/User 세팅 

서버도 켰으니 이제 접속해서 프로젝트에 사용할 전용 유저와 데이터베이스를 만들어보자. 최고 관리자로 모든 걸 다 하는 건 좋지 않은 습관이니까.

 

# 1. 기본 DB에 최고 관리자로 접속
psql postgres

# 2. 접속 확인 후 \q로 나가기, 프로젝트 전용 유저 생성 및 비번 설정
createuser --interactive 
# -> 이름 물어보면 example_user 입력, 슈퍼유저 여부 물어보면 n 입력

# 3. terminal 프로젝트 전용 DB 생성
createdb -O example_user exampleDB

# 4. psql 접속 후, 사용자 비밀번호 설정
\password example_user
# -> 사용할 비밀번호 두 번 입력

5. 내가 마주했던 오류들 (삽질 로그)

역시나 순탄하게만 흘러가진 않았다. 내가 마주했던 두 가지 큰 오류와 해결 과정을 정리해 본다.

오류 1: zsh: command not found: initdb

가장 먼저 나를 반긴 건 initdb 명령어를 찾을 수 없다는 메시지였다. 분명히 설치를 했는데?

• 원인: Homebrew가 postgresql@17처럼 버전을 명시해서 설치한 경우, 다른 버전과의 충돌을 막기 위해 실행 파일들을 공용 경로가 아닌 자신만의 독립적인 경로에만 설치한다. 셸(zsh)이 이 독립적인 경로를 알지 못해서 발생하는 문제였다.
• 해결: postgresql@17의 실행 파일이 있는 정확한 경로를 ~/.zshrc 파일에 추가해주고, source 명령어로 바로 적용시켜주니 해결됐다.
• Bash

   

  # 1. postgresql@17의 정확한 bin 경로를 .zshrc에 추가
  echo 'export PATH="$(brew --prefix postgresql@17)/bin:$PATH"' >> ~/.zshrc
  
  # 2. 변경사항 바로 적용
  source ~/.zshrc
  

오류 2: initdb: 오류: ... 디렉터리가 있지만 비어 있지 않음

경로 문제를 해결하고 다시 initdb를 실행하니 이번엔 디렉토리가 비어있지 않다는 오류가 발생했다.

• 원인: initdb는 '완전히 비어있는' 디렉토리에만 실행할 수 있다. 이전에 command not found 상태에서 여러 번 명령을 시도하는 과정에서 디렉토리가 생성되고 일부 파일이 남아있었던 것으로 보인다.
• 해결: 가장 깔끔한 방법은 기존 디렉토리를 완전히 삭제하고 다시 시도하는 것이다.
• Bash

   

  # 1. 혹시 모르니 서비스가 실행 중이라면 중지
  brew services stop postgresql@17
  
  # 2. 문제가 되는 디렉토리 완전 삭제
  rm -rf /opt/homebrew/var/postgresql@17
  
  # 3. 다시 초기화 진행 -> 성공!
  initdb -D /opt/homebrew/var/postgresql@17
  

 

 

이렇게 PostgreSQL 설치와 트러블슈팅 과정을 정리해 보았다. 

 

이제 다시 새 접시에 맛있는 음식을 담으러 가자.

 

끝!