로컬 PostgreSQL과 Docker PostgreSQL의 포트 충돌

Kim jisu·2025년 4월 17일

Debugging Note

목록 보기

22/37

🐘 로컬 PostgreSQL과 Docker PostgreSQL의 포트 충돌 해결기

문제 상황

Docker로 PostgreSQL 컨테이너를 실행하려고 다음과 같이 docker-compose.yml을 구성했습니다.

services:
  postgres:
    image: postgres:latest
    ports:
      - "5432:5432"

그런데 다음과 같은 오류가 발생했습니다:

ERROR: for postgres  Cannot start service postgres: driver failed programming external connectivity on endpoint ...
Bind for 0.0.0.0:5432 failed: port is already allocated

🔍 원인 분석

오류 메시지에서 port is already allocated는 5432번 포트가 이미 사용 중이라는 의미입니다. PostgreSQL의 기본 포트는 5432이며, 로컬에 설치된 PostgreSQL이 해당 포트를 점유하고 있는 것으로 의심됐습니다.

✅ 포트 점유 확인

다음 명령어로 실제 사용 중인 프로세스를 확인했습니다:

netstat -ano | findstr :5432

결과:

TCP    127.0.0.1:5432      0.0.0.0:0      LISTENING      8520

5432 포트를 사용하는 프로세스의 PID는 8520입니다.

✅ 어떤 프로세스인지 확인

tasklist /FI "PID eq 8520"

결과:

postgres.exe                  8520 Console                    1     19,584 K

로컬에 설치된 PostgreSQL 서버가 실행 중이었고, 이로 인해 Docker PostgreSQL이 실행되지 않았던 것입니다.

🔧 해결 방법

방법 1️⃣: 로컬 PostgreSQL 종료

관리자 권한으로 명령 프롬프트 실행
다음 명령어로 종료:

taskkill /PID 8520 /F

⚠️ 만약 액세스 거부 오류가 난다면, 관리자 권한으로 실행했는지 확인하거나 서비스로 실행 중인지 확인이 필요합니다.

방법 2️⃣: PostgreSQL 서비스 중지 (서비스로 실행 중일 경우)

net stop postgresql-x64-15

PostgreSQL 서비스 이름은 services.msc에서 확인 가능

🐳 Docker PostgreSQL 재시도

로컬 PostgreSQL을 종료한 후 다시 Docker Compose 실행:

docker-compose up -d

이번에는 정상적으로 PostgreSQL 컨테이너가 실행되었습니다.

💡 마무리

이번 경험을 통해 알게 된 포인트:

PostgreSQL은 기본적으로 5432번 포트를 사용하며, 충돌 시 Docker에서 컨테이너 실행이 실패할 수 있음
포트 충돌이 발생하면 netstat + tasklist 명령어로 원인을 파악
로컬 PostgreSQL과 Docker PostgreSQL을 공존시키려면 포트를 바꿔주는 것도 방법
```
ports:
  - "15432:5432"  # 로컬에서는 15432로 접근
```

📌 참고 명령어 요약

# 포트 점유 확인
netstat -ano | findstr :5432

# 해당 PID 프로세스 확인
tasklist /FI "PID eq <pid>"

# 프로세스 강제 종료
taskkill /PID <pid> /F

# PostgreSQL 서비스 종료
net stop postgresql-x64-15