pgAdmin으로 PostgreSQL 데이터베이스 시각화하기

pgAdmin을 개발 스택에 추가하고, 팀원들이 PostgreSQL 데이터베이스를 최대한 쉽게 탐색할 수 있게 만드는 방법을 살펴볼게요.

출처: 문서

본문

많은 어플리케이션이 스택에서 PostgreSQL 데이터베이스를 사용해요. 하지만 모든 개발자가 PostgreSQL 데이터베이스를 탐색하고 작업하는 데 능숙한 건 아니에요.

다행히 개발에 컨테이너를 사용하면 트러블슈팅과 디버깅을 돕는 추가 서비스를 쉽게 붙일 수 있어요.

pgAdmin 도구는 PostgreSQL 데이터베이스를 관리하고 시각화하는 데 도움을 주는 인기 있는 오픈소스 도구예요.

이 가이드에서 배울 내용:

pgAdmin을 어플리케이션 스택에 추가하기
pgAdmin이 개발 데이터베이스에 자동으로 연결되도록 구성하기

pgAdmin을 스택에 추가하기

compose.yaml 파일에서 기존 postgres 서비스 옆에 pgadmin 서비스를 추가해주세요:

services:
  postgres:
    image: postgres:18
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: demo
  pgadmin:
    image: dpage/pgadmin4:9.8
    ports:
      - 5050:80
    environment:
      # Required by pgAdmin
      PGADMIN_DEFAULT_EMAIL: [email protected]
      PGADMIN_DEFAULT_PASSWORD: secret
      # Don't require the user to login
      PGADMIN_CONFIG_SERVER_MODE: 'False'
      # Don't require a "master" password after logging in
      PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: 'False'

다음 명령으로 Compose 스택을 시작해주세요:

$ docker compose up

이미지가 다운로드되고 컨테이너가 시작되면, pgAdmin이 준비됐다는 다음처럼 생긴 출력을 볼 수 있어요:

pgadmin-1 | [2025-09-22 15:52:47 +0000] [1] [INFO] Starting gunicorn 23.0.0
pgadmin-1 | [2025-09-22 15:52:47 +0000] [1] [INFO] Listening at: http://[::]:80 (1)
pgadmin-1 | [2025-09-22 15:52:47 +0000] [1] [INFO] Using worker: gthread
pgadmin-1 | [2025-09-22 15:52:47 +0000] [119] [INFO] Booting worker with pid: 119

http://localhost:5050 으로 가서 pgAdmin을 열어주세요.

관리 패널에 들어가면 Add New Server 링크를 선택해 새 서버를 정의해주세요. 다음 세부사항을 입력해주세요:

General 탭:

Name: postgres

Connection 탭:

Host name/address: postgres
Username: postgres
Password: secret
Save password? 필드를 활성화해주세요

중요: 이 연결 세부사항은 이전 Compose 파일 스니펫을 사용한다고 가정해요. 기존 Compose 파일을 사용한다면 필요에 따라 연결 세부사항을 조정하세요. Host name/address 필드는 postgres 서비스의 이름과 일치해야 해요.

Save 버튼을 선택해 새 데이터베이스를 만들어주세요.

이제 pgAdmin이 설정되고 컨테이너화된 데이터베이스에 연결되었어요. 자유롭게 탐색하고, 테이블을 보고, 데이터베이스를 살펴보세요.

pgAdmin이 데이터베이스에 자동 연결되도록 구성하기

pgAdmin이 실행되고 있지만, 데이터베이스 연결을 구성할 필요 없이 간단히 앱을 열 수 있으면 좋겠죠. 설정 단계를 줄이면 팀원들이 이 도구의 가치를 쉽게 얻을 수 있어요.

다행히 데이터베이스에 자동 연결하는 기능이 있어요.

경고: 자동 연결하려면 데이터베이스 자격 증명이 평문 파일로 공유돼요. 로컬 개발 중에는 로컬 데이터가 실제 고객 데이터가 아니므로 종종 허용돼요. 하지만 프로덕션 또는 민감한 데이터를 사용한다면 이 관행은 강력히 권장되지 않아요.

먼저 서버 자체를 정의해야 하는데, pgAdmin은 servers.json 파일로 이를 수행해요.

servers.json 파일용 구성 파일을 정의하려면 compose.yaml 파일에 다음을 추가해주세요:

configs:
  pgadmin-servers:
    content: |
      {
        "Servers": {
          "1": {
            "Name": "Local Postgres",
            "Group": "Servers",
            "Host": "postgres",
            "Port": 5432,
            "MaintenanceDB": "postgres",
            "Username": "postgres",
            "PassFile": "/config/pgpass"
          }
        }
      }

servers.json 파일은 PassFile 필드를 정의하는데, 이는 PostgreSQL 패스워드 파일 을 가리켜요. 흔히 pgpass 파일이라고 불러요.

pgpass 파일을 정의하려면 compose.yaml 파일에 다음 구성을 추가해주세요:

configs:
  pgadmin-pgpass:
    content: |
      postgres:5432:*:postgres:secret

이것은 postgres:5432 에 대한 연결 요청으로 사용자 이름 postgres 를 사용하면 secret 이라는 비밀번호를 제공해야 함을 나타내요.

compose.yaml 에서 pgadmin 서비스를 업데이트해 구성 파일을 주입해주세요:

services:
  pgadmin:
    ...
    configs:
      - source: pgadmin-pgpass
        target: /config/pgpass
        uid: "5050"
        gid: "5050"
        mode: 0400
      - source: pgadmin-servers
        target: /pgadmin4/servers.json
        mode: 0444

docker compose up 을 다시 실행해 어플리케이션 스택을 업데이트해주세요:

$ docker compose up

어플리케이션이 재시작되면 브라우저에서 http://localhost:5050 을 열어주세요. 로그인이나 구성 없이도 데이터베이스에 접근할 수 있어야 해요.

결론

컨테이너를 사용하면 어플리케이션의 의존성을 실행할 뿐 아니라 트러블슈팅과 디버깅을 돕는 추가 도구도 쉽게 실행할 수 있어요.

도구를 추가할 때는 팀원들이 겪을 경험과 가능한 마찰을 생각하고, 어떻게 제거할 수 있을지 고민해보세요. 이 경우 데이터베이스를 자동으로 구성하고 연결하는 구성을 추가하는 한 단계를 더 해, 팀원들의 귀중한 시간을 아껴줬어요.

더 알아보기 (Learn more)

PostgreSQL 가이드
pgAdmin
Docker Compose