본문으로 건너뛰기

linkding 및 PostgreSQL 연결 슬롯 부족 문제 해결

등록일: 2026. 4. 6.

linkding 및 PostgreSQL 연결 오류 분석 및 해결 가이드

1. 에러 현상 분석​

  • 핵심 오류: django.db.utils.OperationalError: connection failed: ... remaining connection slots are reserved for non-replication superuser connections
  • 원인: PostgreSQL의 최대 동시 접속 수(max_connections)가 한계치에 도달하여 일반 사용자의 신규 연결이 거부됨.
  • 부차적 오류: psycopg.OperationalError: could not open certificate file "/root/.postgresql/postgresql.crt": Permission denied
    • PostgreSQL 연결 시 SSL 인증서 확인을 시도하지만 권한 문제로 실패함.

2. 실시간 진단 및 원인 파악 (SQL)​

PostgreSQL 서버에 접속하여 현재 연결 상태를 점검함.

-- 1. 현재 상태별 커넥션 개수 확인
SELECT count(*), state FROM pg_stat_activity GROUP BY state;

-- 2. 현재 활성 상태인 쿼리 및 소스 IP 확인 (범인 검거)
SELECT pid, datname, usename, client_addr, state, query 
FROM pg_stat_activity 
WHERE state != 'idle';

-- 3. 특정 DB의 연결을 강제로 종료해야 할 경우 (응급처치)
SELECT pg_terminate_backend(pid) 
FROM pg_stat_activity 
WHERE datname = 'linkding_db_name' AND pid <> pg_backend_pid();

3. 해결 방안​

A. PostgreSQL 설정 변경 (Host OS 직접 설치 시)​

설정 파일의 최대 연결 수를 늘리고 서비스를 재시작함.

  1. 설정 파일 위치 확인: 보통 /etc/postgresql/[version]/main/postgresql.conf
  2. 설정 수정: 
    sudo nano /etc/postgresql/16/main/postgresql.conf
    • max_connections = 200 (기본값 100에서 상향)
  3. 서비스 재시작: 
    sudo systemctl restart postgresql

B. linkding SSL 설정 비활성화​

로그에 나타난 Permission denied 인증서 에러를 방지하기 위해 SSL 모드를 명시적으로 끔.

  • docker-compose.yml 환경변수에 추가: 
    environment:
      - LD_DB_SSLMODE=disable

4. 근본적인 예방 조치 (토이 프로젝트 관리)​

혼자 쓰는 시스템에서 연결 슬롯이 부족한 것은 Connection Leak 또는 Pool 설정 과다일 가능성이 큼.

  1. 커넥션 풀 사이즈 조정:
    • 각 토이 프로젝트(Spring Boot, Node.js 등)의 maximumPoolSize를 5~10 정도로 낮게 설정함.
    • 기본값이 30~50일 경우, 프로젝트 몇 개만 띄워도 100개를 금방 소진함.
  2. 유휴 커넥션 정리:
    • postgresql.conf에서 idle_in_transaction_session_timeout 설정을 추가하여 장시간 점유 중인 세션을 자동 종료함 (예: 5min).
  3. Docker Health Check 최적화:
    • 도커의 헬스체크 주기가 너무 짧고 매번 DB 연결을 확인한다면 주기를 늘리거나 로직을 단순화함.