pgadmin docker 배포 및 docker PostgreSQL 연결

PostgreSQL을 관리하기 위해, pgAdmin을 Docker Compose로 배포하는 방법을 정리해요. pgAdmin은 브라우저 기반 GUI 도구라서 데이터베이스를 직관적으로 다루고, 사용자와 권한을 쉽게 관리할 수 있어요. Docker Compose 파일에 pgAdmin 서비스만 정의하고, 기존 Postgres와 연결해서 활용하는 과정을 단계별로 알아볼게요.

 

📑 목차

• 개요
• pgAdmin 배포
• pgAdmin 접속
• 기존 Postgres 연결
• 보안 권장사항
• 정리

 

개요

안녕하세요.

낙노즈 입니다. 오늘은 Docker 내 Database를 쉽게 접근하고 관리할 수 있게 할 수 있는 글을 써보려고해요.

 

Docker로 Database를 쉽게 배포하고 실행할 수 있어요. 저도 그렇게 사용중인데 신규 테이블을 생성하거나

스키마를 변경하는 등 작업을 하려고 할때마다 호스트 PC 접근 -> 컨테이너 접근 -> psql 접근

이러한 접근이 번거롭다고 느껴졌어요. DB 관리 도구를 사용하려고 했는데,

 

제가 배포한 데이터베이스 컨테이너는 외부 접근은 필요 없어서 Docker 내부 네트워크끼리만 통신 할 수 있도록 허용된 상태였어요. 고심하던 차에 DB관리 도구를 Docker로 배포한 뒤 사용하는 사례가 있어서 한번 구성해 보려고 해요.

 

제가 사용중인 데이터베이스는 PostgreSQL로 N8N에서 사용중이에요.

2025.08.29 - [N8N] - N8N 셀프 호스팅 구축기 (5) - CloudFlare Domain + Hetnzer VPS + Docker Compose + N8N (하)

N8N 셀프 호스팅 구축기 (5) - CloudFlare Domain + Hetnzer VPS + Docker Compose + N8N (하)

 

 

pgAdmin 배포

pgAdmin은 dpage/pgadmin4 이미지를 이용해요.
Compose 파일에 환경 변수를 지정해서 초기 계정을 만들어줘요.

아래 docker compose 형식을 사용해주세요.

yaml docker-compose.yml

Code

services:
  pgadmin:
    image: dpage/pgadmin4:latest
    restart: always
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@example.com
      PGADMIN_DEFAULT_PASSWORD: admin123
    ports:
      - "8080:80"
    volumes:
      - pgadmin-data:/var/lib/pgadmin

volumes:
  pgadmin-data:

위 .yml에 중요한 건 PGADMIN_DEFAULT_EMAIL / PGADMIN_DEFAULT_PASSWORD 예요.

계정 정보를 설정하는 부분이니 원하는 메일 / 패스워드로 변경해주세요.

 

위 코드로 yml 파일을 만든 뒤 명령어 docker compose up -d 를 실행하면 pgAdmin 컨테이너가 올라와요.

기존 docker compose 네트워크에 연결

docker compose를 실행 시 같은 yaml 파일에 속한 서비스들은 자동으로 같은 네트워크에 속해요.

그래서 그 컨테이너들은 IP가 아닌 지정된 서비스명을 통해 통신할 수 있어요.

 

문제는 다른 yaml 파일에 있을 경우 기본적으로 다른 네트워크에 올라가서 동작하도록 구성돼요.

저는 기존 postgres를 관리하고자 pgadmin을 구축하는건데, 관리하고싶은 DB에 접근할 수 없으면 문제되겠죠.

 

문제를 해결하는 방법은 크게 2가지가 있어요.

- yaml 파일 내 network를 정의하여 공통 네트워크로 명시하는 방법

- docker-compose.override.yml를 사용하는 방법

 

문제는 기존 yaml 파일 내 network를 정의하지 않았다면 기존 파일을 수정해야하는데,

yaml 파일 내 서비스가 여러개 구성되어 있고 복잡할 경우 귀찮을 수 있어요.

 

그래서 저는 docker-compose.override.yml을 사용했어요.

 

docker-compose.override.yml

 

docker-compose.override.yml은 기존 docker-compose.yml을 확장하거나

덮어쓰는(override) 용도로 쓰이는 추가 설정 파일이에요.

Docker Compose는 기본적으로 프로젝트 실행 시 다음 두 가지 파일을 자동으로 읽습니다:

• docker-compose.yml
• docker-compose.override.yml

즉, 같은 디렉토리에 docker-compose.override.yml 파일이 있으면,

별도 옵션 없이 docker compose up 했을 때 두 파일을 합쳐서 실행돼요.

 

그래서 저는 위의 pgadmin yaml을 docker-compose.override.yml로 저장했어요.

그리고 기존에 실행 중이던 서비스를 내린 뒤에 다시 실행하니 pgadmin이 같이 배포된 것을 볼 수 있어요.

CLI n8n@hetzner:~

Shell

vi docker-compose.override.yml
# pgadmin용 yaml 생성
docker compose down 
docker compose up -d

 

 

pgAdmin 접속

브라우저에서 8080 포트로 접속하면 로그인 화면이 보여요.
환경 변수로 지정한 이메일과 비밀번호를 입력해서 로그인해요.

 

*저는 Hetzner Cloud에서 대여한 서버를 이용중이기 때문에 8080포트로 접속하려면 방화벽 설정을 변경해야했어요.

 

로그인 하면 다음과 같은 화면을 볼 수 있어요.

기존 Postgres 연결

이제 기존에 실행 중인 Postgres를 연결해요.
pgAdmin Dasboard에서 좌측 상단의 [ Servers ]에 우클릭해요.

[ Register ] - [ Server... ]를 눌러요.

 

그럼 아래와 같은 Register 창이 나타나요.

[ Name ] 부분에 등록할 서버의 이름을 지정해주세요.

Connection 탭으로 이동한 뒤 아래와 같이 입력하고 [ Save ]를 눌러요.

• Host Name: Postgres 컨테이너 서비스 이름 또는 서버 IP
• Port: 5432
• Username: Postgres 사용자명 (예: admin)
• Password: 비밀번호

 

저장을 누르면 서버가 등록되고, 데이터베이스 트리가 나타나요.
이제 GUI에서 쿼리 실행과 계정 관리, DB 생성 작업을 편리하게 할 수 있어요.

 

 

정리

이 글에서는 pgAdmin을 Docker Compose로 배포하고,

기존에 Docker에 구동중인 Postgres와 연결하는 방법을 정리했어요.

 

여러분들이 자동화를 할 때 데이터베이스를 구성해야할 수도 있어요.

예를 들어 테이블을 구성하거나 설정을 변경하는 등의 작업을 할때 매번 CLI로 작업을 수행하기가 번거로울 수 있어요.

그런 점에서 pgAdmin등의 데이터베이스 관리 도구는 데이터베이스를 GUI로 편리하게 관리할 수 있게 해줘요.

 

운영 환경에서는 반드시 보안을 강화하고 계정과 네트워크를 체계적으로 관리해야 해요.