PostgreSQL 데이터 소스 트러블슈팅

Grafana에서 PostgreSQL 데이터 소스를 사용할 때 겪을 수 있는 흔한 오류에 대한 트러블슈팅 정보를 정리한 문서예요. 연결, 인증, TLS/인증서, 데이터베이스, 쿼리, 성능, 프로비저닝 오류를 다룹니다.

출처: Troubleshoot PostgreSQL data source issues

본문

연결 오류 (Connection errors)

PostgreSQL에 연결 실패:

오류 메시지: failed to connect to <host>: connect: connection refused 또는 dial tcp: connect: connection refused

원인: Grafana가 PostgreSQL 서버와 네트워크 연결을 설정할 수 없음.

해결:

데이터 소스 구성의 Host URL이 올바른지 확인.
PostgreSQL이 실행 중이고 Grafana 서버에서 접근 가능한지 확인.
포트가 올바른지 확인(PostgreSQL 기본 포트는 5432).
연결을 차단하는 방화벽 규칙이 없는지 확인.
pg_hba.conf에서 PostgreSQL이 Grafana 서버로부터의 연결을 수락하도록 구성되어 있는지 확인.
Grafana Cloud라면 PostgreSQL 인스턴스가 공개적으로 접근 불가할 때 Private data source connect(P DC)를 구성했는지 확인.

Grafana Cloud가 사설 데이터베이스에 도달할 수 없음:

오류 메시지: dial tcp: connect: connection refused, i/o timeout, context deadline exceeded

원인: Grafana Cloud는 호스팅 환경에서 실행되며 localhost, 127.0.0.1, 사설 IP 범위(10.x, 172.16.x, 192.168.x)의 데이터베이스에 직접 도달할 수 없음. 이는 자체 관리 Grafana에서 Grafana Cloud로 마이그레이션할 때 가장 흔한 문제.

해결:

PDC(Private data source connect)를 설정해 Grafana Cloud와 사설 네트워크 사이 보안 터널 생성.
PostgreSQL 인스턴스에 네트워크 접근이 있는 머신에 PDC 에이전트 설치.
Docker 기반 PDC 에이전트로 간헐적 연결 끊김을 겪는다면 바이너리 기반 에이전트 시도(일부 환경에서 안정성 문제 해결).
데이터 소스 설정의 Host URL을 PDC 에이전트 네트워크에서 보이는 hostname(이상 localhost 아님)으로 업데이트.

요청 시간 초과 (Request timed out):

오류 메시지: "context deadline exceeded" 또는 "i/o timeout"

원인: 응답을 받기 전에 PostgreSQL 연결이 시간 초과됨.

해결: Grafana와 PostgreSQL 사이 네트워크 지연 확인. PostgreSQL이 과부하되거나 성능 문제가 없는지 확인. 데이터 소스 구성의 Connection limits 아래 Max lifetime 설정 증가. 쿼리 시간 범위나 복잡성 줄임. 로드 밸런서/프록시 같은 네트워크 장치가 연결을 시간 초과시키는지 확인.

호스트를 찾을 수 없음 (Host not found):

오류 메시지: failed to connect to <host>: hostname resolving error 또는 lookup hostname: no such host

원인: 데이터 소스 구성에 지정된 hostname을 해석할 수 없음.

해결: hostname 철자가 올바른지 확인. Grafana 서버에서 DNS 해석이 동작하는지 확인. hostname 대신 데이터베이스 공개 IP 주소 사용 시도(DNS 해석 진단에 유용). Grafana 서버 네트워크에서 PostgreSQL 서버에 접근 가능한지 확인. Grafana Cloud의 DNS 해석 동작은 스택 리전·클라우드 제공자마다 다를 수 있으므로, hostname이 한 스택에서는 해석되고 다른 스택에서는 안 되면 직접 IP를 시도하고 Grafana Support에 문의.

인증 오류 (Authentication errors)

PostgreSQL 사용자 이름 미지정:

오류 메시지: FATAL: no PostgreSQL user name specified in startup packet (SQLSTATE 28000)

원인: 사용자 이름 없이 연결 시도. 데이터 소스 구성의 Username 필드가 비어 있거나 지워졌기 때문.

