> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# PostgreSQL

오픈소스 관계형 데이터베이스(RDBMS)입니다. 테이블 형태로 데이터를 저장하고 SQL로 조회합니다.

## 어디에 쓰이나요?

* 사용자 정보, 게시글, 주문 내역 등 **구조화된 데이터**를 저장할 때
* Dify, Langfuse, n8n 등 대부분의 애플리케이션이 **기본 데이터베이스**로 사용
* 트랜잭션, 외래 키 등 **데이터 무결성**이 필요한 경우

<Note>
  이 가이드에서 다루는 Dify, Langfuse, Langflow, n8n 모두 내부적으로 PostgreSQL을 사용합니다. 각 서비스의 docker-compose.yml에 PostgreSQL이 포함되어 있으므로, 별도로 설치할 필요 없이 해당 서비스를 실행하면 됩니다.
</Note>

## Docker Compose

```yaml docker-compose.yml theme={null}
services:
  postgres:
    image: postgres:17
    container_name: postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
```

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

```bash theme={null}
docker exec -it postgres psql -U postgres
```

정상적으로 접속되면 `postgres=#` 프롬프트가 표시됩니다.

```sql theme={null}
SELECT version();
```

## 기본 정보

| 항목        | 값                 |
| --------- | ----------------- |
| 포트        | 5432              |
| 기본 사용자    | postgres          |
| 기본 비밀번호   | changeme          |
| 데이터 저장 경로 | postgres\_data 볼륨 |

## 환경 변수

| 변수                  | 설명           | 기본값                      |
| ------------------- | ------------ | ------------------------ |
| `POSTGRES_USER`     | 슈퍼유저 이름      | postgres                 |
| `POSTGRES_PASSWORD` | 슈퍼유저 비밀번호    | (필수)                     |
| `POSTGRES_DB`       | 기본 데이터베이스 이름 | POSTGRES\_USER 값         |
| `PGDATA`            | 데이터 디렉토리 경로  | /var/lib/postgresql/data |

## 라이선스

| 구분     | 내용                          |
| ------ | --------------------------- |
| 라이선스   | PostgreSQL License (BSD 계열) |
| 개인 사용  | 자유롭게 사용 가능                  |
| 상업적 사용 | 자유롭게 사용 가능, 수정/재배포 제한 없음    |

## 참고

* [Docker Hub - postgres](https://hub.docker.com/_/postgres)
* [PostgreSQL 공식 문서](https://www.postgresql.org/docs/)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Redis" icon="arrow-right" href="/stacks/redis">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>