Docker로 띄운 PostgreSQL에 접속하는 방법

애플리케이션을 개발할 때 로컬 PC에 직접 데이터베이스를 설치하는 대신, 도커(Docker)를 활용해 데이터베이스를 띄우는 방식이 실무의 표준으로 자리잡았습니다. 환경 구축이 매우 간편하고, 다른 팀원들과 동일한 환경을 유지하기 쉽기 때문입니다.

오늘은 Docker로 띄운 PostgreSQL을 터미널, 인텔리제이(IntelliJ), docker Desktop GUI에서 접속하는 방법에 대해 정리해보겠습니다.

2026.05.26 - [Tech/Docker] - 도커 이미지와 컨테이너의 차이, 그리고 Docker Compose

도커 이미지와 컨테이너의 차이, 그리고 Docker Compose

2026.05.26 - [Tech/Docker] - Docker Container 간 통신 원리(DNS)와 docker-compose 라이프사이클 분리 전략

Docker Container 간 통신 원리(DNS)와 docker-compose 라이프사이클 분리 전략

준비 사항: docker-compose와 .env 설정

가장 표준적으로 사용되는 docker-compose.yaml 파일과, 환경 변수를 모아둔 .env 파일의 구조를 기준으로 설명하겠습니다. 실행하려는 docker-compose.yaml 파일이 위치한 폴더에 .env파일이 함께 존재해야 합니다.

docker-compose.yaml

services:
  db:
    image: postgres:16
    container_name: my-postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_DATABASE}
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    networks:
      - my-network

networks:
  my-network:
    name: my-network
    driver: bridge

.env

# Database 설정
DB_URL=jdbc:postgresql://db:5432/my-db
DB_USERNAME=my-user
DB_PASSWORD=my-password
DB_DATABASE=my-db

컨테이너의 이름은 my-postgres로 지정했으며, 외부 포트와 내부 포트를 모두 PostgreSQL의 기본 포트인 5432로 설정하였습니다. 접속에 사용할 사용자 계정과 데이터베이스명은 .env 파일에서 주입받도록 구성했습니다.

터미널(CLI)에서 접속하기

터미널을 열고 docker-compose 파일이 존재하는 경로로 이동한 뒤에, 아래 명령어를 통해 백그라운드 모드로 데이터베이스를 실행합니다.

docker-compose up -d

이후 docker ps 명령어를 입력하여 my-postgres 컨테이너가 정상적으로 구동되어 Up 상태를 유지하고 있는지 확인합니다.

도커 컨테이너는 가상 환경 내부에서 격리되어 실행되므로, 외부 터미널에서 내부의 Psql 툴을 실행하기 위해 docker exec 명령어를 활용해야 합니다. 기본 형식은 다음과 같습니다.

docker exec -t [컨테이너_이름] psql -U [DB_유저네임] -d [DB_이름]

설정한 .env 환경 변수 값을 대입하여 터미널에 아래와 같이 입력합니다.

docker exec -it my-postgres psql -U my-user -d my-db

여기에서 -U는 .env 파일 내의 DB_USERNAME에 지정한 계정명이며, -d는 DB_DATABASE에 지정한 데이터베이스명입니다. 정상적으로 연결이 완료되면 터미널 화면에 PostgreSQL 버전 정보와 함께 쿼리를 입력할 수 있는 my-db= 프롬프트가 노출됩니다. 작업을 모두 마치고 터미널로 돌아오고 싶을 때는 exit 명령어를 입력하면 됩니다.

인텔리제이(IntelliJ) Database 탭에서 접속하기

1. 인텔리제이 우측 사이드바에 위치한 Database 탭을 클릭합니다.

2. 탭 상단의 + 버튼을 누르고, Data Source → PostgreSQL을 선택합니다.

3. General 설정 창에서 아래의 항목을 입력합니다.

설정 항목	입력 값
Host	localhost 혹은 127.0.0.1
Port	5432 (docker-compose에서 설정한 포트)
User	my-user (.env의 DB_USERNAME 값)
Password	my-password (.env의 DB_PASSWORD 값)
Database	my-db (.env의 DB_DATABASE 값)

4. 모든 값을 채운 뒤 왼쪽 아래의 Test Connection 버튼을 클릭했을 때 초록색 체크 표시가 노출되면 연동된 것 입니다.

Docker Desktop GUI로 접속하기

1. Docker Desktop 앱을 실행하고, 좌측 메뉴에서 Container 탭을 클릭합니다.

2. 현재 실행 중인 컨테이너 목록 중 my-postgres를 찾아 클릭합니다.

3. 컨테이너 상세 페이지가 열리면, 상단의 여러 탭 중에서 Exec 탭을 클릭합니다. 이 화면이 바로 컨테이너 내부와 직접 연결된 웹 터미널입니다.

4. 이미 컨테이너 내부에 들어온 상태이기 때문에, psql 접속 명령어를 바로 입력합니다.

psql -U my-user -d my-db

인텔리제이와 도커 컨테이너의 접속 주소가 다른 이유

저는 해당 작업을 진행하며 의문이 생겼습니다. 환경 변수의 DB_URL을 보면 db:5432라는 주소로 명시되어 있는데, 왜 인텔리제이 설정 창에서는 localhost:5432로 입력해야 접속이 되는 것일까?

이유는 네트워크를 바라보는 '접속 주체의 위치'에 있습니다. 

상황 1: 인텔리제이에서 도커 DB로 접근할 때 (외부 접근)

인텔리제이는 도커 컨테이너 내부가 아닌, 로컬 PC 환경 위에서 실행되는 프로그램입니다. 도커 엔진 관점에서 로컬 PC는 격리된 외부 공간입니다. 따라서 가상화된 컨테이너 내부로 진입하려면, 도커가 호스트 PC를 향해 열어둔 통로인 ports 설정을 타야합니다. 5432:5432 설정을 통해 로컬 PC의 localhost:5432로 들어오는 트래픽이 컨테이너 내부의 5432 포트로 포워딩되는 구조입니다. 즉, 인텔리제이는 로컬 PC의 포트를 타고 들어가야 하므로 주소가 localhost가 됩니다.

상황 2: 스프링 부트 컨테이너에서 도커 DB로 접근할 때 (내부 접근)

반면, 도커 컨테이너로 빌드되어 동일한 도커 네트워크 안으로 띄워진다면 굳이 외부 localhost 포트를 경유하지 않고, 도커 내부에 탑재된 자체 내장 DNS 서버를 통해 호스트 IP 대신 컨테이너 서비스 이름(예: db)을 주소 값으로 사용하여 네트워크 내부에서 직접 다이렉트로 호출할 수 있게 됩니다. 이 때문에 컨테이너 간 연동 시엔 localhost가 아닌 컨테이너 식별 주소를 사용하게 됩니다.

마무리

오늘은 도커 환경에서 구동되는 PostgreSQL 데이터베이스를 통제하기 위해 터이널 CLI, Docker Desktop GUI, 인텔리제이(IntelliJ0 환경에서 연동하는 방법을 살펴보았습니다. 그리고 네트워크 접근 주체에 따른 주소 매핑 원리까지 학습했습니다.