해결: 데이터 소스 설정에서 Username 필드에 유효한 PostgreSQL 사용자가 있는지 확인. Save & test로 연결 성공 확인. 저장 후 사용자 이름이 사라지면 Grafana 버전 확인. fast release 채널의 Grafana v13.1 버그가 저장 시 사용자 이름 필드를 지워버림. 패치 릴리스로 업그레이드하거나 steady release 채널로 전환하면 해결.

비밀번호 인증 실패:

오류 메시지: failed to connect to <host>: server error: FATAL: password authentication failed for user "<username>" (SQLSTATE 28P01)

원인: 사용자 이름이나 비밀번호가 올바르지 않음.

해결: 데이터 소스 구성에서 사용자 이름/비밀번호가 올바른지 확인. PostgreSQL에 사용자가 존재하는지 확인. 비밀번호가 만료되지 않았는지 확인. 비밀번호가 지정되지 않았다면 PostgreSQL 비밀번호 파일이 구성되었는지 확인.

권한 거부 (Permission denied):

오류 메시지: ERROR: permission denied for table <table_name> 또는 ERROR: permission denied for schema <schema_name> (SQLSTATE 42501)

원인: 데이터베이스 사용자가 요청한 테이블/스키마에 접근 권한이 없음.

해결: 사용자가 필요한 테이블에 SELECT 권한이 있는지 확인. 필요 권한 부여:

GRANT USAGE ON SCHEMA schema_name TO grafanareader;
GRANT SELECT ON schema_name.table_name TO grafanareader;

사용자가 올바른 데이터베이스에 접근하는지 확인. search path가 테이블이 있는 스키마를 포함하는지 확인.

pg_hba.conf 항목 없음:

오류 메시지: failed to connect to <host>: server error: FATAL: no pg_hba.conf entry for host "<ip_address>", user "<username>", database "<database_name>" (SQLSTATE 28000)

원인: PostgreSQL이 Grafana 서버로부터 연결을 수락하도록 구성되지 않음.

해결: PostgreSQL 서버의 pg_hba.conf 편집. Grafana 서버로부터 연결을 허용하는 항목 추가:

host    database_name    username    grafana_ip/32    md5

SELECT pg_reload_conf();로 PostgreSQL 구성 재로드. SSL을 사용한다면 올바른 인증 방법(hostssl 등)을 지정했는지 확인.

TLS 및 인증서 오류

인증서 검증 실패:

오류 메시지: "x509: certificate signed by unknown authority" 또는 "certificate verify failed"

원인: Grafana가 PostgreSQL이 제시한 TLS 인증서를 검증할 수 없음.

해결: TLS/SSL Mode를 적절한 수준(require, verify-ca, verify-full)으로 설정. 자체 서명 인증서를 쓴다면 TLS/SSL Auth Details에 CA 인증서 추가. 인증서 체인이 완전하고 유효한지 확인. 인증서가 만료되지 않았는지 확인. 테스트용으로만 TLS/SSL Mode를 disable 설정(프로덕션 권장 안 함).

SSL 미지원:

오류 메시지: failed to connect to <host>: server refused TLS connection 또는 server does not support SSL

원인: PostgreSQL 서버가 SSL 연결용으로 구성되지 않았지만 데이터 소스가 SSL을 요구함.

해결: SSL이 필요 없으면 TLS/SSL Mode를 disable로 설정. 또는 postgresql.conf에서 ssl = on으로 PostgreSQL에 SSL 활성화. 서버가 유효한 SSL 인증서를 구성했는지 확인.

클라이언트 인증서 오류:

오류 메시지: "TLS: failed to find any PEM data in certificate input" 또는 "could not load client certificate"

원인: 클라이언트 인증서 또는 키가 유효하지 않거나 잘못 포맷됨.

해결: 인증서와 키가 PEM 형식인지 확인. 인증서 파일 경로가 올바르고 Grafana 프로세스가 읽을 수 있는지 확인. 인증서와 키가 일치하는지(같은 키 쌍) 확인. 인증서 콘텐츠를 사용한다면 헤더를 포함한 전체 인증서를 붙여 넣었는지 확인.

데이터베이스 오류 (Database errors)

데이터베이스가 존재하지 않음:

오류 메시지: failed to connect to <host>: server error: FATAL: database "<database_name>" does not exist (SQLSTATE 3D000)

원인: 지정된 데이터베이스 이름이 잘못되었거나 데이터베이스가 없음.

