Docker pgAdmin: Docker Compose로 PostgreSQL GUI 설정하기

Docker Compose로 pgAdmin 4와 PostgreSQL을 설정하는 단계별 가이드입니다. 컨테이너 구성, 서버 등록, Query Tool·스키마 브라우저·백업/복원 등 핵심 기능을 다룹니다.

업데이트됨 2026년 5월 4일 · 10분 읽다

세션을 오가고, 구문을 외우며, 파괴적 쿼리에 오타가 없기를 바라는 일은 금세 지칩니다. 시각적 쿼리 플랜도, 스키마 브라우저도, 간편한 백업 방법도 없습니다. 동작은 하지만, 이상적이라고 하긴 어렵습니다.

pgAdmin 4는 PostgreSQL을 위해 설계된 브라우저 기반 GUI로 이런 문제를 해결합니다. Docker로 실행하면 로컬 설치가 전혀 필요 없습니다. 컨테이너만 시작하면 됩니다.

이 글에서는 Docker Compose로 PostgreSQL과 pgAdmin 4를 설정하고, 두 컨테이너를 연결한 다음, pgAdmin의 Query Tool, 스키마 브라우저, 백업 기능을 사용하는 방법을 보여드립니다.

따라 하려면 머신에 Docker가 설치되어 실행 중이어야 합니다. Docker Compose가 처음이라면, 멀티 컨테이너 개발을 어떻게 단순화하는지 설명한 가이드를 읽어보세요.

pgAdmin 4란?

pgAdmin 4는 오픈 소스 브라우저 기반 PostgreSQL 관리 및 개발 플랫폼입니다. 웹 브라우저로 접근하므로 데스크톱 앱을 설치할 필요가 없습니다. GUI로 데이터베이스 관리, 쿼리 실행, 스키마 확인, 백업 처리까지 커맨드 라인 없이 수행할 수 있습니다.

공식 Docker 이미지는 pgAdmin 개발 팀이 관리하는 dpage/pgadmin4입니다.

Docker에서 pgAdmin 4를 실행하면 로컬 설치 대비 명확한 장점이 있습니다. 첫째, 이식성입니다. 전체 데이터베이스 환경이 팀원과 공유 가능한 docker-compose.yml 파일에 담깁니다. 둘째, 버전 충돌이 없습니다. pgAdmin은 자체 컨테이너에서 실행되어 머신의 다른 것들과 완전히 격리됩니다. 작업이 끝나면 docker compose down으로 깔끔히 지울 수 있습니다.

pgAdmin 4와 다른 PostgreSQL GUI 비교

데이터베이스 관리 GUI 도구는 많습니다. 아래는 pgAdmin 4를 인기 대안 두 가지와 비교한 내용입니다.

pgAdmin 4와 인기 대안 비교

DBeaver와 TablePlus도 훌륭한 도구지만, 공식 Docker 이미지는 없습니다. PostgreSQL 인스턴스를 이미 Docker에서 실행 중이라면 pgAdmin 4가 훌륭한 선택입니다. docker-compose.yml에 서비스 하나만 추가하면 모두 같은 네트워크에서 함께 실행됩니다.

Docker Compose로 환경 설정하기

PostgreSQL과 pgAdmin 4를 함께 실행하는 가장 빠른 방법은 하나의 docker-compose.yml 파일을 쓰는 것입니다. 주제가 처음이라면 Docker Compose 가이드에서 기본을 확인하세요. 여기서는 pgAdmin 전용 설정에 집중하겠습니다.

아래 전체 파일을 복사해 사용하세요:

services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - pgnetwork

  pgadmin:
    image: dpage/pgadmin4:9.13
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: you@yourdomain.com
      PGADMIN_DEFAULT_PASSWORD: password
      PGADMIN_LISTEN_PORT: 5050 
    ports:
      - "5050:5050"                
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - pgnetwork

volumes:
  postgres_data:
  pgadmin_data:

networks:
  pgnetwork:

depends_on 필드는 Docker Compose가 pgadmin보다 먼저 postgres 컨테이너를 시작하도록 지시합니다. 이 설정이 없으면, PostgreSQL이 준비되기 전에 pgAdmin이 먼저 시작되어 연결에 실패할 수 있습니다. 이는 PostgreSQL의 완전한 정상 상태까지 기다리는 것은 아니고, 컨테이너 시작만 보장합니다. 그래도 대부분의 레이스 컨디션을 피하기엔 충분합니다.

pgAdmin 4 환경 변수

필수 환경 변수는 두 가지입니다:

