백엔드 데이터 인프라 2편 — PostgreSQL 설치 (Docker·brew·apt 3가지)

이 글은 백엔드 데이터 인프라 시리즈 70편 중 2편이에요. 1편 에서 "PG(PostgreSQL, 오픈소스 관계형 DB)가 무엇이고 왜 한국 회사가 PG로 가는지" 다뤘으니, 이번 2편은 로컬에 PG를 직접 띄워 시리즈 흐름을 따라갈 환경을 만들어요.

설치가 헷갈리는 이유

PG 설치 방법은 공식 사이트만 봐도 5~6가지. 어떤 게 "실무에 가까운지", "개발자 PC에 안전한지" 가 헷갈려요.

이 글에서는 3가지로 좁혀 풀어요. Docker 는 가장 안전·표준이라 기본 권장이고, Homebrew 는 macOS 네이티브 설치, apt 는 Linux(Ubuntu·Debian) 네이티브 경로예요.

Windows는 — WSL2(Windows에서 리눅스를 돌리는 호환층) + apt 또는 Docker Desktop이 표준. 직접 .exe 설치는 권장 X.

방법 1 — Docker (가장 권장)

Docker를 권장하는 이유는 네 가지예요. 개발 PC 호스트가 깨끗하게 유지돼서 PG 프로세스가 호스트에 안 박히고, 버전 격리가 돼서 PG 16·17·18을 동시에 띄울 수 있고, 끄고 켜기가 즉시 가능하고, 운영 환경과 거의 동일해서 CI(자동 빌드·테스트 파이프라인)도 같은 Docker 기반으로 굴러가요.

한 줄 시작

docker run -d \
  --name postgres-dev \
  -e POSTGRES_PASSWORD=devpass \
  -p 5432:5432 \
  postgres:18

설명: - -d = 백그라운드 실행 - --name postgres-dev = 컨테이너 이름 (관리 편하게) - -e POSTGRES_PASSWORD=devpass = 슈퍼유저(postgres) 비밀번호 설정 (필수 — 빠뜨리면 시동 실패) - -p 5432:5432 = 호스트 5432 ↔ 컨테이너 5432 - postgres:18 = 공식 이미지, PG 18 안정 버전

데이터 영속화 — Volume

기본 컨테이너는 "컨테이너 삭제 = 데이터 삭제". 영속화하려면 Volume.

docker run -d \
  --name postgres-dev \
  -e POSTGRES_PASSWORD=devpass \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  postgres:18

pgdata Volume이 자동 생성돼서 — 컨테이너 지워도 데이터 살아남음. 운영 환경 표준 패턴.

접속 확인

# 컨테이너 안 psql로 접속
docker exec -it postgres-dev psql -U postgres

# 또는 호스트의 psql로 (호스트에 psql 설치된 경우)
psql -h localhost -U postgres

psql 프롬프트가 뜨면 — 설치 성공.

psql (18.4)
Type "help" for help.

postgres=#

방법 2 — macOS Homebrew

호스트에 직접 설치. "개발 단순함" 추구할 때.

brew install postgresql@18
brew services start postgresql@18

brew services 가 PG를 백그라운드 서비스로 등록. 시스템 시작 시 자동 시동.

초기 사용자

Homebrew 설치는 — postgres 슈퍼유저 + 현재 macOS 사용자명을 같은 이름으로 자동 생성. 비밀번호 없이 로컬 접속 가능.

psql -d postgres

또는 직접 사용자 만들기:

createuser --interactive --pwprompt
createdb myappdb

createuser·createdb 는 PG가 함께 설치하는 헬퍼 명령. psql 안에서 안 짜도 OS 명령으로.

끄고 켜기

brew services stop postgresql@18
brew services start postgresql@18
brew services restart postgresql@18

방법 3 — Ubuntu·Debian apt

운영 서버에 가장 가까운 환경. 실무에서 자주.

# apt 패키지 색인 추가 (PG 공식 저장소)
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
    --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc

sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \
    https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \
    > /etc/apt/sources.list.d/pgdg.list'

sudo apt update
sudo apt install -y postgresql-18

# 시동
sudo systemctl start postgresql
sudo systemctl enable postgresql       # 부팅 시 자동 시동

초기 사용자

apt 설치는 — postgres 라는 OS 사용자가 자동 생성, 그 사용자로 PG에 접속.

sudo -u postgres psql

비밀번호 박기:

ALTER USER postgres WITH PASSWORD 'devpass';

검증 — Hello PostgreSQL

설치 방법과 무관하게 — 첫 접속 후 같은 명령으로 검증.

-- 버전 확인
SELECT version();

-- 현재 사용자
SELECT current_user;

-- 데이터베이스 목록
\l

-- 테이블 목록 (현재 빈 상태)
\dt

-- 간단한 쿼리
SELECT 1 + 1 AS result;