해결: 데이터 소스 구성의 데이터베이스 이름 확인. 데이터베이스 존재 확인(psql의 \l 또는 SELECT datname FROM pg_database;). 데이터베이스 이름은 대소문자 구분이므로 정확히 일치하는지 확인. 사용자가 데이터베이스 연결 권한이 있는지 확인.

릴레이션 존재하지 않음:

오류 메시지: ERROR: relation "<table_name>" does not exist (SQLSTATE 42P01)

원인: 지정된 테이블/뷰가 없거나 사용자가 접근할 수 없음.

해결: 테이블 이름이 올바르고 존재하는지 확인. 테이블이 public 스키마에 없으면 스키마 이름 확인. schema_name.table_name처럼 정규화된 이름 사용. 사용자에게 테이블 SELECT 권한 확인. SHOW search_path;로 search path 확인.

쿼리 오류 (Query errors)

문자열 리터럴의 이중 대시로 쿼리 잘림:

오류 메시지: 문자열 값에 --(이중 대시)가 있을 때 예상치 못한 문법 오류 또는 잘린 결과.

원인: 이전 Grafana 버전에서 SQL 주석 제거 파서가 단일 따옴표 문자열 안의 --를 올바르게 처리하지 못함. WHERE name = 'value--suffix' 같은 쿼리가 --에서 잘려 나머지가 조용히 버려짐. 연속 하이픈 문자열에도 영향. PR #121772에서 따옴표 인식 주석 제거 파서로 수정됨(PostgreSQL 달러 따옴표 문자열 $$...$$도 처리). Grafana 13.1+, 13.0.2+, 12.1.11, 12.2.9, 12.3.7, 12.4.3에서 사용 가능.

해결: 수정이 포함된 Grafana 릴리스로 업그레이드(13.1+, 13.0.2+, 위 12.x 패치 릴리스). 즉시 업그레이드할 수 없다면 PostgreSQL 문자열 연결로 리터럴 --를 피해 해결:

WHERE name = 'value' || '--' || 'suffix'

또는 값에 템플릿 변수를 사용한 파라미터화 방식 사용.

쿼리 문법 오류:

오류 메시지: ERROR: syntax error at or near "<keyword>" (SQLSTATE 42601)

원인: SQL 쿼리에 유효하지 않은 문법 포함.

해결: 쿼리 문법의 오타나 유효하지 않은 키워드 확인. 특수 문자나 예약어를 포함한 열·테이블 이름이 올바르게 따옴표 처리되었는지 확인. 식별자에 이중 따옴표 사용: "column_name". psql 같은 PostgreSQL 클라이언트에서 직접 쿼리 테스트.

열이 존재하지 않음:

오류 메시지: ERROR: column "<column_name>" does not exist (SQLSTATE 42703)

원인: 지정된 열 이름이 잘못되었거나 테이블에 없음.

해결: 열 이름 철자가 올바른지 확인. PostgreSQL에서 따옴표 처리된 열 이름은 대소문자 구분. 대소문자 구분 이름에는 올바른 따옴표 사용("Column_Name"). psql의 \d table_name으로 열 존재 확인.

시간(시간) 열을 찾지 못함:

오류 메시지: "no time column found" 또는 시계열 시각화가 데이터 표시 안 함.

원인: 쿼리 결과가 제대로 포맷된 시간 열을 포함하지 않음.

해결: 쿼리가 타임스탬프나 epoch 값을 반환하는 time이라는 이름의 열을 포함하는지 확인. 시간 열 이름을 바꾸려면 별칭 사용(SELECT created_at AS time). 시간 열이 timestamp, timestamptz, 또는 숫자 epoch 값 유형인지 확인. 시간 열로 결과 정렬: ORDER BY time ASC.

매크로 확장 오류:

오류 메시지: "macro '$__timeFilter' not found" 또는 매크로로 잘못된 쿼리 결과.

원인: Grafana 매크로가 제대로 확장되지 않음.

해결: 매크로 문법이 올바른지 확인(예: $__timeFilter(time_column)). 매크로에 전달된 열 이름이 테이블에 존재하는지 확인. 매크로가 SQL 주석(-- 또는 /* */) 안에 없는지 확인. Grafana는 매크로 확장 전에 주석을 제거하므로 주석 안의 매크로는 조용히 무시됨. Builder 모드에서 Preview 토글로 확장된 쿼리 확인. Query inspector로 매크로 확장 후 PostgreSQL에 보내진 정확한 SQL 확인. 시간 기반 매크로는 열이 timestamp 데이터를 포함하는지 확인.