PGADMIN_DEFAULT_EMAIL - pgAdmin 웹 인터페이스에 로그인할 때 사용할 이메일 주소
PGADMIN_DEFAULT_PASSWORD - 해당 계정의 비밀번호

세 번째는 선택이지만 지정하는 것이 좋습니다:

PGADMIN_LISTEN_PORT - 컨테이너 내부에서 pgAdmin이 수신하는 포트입니다. 기본값은 80이지만, 포트 매핑 시 5050으로 설정하면 더 깔끔합니다.

다만 Compose 파일에 자격 증명을 하드코딩하는 건 좋지 않습니다. 특히 파일을 버전 관리에 넣는 경우 더 위험합니다. 대신 .env 파일로 옮기세요.

docker-compose.yml과 같은 디렉터리에 .env 파일을 만드세요:

POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=secret

그리고 Compose 파일에서 변수를 참조하세요:

# postgres
environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}
  
# pgadmin
environment:
  PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
  PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}

Docker Compose는 명령 실행 시 .env 파일을 자동으로 읽으므로 추가 설정이 필요 없습니다. .gitignore에 .env를 반드시 추가해 자격 증명이 저장소에 들어가지 않도록 하세요.

볼륨과 데이터 영속성

/var/lib/pgadmin에 매핑된 볼륨은 세션 데이터, 저장된 서버 연결, 설정 등 pgAdmin 데이터가 저장되는 위치입니다. Compose 파일에서 이를 제거하면 컨테이너가 재시작될 때마다 모든 데이터를 잃게 됩니다.

현재 Compose 파일에서는 호스트 머신에서 Docker가 관리하는 명명된 볼륨을 사용합니다. 데이터를 명시적으로 docker volume rm으로 삭제하지 않는 한, 컨테이너 재시작, 재생성, 이미지 업데이트 후에도 데이터는 유지됩니다.

스택 시작 및 pgAdmin 4 접속

docker-compose.yml이 준비되면, 스택 시작은 명령 하나면 됩니다:

docker compose up -d

-d 플래그는 두 컨테이너를 분리 모드로 실행합니다. 백그라운드에서 시작하고 터미널은 계속 사용할 수 있습니다. 두 컨테이너가 실행 중인지 확인하려면:

docker ps

postgres와 pgadmin 둘 다 Up 상태로 표시되어야 합니다.

컨테이너 상태

이상이 보인다면 pgAdmin 로그를 확인하세요:

docker logs pgadmin

정상 시작은 아래처럼 보입니다:

pgAdmin 시작 로그

여기서 오류가 보인다면, 보통 다음 세 가지 중 하나입니다:

비밀번호 인증 실패: .env 파일의 PGADMIN_DEFAULT_PASSWORD가 누락되었거나 형식이 잘못됨
포트가 이미 할당됨: 5050 포트에서 다른 것이 실행 중임; Compose 파일에서 호스트 포트를 변경
그런 파일이나 디렉터리가 없음: 볼륨 경로가 잘못되었거나 컨테이너에 쓰기 권한이 없음

두 컨테이너가 올라가고 로그에 이상이 없다면 브라우저에서 http://localhost:5050으로 이동하세요:

pgAdmin 로그인 페이지

PGADMIN_DEFAULT_EMAIL과 PGADMIN_DEFAULT_PASSWORD에 설정한 이메일과 비밀번호로 로그인하세요. 그러면 pgAdmin 대시보드로 이동하며, 이제 PostgreSQL 서버를 등록할 수 있습니다:

pgAdmin 홈

pgAdmin 4를 PostgreSQL 컨테이너에 연결하기

pgAdmin 사이드바에서 Servers를 우클릭 - Register - Server를 선택하세요. General과 Connection 두 탭을 채우면 됩니다.

General 탭

서버에 의미 있는 이름을 지정하세요. 예: local-dev-postgres. 이는 pgAdmin 내부에서 보이는 라벨일 뿐이므로, 본인 환경에 맞게 정하면 됩니다.

서버 등록 - General 탭

Connection 탭

여기서는 localhost를 사용하지 마세요.

Docker 네트워크 내부에서 localhost는 해당 컨테이너 자체를 가리킵니다. 호스트 머신이나 PostgreSQL 컨테이너가 아닙니다. Docker에는 자체 내부 DNS가 있어 docker-compose.yml에 정의된 서비스 이름으로 컨테이너 이름을 해석합니다. 따라서 PostgreSQL 서비스 이름이 postgres라면, 그게 사용할 호스트명입니다.

다음과 같이 입력하세요:

