Skip to main content

pgAdmin

20+ 프로젝트의 PostgreSQL을 단일 웹 UI에서 통합 관리하는 도구입니다.

개요​

항목내용
위치workspace/_devtools/pgadmin/
용도모든 프로젝트의 PostgreSQL 통합 관리 (쿼리/백업/사용자)
기반 이미지dpage/pgadmin4
포트7050
어드민 도메인db.devtools.codebase.how (🔒 Tailscale 제한)
랜딩 도메인db.codebase.how (🌐 공개 소개)

주요 기능​

  • 다중 서버 등록 — 20+ PostgreSQL 인스턴스 트리 구조로 관리
  • SQL 에디터 — 쿼리 작성/실행/결과 내보내기 (CSV, JSON)
  • ERD 다이어그램 — 스키마 시각화
  • 백업/복원 — pg_dump / pg_restore GUI
  • 사용자/권한 관리 — Role, Grant, RLS 확인
  • Explain Visual — 쿼리 플랜 시각화

시작하기​

make up NAME=_devtools/pgadmin
make status NAME=_devtools/pgadmin
make logs NAME=_devtools/pgadmin

접속​

용도URL비고
운영 어드민https://db.devtools.codebase.howTailscale 내부망
운영 랜딩https://db.codebase.how공개 소개
로컬 개발http://localhost:7050직접 포트 접근

첫 로그인​

  • Email/Password: .env의 PGADMIN_DEFAULT_EMAIL / PGADMIN_DEFAULT_PASSWORD
  • 첫 로그인 후 Master Password 설정 (서버 연결 정보 암호화에 사용)

서버 등록 (자동 설정)​

pgAdmin은 servers.json을 통해 컨테이너 시작 시 자동으로 서버를 등록할 수 있습니다.

servers.json 예시​

{
  "Servers": {
    "1": {
      "Name": "demo.codebase.how",
      "Group": "Codebase Projects",
      "Host": "msk-demo-postgres",
      "Port": 5432,
      "MaintenanceDB": "postgres",
      "Username": "postgres",
      "SSLMode": "prefer"
    },
    "2": {
      "Name": "quant.how",
      "Group": "Codebase Projects",
      "Host": "msk-quant-how-postgres",
      "Port": 5432,
      "Username": "postgres"
    }
  }
}

각 프로젝트의 PostgreSQL 컨테이너 이름을 Host에 지정하면 Docker DNS가 shared-network 내에서 자동 해석합니다.

네트워크 구성​

┌────────────────────────────────────────────────┐
│  ${PLATFORM_NAME}-shared-network               │
│                                                │
│  msk-pgadmin                                   │
│       │                                        │
│       ├──▶ msk-demo-postgres:5432              │
│       ├──▶ msk-quant-how-postgres:5432         │
│       ├──▶ msk-apis-how-postgres:5432          │
│       └──▶ ... (20+ 프로젝트)                   │
└────────────────────────────────────────────────┘

권한 설정​

pgAdmin 컨테이너는 UID 5050으로 실행됩니다. 호스트 볼륨 마운트 시 권한 주의:

sudo chown -R 5050:5050 data/pgadmin/

Makefile이 자동으로 권한을 체크하고 안내합니다.

환경변수 (.env)​

DEVTOOLS_PGADMIN_PORT=7050
PLATFORM_DB_ADMIN_URL=https://db.devtools.codebase.how
PLATFORM_DB_URL=https://db.codebase.how

PGADMIN_DEFAULT_EMAIL=admin@codebase.how
PGADMIN_DEFAULT_PASSWORD=...
PGADMIN_CONFIG_SERVER_MODE=False

보안​

항목설정
어드민 URL 접근NPM Access List — Tailscale 100.64.0.0/10 IP만 허용
로그인pgAdmin 자체 인증 + Master Password (이중 보호)
서버 비밀번호Master Password로 AES 암호화 저장
외부 노출 금지

db.devtools.codebase.how는 반드시 NPM Access List + Tailscale IP 제한을 적용하세요. pgAdmin에는 모든 프로젝트의 DB 비밀번호가 저장됩니다.

주요 사용 시나리오​

1. SQL 쿼리 실행​

좌측 트리 → 프로젝트 → Databases → 스키마 → Tables → 우클릭 → Query Tool → SQL 실행

2. 백업​

Database 우클릭 → Backup → 포맷 선택 (plain/custom) → 경로 지정 → pg_dump 실행

3. ERD 보기​

Database 우클릭 → ERD For Database → 시각화된 스키마 다이어그램

4. RLS 정책 확인​

Schemas → public → Policies → 각 테이블의 Row Level Security 정책 조회

5. Explain Visual​

쿼리 탭 → 쿼리 입력 → F7 (Explain) 또는 Shift+F7 (Explain Analyze) → 시각적 플랜 트리로 병목 파악

자주 묻는 질문​

Q. 서버 목록이 나타나지 않습니다.​

A. servers.json은 컨테이너 첫 시작 시에만 로드됩니다. 이미 실행된 컨테이너에 반영하려면:

make down NAME=_devtools/pgadmin
make up NAME=_devtools/pgadmin

Q. 특정 프로젝트 DB 연결이 실패합니다.​

A. 해당 PostgreSQL 컨테이너가 shared-network에 속해있는지 확인:

docker network inspect ${PLATFORM_NAME}-shared-network | grep msk-{project}-postgres

없으면 프로젝트 _docker/docker-compose.*.yml의 postgres 서비스에 networks 추가:

postgres:
  networks:
    - default
    - shared

관련 문서​