성능 문제 (Performance issues)

쿼리 시간 초과:

오류 메시지: "canceling statement due to statement timeout" 또는 "query timeout"

원인: 쿼리가 구성된 시간 초과보다 오래 걸림.

해결: 쿼리 시간 범위 줄임. WHERE 절과 조인의 열에 인덱스 추가. $__timeFilter 매크로로 데이터를 대시보드 시간 범위로 제한. 관리자 권한이 있으면 PostgreSQL의 statement timeout 증가. 쿼리 복잡성 최적화.

너무 많은 연결 (Too many connections):

오류 메시지: failed to connect to <host>: server error: FATAL: too many connections for role "<username>" (SQLSTATE 53300) 또는 connection pool exhausted

원인: PostgreSQL 최대 연결 수에 도달.

해결: 데이터 소스 구성에서 Max open connections 설정 줄임. 관리자 권한이 있으면 postgresql.conf의 max_connections 증가. 같은 데이터베이스에 연결하는 다른 애플리케이션의 연결 누수 확인. Auto max idle 활성화로 유휴 연결 자동 관리.

느린 쿼리 성능:

해결: 쿼리 시간 범위 줄임. 테이블에 적절한 인덱스 추가. $__timeFilter 매크로로 스캔되는 데이터 제한. Min time interval 설정 증가로 데이터 포인트 수 줄임. PostgreSQL에서 EXPLAIN ANALYZE로 쿼리 병목 식별. 복잡한 집계에 materialized view 고려.

프로비저닝 오류 (Provisioning errors)

잘못된 프로비저닝 구성:

오류 메시지: "metric request error" 또는 프로비저닝 후 데이터 소스 테스트 실패.

원인: 프로비저닝 YAML 파일에 잘못된 구성 포함.

해결: 파라미터 이름이 예상 형식과 정확히 일치하는지 확인. URL에 데이터베이스 이름이 포함되지 않았는지 확인. URL 형식은 hostname:port 사용. YAML 파일에서 문자열 값이 올바르게 따옴표 처리되었는지 확인. 올바른 형식은 프로비저닝 예시 참고.

예시 올바른 구성:

datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    user: grafana
    secureJsonData:
      password: 'Password!'
    jsonData:
      database: grafana
      sslmode: 'disable'

기타 흔한 문제

빈 쿼리 결과: 쿼리가 데이터를 반환하지 않음. 시간 범위에 데이터가 있는지, 테이블·열 이름이 올바른지, 필터가 모든 데이터를 제외하지 않는지 확인. $__timeFilter 매크로가 올바른 시간 열을 사용하는지 확인.

TimescaleDB 함수 사용 불가: 쿼리 빌더에서 time_bucket 같은 TimescaleDB 특정 함수를 사용할 수 없음. 데이터 소스 구성의 PostgreSQL Options 아래 TimescaleDB 토글 활성화. PostgreSQL 데이터베이스에 TimescaleDB가 설치·활성화되었는지 확인. CREATE EXTENSION IF NOT EXISTS timescaledb;로 확장 생성 확인.

데이터가 지연되거나 최근 지점 누락: 시각화가 가장 최근 데이터를 표시하지 않음. 대시보드 시간 범위와 새로고침 설정 확인. Min time interval이 너무 높지 않은지 확인. 데이터가 데이터베이스에 커밋되었는지(미커밋 트랜잭션 아님) 확인. Grafana와 PostgreSQL 사이 클록 동기화 문제 확인.

추가 도움 (Get additional help)

PostgreSQL 문서에서 데이터베이스별 지침, Grafana 커뮤니티 포럼에서 유사 문제를 확인해요. Cloud Pro, Cloud Contracted, Enterprise 사용자라면 Grafana Support에 문의해요. 이슈 보고 시 Grafana 버전, PostgreSQL 버전, 오류 메시지(민감 정보 redact), 재현 단계, 관련 구성(데이터 소스 설정, TLS 모드, 연결 제한 — 비밀번호·자격 증명 redact)을 포함하세요.

PostgreSQL 데이터 소스 트러블슈팅