Host name/address: postgres (docker-compose.yml의 서비스 이름)
Port: 5432
Maintenance database: Compose 파일의 POSTGRES_DB 값 (예: mydb)
Username: POSTGRES_USER 값 (예: admin)
Password: POSTGRES_PASSWORD 값

Save를 클릭합니다.

서버 등록 - Connection 탭

모두 올바르게 입력했다면, 사이드바에 서버가 표시되고 데이터베이스를 펼쳐 볼 수 있습니다.

서버 등록 성공

이제 연결된 것입니다.

Query Tool 사용하기

이제 연결되었으니, pgAdmin 4와 일반적인 Postgres 사용의 기초를 살펴보겠습니다.

상단 메뉴에서 Tools - Query Tool을 클릭해 Query Tool을 엽니다. 인터페이스는 세 개의 패널로 구성됩니다:

Editor: SQL을 작성하는 영역
Data Output: 쿼리 실행 후 결과가 표시되는 영역
Messages: PostgreSQL이 상태 메시지, 오류, 실행 정보를 보내는 영역

Query tool

SQL 작성 및 실행

간단한 orders 테이블을 만들고 데이터를 추가해 보겠습니다. 각 블록은 재생 버튼을 누르거나 단축키 F5로 실행할 수 있습니다.

테이블 생성:

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    product VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    order_date DATE DEFAULT CURRENT_DATE
);

몇 개의 행을 삽입:

INSERT INTO orders (customer_name, product, quantity)
VALUES
    ('Alice Johnson', 'Wireless Keyboard', 2),
    ('Bob Smith', 'USB-C Hub', 1),
    ('Carol White', 'Mechanical Keyboard', 3);

이제 데이터를 조회합니다:

SELECT * FROM orders;

데이터 조회

결과는 Data Output 패널에 표 형태로 표시됩니다. 열을 정렬하고 크기를 조정하며, 그리드에서 행을 직접 복사할 수 있습니다.

시각적 쿼리 플랜 읽기

쿼리 실행 시 내부에서 무엇이 일어나는지 보려면, SELECT 문에 EXPLAIN ANALYZE를 실행하세요:

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_name = 'Alice Johnson';

Explain Analyze 결과

Data Output 패널에는 원시 출력이 표시됩니다. 하지만 pgAdmin에는 더 좋은 옵션이 있습니다. 툴바에서 Explain 버튼을 클릭하면 pgAdmin이 쿼리 플랜을 대화형 그래프로 렌더링합니다.

그래프로 표시된 쿼리 플랜

이번 예시는 단순하지만, 테이블 조인이나 복잡한 집계를 수행할 때는 훨씬 많은 정보를 얻을 수 있습니다.

이는 중요합니다. 원시 EXPLAIN 출력을 읽는 일은 느리고 오류가 생기기 쉽습니다. 시각적 플랜을 보면 PostgreSQL이 큰 테이블에서 전체 스캔을 하는지, 인덱스가 있음에도 사용하지 않는지 등을 한눈에 파악할 수 있습니다.

데이터베이스 스키마 관리

pgAdmin의 사이드바는 데이터베이스 구조를 전체적으로 보여주며, GUI를 통해 수정할 수도 있습니다.

사이드바 트리는 Servers - 서버 이름 - Databases - 데이터베이스 - Schemas - public - Tables 순서입니다. 테이블을 확장하면 Columns, Indexes, Constraints가 하위 노드로 표시됩니다. 각각을 클릭하면 오른쪽 패널에서 세부 정보를 확인할 수 있습니다.

테이블 생성 및 수정

새 테이블을 만들려면 스키마 아래의 Tables를 우클릭하고 Create - Table을 선택하세요. 몇 개의 탭이 있는 대화 상자가 열립니다.

테이블 생성

General 탭에서 테이블 이름을 지정합니다. Columns 탭으로 전환해 열을 추가하세요. 각 행에서 열 이름, 데이터 타입, 길이, NULL 허용 여부를 설정할 수 있습니다. Constraints 탭에서는 기본 키, 외래 키, 고유 제약을 설정합니다.

기존 테이블에 인덱스를 추가하려면 사이드바에서 해당 테이블을 확장하고 Indexes를 우클릭한 뒤 Create - Index를 선택하세요. 인덱싱할 열을 고르고 인덱스 타입을 선택합니다. 기본값 btree는 대부분의 경우 잘 작동합니다.

인덱스 생성

백업과 복원

데이터베이스를 백업하려면 Tools - Backup으로 이동하세요. 형식을 선택해야 합니다:

