PostgreSQL] 최대 동시 접속자 수를 초과

에러 메시지:

HHH000342: Could not obtain connection to query metadata  
org.postgresql.util.PSQLException: 치명적오류: 최대 동시 접속자 수를 초과했습니다.

는 PostgreSQL 데이터베이스의 최대 연결 수(max_connections)를 초과해서 더 이상 연결을 할 수 없는 상태를 의미합니다. 이는 Spring 애플리케이션 또는 다른 클라이언트들이 너무 많은 커넥션을 열어두고 있거나, 커넥션을 제대로 닫지 않아서 발생합니다.

---

✅ 원인 요약

1. PostgreSQL 서버의 max_connections 제한 초과
   • 기본값은 보통 100개.
2. Spring Boot 애플리케이션에서 너무 많은 커넥션을 생성하거나 풀에 반납하지 않음
   • HikariCP 기본 설정은 10개인데, 여러 인스턴스에서 동시에 접속하면 초과 가능.
3. 커넥션 누수
   • 예외 처리 누락, @Transactional 미적용, EntityManager 수동 사용 시 반납 실패 등.
4. 다른 애플리케이션 또는 외부 클라이언트(PostGIS, pgAdmin, ETL 툴 등)의 연결 남발

---

✅ 해결 방법

1. PostgreSQL의 max_connections 수 늘리기

SHOW max_connections;

변경하려면 postgresql.conf 설정:

max_connections = 200  # 예: 200개로 증가

⚠️ 서버 재시작 필요
단, 이 방법은 임시적이며, 애플리케이션 측의 커넥션 관리가 제대로 안 되면 또 초과됩니다.

---

2. Spring Boot - 커넥션 풀 설정 제한하기 (HikariCP)

application.yml 또는 application.properties:

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      idle-timeout: 30000
      max-lifetime: 1800000
      connection-timeout: 30000

혹은 .properties 형식:

spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.idle-timeout=30000
spring.datasource.hikari.max-lifetime=1800000
spring.datasource.hikari.connection-timeout=30000

---

3. 커넥션 누수 감지

• @Transactional 빠짐 없이 적용
• DataSource 또는 JdbcTemplate 수동 관리 시 Connection 을 명확히 close()
• 커넥션 누수 탐지를 위한 설정:

spring:
  datasource:
    hikari:
      leak-detection-threshold: 2000  # 2초 이상 반납되지 않으면 로그 출력

---

4. PostgreSQL의 현재 접속 확인 및 종료

SELECT pid, usename, client_addr, backend_start, state 
FROM pg_stat_activity 
WHERE datname = 'your_database_name';

특정 커넥션 종료:

SELECT pg_terminate_backend(pid) 
FROM pg_stat_activity 
WHERE datname = 'your_database_name' AND state = 'idle';

⚠️ 주의: 운영 환경에서는 중요한 연결을 끊지 않도록 주의!

---

✅ 요약 체크리스트

조치 설명

max_connections 확인/확장	PostgreSQL 서버 설정 확인
HikariCP 제한 설정	maximum-pool-size 조정
커넥션 누수 방지	@Transactional, close() 철저
커넥션 감지 활성화	leak-detection-threshold 설정
불필요 연결 종료	pg_stat_activity 통해 점검

---

필요하다면 커넥션 풀 모니터링 방식(HikariCP MBeans, actuator, etc.)이나, 커넥션 풀을 줄이면서 효율성 유지하는 전략도 추가로 설명드릴 수 있습니다.