-- 첫 테이블 만들기
CREATE TABLE hello (id SERIAL PRIMARY KEY, msg TEXT);
INSERT INTO hello (msg) VALUES ('Hello PostgreSQL');
SELECT * FROM hello;

-- 정리
DROP TABLE hello;

-- psql 종료
\q

위 흐름이 정상이면 설치·접속·SQL 다 OK.

psql 자주 쓰는 명령

psql 안에서 \ 로 시작하는 명령들 — "메타 명령". SQL이 아니라 psql 자체의 단축.

\? 하나만 외워도 나머지 다 찾을 수 있어요.

GUI 도구 — DBeaver·pg_admin

CLI(터미널 명령줄 인터페이스) 익숙해지면 충분하지만 — GUI도 자주 씁니다. DBeaver 는 무료에 멀티 DB 지원으로 한국에서 가장 흔하고, pg_admin 은 PG 공식 GUI, TablePlus 는 macOS·Windows 유료지만 가벼운 게 장점이에요.

설치 후 접속 정보: host=localhost·port=5432·user=postgres·password=설정한 값. 검증 완료된 PG에 GUI 한 번 연결해 보면 — 테이블 보기·쿼리 작성이 한결 편해요.

Spring Boot 연결 — 미리 보기

자바 백엔드 입문 44~50편 JPA 의 Spring 백엔드를 우리 PG에 연결할 때 — application.yml 한 줄:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/postgres
    username: postgres
    password: devpass
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect

자바 백엔드 입문 13편 Profiles 에 다뤘듯이 — application-local.yml 에 박아 두면 개발 환경 따로 운영 환경 따로.

함정 5가지

(1) Docker POSTGRES_PASSWORD 누락

docker run -d --name pg postgres:18   # ❌ 시동 실패
# Error: Database is uninitialized and superuser password is not specified.

-e POSTGRES_PASSWORD=... 필수.

(2) 포트 5432 충돌

이미 PG가 호스트에 떠 있는 상태에서 또 띄우면 — port already in use. 호스트 포트 다른 번호로:

-p 5433:5432

(3) Volume 안 박고 컨테이너 지움

docker rm -f postgres-dev   # 데이터 사라짐!

영속화 필요하면 -v pgdata:/var/lib/postgresql/data 필수.

(4) Homebrew + Docker 충돌

호스트에 brew PG 깔린 상태에서 Docker도 5432 띄우면 충돌. 하나만 사용 또는 포트 다르게.

(5) PG 슈퍼유저 비밀번호 운영에 그대로

devpass 같은 약한 비밀번호를 운영에 쓰면 위험. 운영 환경 = AWS Secrets Manager·HashiCorp Vault 같은 비밀 관리 도구.

한 줄 정리 — Docker가 가장 안전·표준. Homebrew는 macOS 네이티브. apt는 Ubuntu·운영 가까운 환경. POSTGRES_PASSWORD + Volume 두 가지가 함정. 첫 접속 후 \l·\dt·SELECT version() 으로 검증.

시험 직전 한 번 더 — PostgreSQL 설치 입문자가 매번 헷갈리는 것

• Docker = 가장 권장 (개발 + CI + 운영 일관성)
• 한 줄 시작 = docker run -d --name postgres-dev -e POSTGRES_PASSWORD=devpass -p 5432:5432 postgres:18
• POSTGRES_PASSWORD 필수 — 빠뜨리면 시동 실패
• 데이터 영속화 = Volume -v pgdata:/var/lib/postgresql/data
• 포트 = 5432 (기본)
• Homebrew = macOS 네이티브 — brew install postgresql@18
• 시동 = brew services start postgresql@18
• apt = Ubuntu·운영 가까움
• 공식 저장소 = apt.postgresql.org/pub/repos/apt
• 시동 = sudo systemctl start postgresql
• psql = PG 표준 CLI
• 접속 = psql -h localhost -U postgres 또는 docker exec -it postgres-dev psql -U postgres
• 메타 명령 = \?·\l·\dt·\d <table>·\du·\q
• SELECT version(); = 버전 확인
• GUI = DBeaver(무료) · pg_admin · TablePlus
• Spring Boot 연결 = jdbc:postgresql://localhost:5432/postgres
• 드라이버 = org.postgresql.Driver
• Hibernate 방언 = org.hibernate.dialect.PostgreSQLDialect
• 운영 비밀번호 = Secrets Manager·Vault
• 함정 = 포트 충돌·Volume 누락·약한 비밀번호 운영
• 입문자 표준 = Docker 한 줄 + Volume

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 1편 — PostgreSQL이란 + MySQL과의 비교

다음 글:

• 3편 — PostgreSQL 아키텍처 (클라이언트·서버·DB·테이블)
• 4편 — psql 첫 접속과 기본 명령
• 5편 — 데이터베이스 만들기 CREATE DATABASE
• 6편 — PostgreSQL 데이터베이스 접속·전환
• 7편 — PostgreSQL 관계형 모델 핵심 개념