Custom: 압축된 바이너리 형식으로 가장 유연합니다. 전체가 아닌 개별 테이블을 복원할 수 있어 대부분의 경우 최선의 선택입니다.
Plain: 일반 SQL 스크립트로, 어떤 텍스트 편집기로도 열어 읽을 수 있습니다.
Tar: 압축되지 않은 아카이브로, 덜 일반적이지만 일부 복원 워크플로에서 유용합니다.

형식과 저장 경로를 선택하면, pgAdmin이 백그라운드에서 pg_dump를 실행해 파일을 로컬 머신에 저장합니다.

백업 생성

복원하려면 Tools - Restore로 이동해 백업 파일을 선택하고 대상 데이터베이스를 지정하세요.

백업에서 복원

이 기능이 왜 유용한지 궁금하다면, 개발 데이터베이스에서 파괴적 마이그레이션을 테스트하는 상황을 떠올려 보세요. 먼저 백업을 수행하고 마이그레이션을 실행합니다. 문제가 생기면 백업을 복원해 안정적인 상태로 되돌릴 수 있습니다.

Docker에서 pgAdmin 4를 운영할 때의 모범 사례

pgAdmin 4를 실행하는 것과 원활하게 운영하는 것은 별개의 일입니다. 알아두면 좋은 몇 가지 팁을 소개합니다.

자격 증명은 Compose 파일에서 분리하세요

docker-compose.yml이 버전 관리에 들어가면(대개 그렇습니다) 하드코딩된 비밀번호도 함께 갑니다. 자격 증명은 .env 파일로 분리하고 .gitignore에 추가하세요. 운영 환경에서는 한 단계 더 나아가 Docker secrets를 사용해 민감한 값을 환경 변수가 아닌 파일로 마운트하세요.

pgAdmin 포트를 공용으로 노출하지 마세요

기본적으로 Docker는 포트를 0.0.0.0에 바인딩합니다. 이는 모든 네트워크 인터페이스(공용 포함)를 의미합니다. 원격 서버에서는 pgAdmin 인스턴스가 인터넷에서 접근 가능해집니다. 대신 127.0.0.1에 명시적으로 바인딩하세요:

ports:
  - "127.0.0.1:5050:5050"

이렇게 하면 서버 자체에서만 pgAdmin에 접근할 수 있습니다. 원격 접근이 필요하면 SSH 터널이나 인증이 적용된 리버스 프록시를 사용하세요.

이미지 태그를 고정하세요

dpage/pgadmin4:latest를 사용하면 누군가 docker compose pull을 실행할 때마다 새 버전을 가져옵니다. 새 버전은 동작이 달라지거나 설정이 깨지거나 예상치 못한 변경을 도입할 수 있습니다. dpage/pgadmin4:9.13처럼 구체적인 태그를 사용해 팀원 모두가 정확히 같은 버전을 실행하도록 하세요.

`servers.json`으로 서버 연결을 미리 로드하세요

팀 전체가 같은 Compose 설정을 공유한다면, 스택을 올린 뒤 매번 PostgreSQL 서버를 수동 등록하게 만들지 마세요. pgAdmin은 시작 시 연결을 미리 채워 넣는 servers.json을 지원합니다. 컨테이너에 다음과 같이 마운트하세요:

volumes:
  - ./servers.json:/pgadmin4/servers.json

최소한의 servers.json 예시는 다음과 같습니다:

{
  "Servers": {
    "1": {
      "Name": "local-dev-postgres",
      "Group": "Servers",
      "Host": "postgres",
      "Port": 5432,
      "MaintenanceDB": "mydb",
      "Username": "admin",
      "SSLMode": "prefer"
    }
  }
}

pgAdmin이 시작될 때 서버가 자동으로 표시되어 수동 설정이 필요 없습니다.

결론

이 글에서는 처음부터 Docker에서 pgAdmin 4를 설정하는 과정을 안내했습니다. PostgreSQL과 pgAdmin 4를 함께 올리는 Docker Compose 파일을 작성하고, Docker의 내부 DNS를 사용해 두 컨테이너를 연결했으며, pgAdmin의 핵심 기능인 Query Tool, 스키마 브라우저, 백업/복원 워크플로를 사용했습니다.

핵심 원칙은 재현성입니다.

docker-compose.yml, servers.json, .env 파일만 있으면 팀원에게 완전히 구성된 데이터베이스 환경을 제공할 수 있습니다. 이렇게 하면 “내 컴퓨터에서는 되는데”라는 문제가 다시는 벌어지지 않습니다.

Docker와 컨테이너화에 대해 더 깊이 배우려면 Intermediate Docker 과정을 확인하세요. 멀티 스테이지 빌드, 네트워킹, Compose 심화 등 유용한 팁이 가득합니다.