n8n DB 커넥터 타임아웃 에러 해결: MySQL, PostgreSQL 사례

n8n DB 커넥터 타임아웃 에러 해결: MySQL, PostgreSQL 사례

n8n으로 자동화 워크플로우를 구성할 때 가장 골치 아픈 문제 중 하나가 바로 DB 커넥터 타임아웃 에러입니다. 특히 MySQL과 PostgreSQL을 연동하는 과정에서 “Timeout occurred” 또는 “Connection lost” 같은 오류 메시지를 마주하면 작업이 중단되고, 원인을 찾느라 몇 시간을 허비하게 됩니다. 데이터베이스 연결 자체는 정상인데 왜 n8n에서만 타임아웃이 발생하는지, 그리고 이를 어떻게 빠르고 확실하게 해결할 수 있는지 고민이 많으실 텐데요. 이 글에서는 실제 운영 환경에서 빈번하게 발생하는 n8n DB 커넥터 타임아웃 원인을 분석하고, MySQL과 PostgreSQL 각각의 사례에 맞춘 실전 해결책을 단계별로 정리했습니다.

1. n8n DB 타임아웃이 발생하는 근본 메커니즘

n8n은 워크플로우 실행 시 각 노드(DB 커넥터 포함)를 비동기로 처리합니다. 이때 n8n이 기본적으로 사용하는 MySQL2 또는 pg 라이브러리는 네트워크 지연이나 DB 서버의 설정값에 매우 민감합니다. 단순히 DB에 접속하는 순간의 문제가 아니라, n8n이 쿼리를 보낸 후 응답을 기다리는 시간(타임아웃)과 DB 서버가 유휴 연결을 종료하기까지의 시간이 서로 다르면 에러가 발생할 확률이 급증합니다.

일반적으로 발생하는 타임아웃 에러는 두 가지 유형으로 나뉩니다. 첫째는 초기 연결 시도 시 발생하는 커넥션 타임아웃으로, 주로 네트워크 문제나 DB 서버의 최대 연결 수 초과로 인해 발생합니다. 둘째는 쿼리 실행 중간에 발생하는 idle 타임아웃으로, 긴 트랜잭션이나 대용량 데이터 처리 시 n8n의 기본 타임아웃 값(보통 30초~60초)을 초과할 때 나타납니다. 이 두 가지를 구분하지 않고 동일하게 해결하려 하면 오히려 문제가 악화될 수 있습니다.

핵심은 n8n이 각 DB 커넥터를 생성하는 방식과 그 연결이 유지되는 생명주기를 이해하는 것입니다. n8n은 워크플로우가 트리거될 때마다 새 연결을 시도하지 않고, 커넥션 풀(Connection Pool)이라는 캐시 공간에 일정 개수의 연결을 미리 만들어 재사용합니다. 이 풀의 기본 설정이 DB 서버의 유휴 연결 설정과 불일치하면, 오래 방치된 연결이 서버에 의해 강제 종료된 후 n8n이 이를 인지하지 못하고 사용하려다 에러가 발생합니다.

2. MySQL 커넥터 타임아웃 실전 해결

MySQL을 사용하는 경우 가장 흔한 타임아웃 에러는 PROTOCOL_CONNECTION_LOST 또는 ETIMEDOUT입니다. 이는 대부분 MySQL 서버의 wait_timeout과 interactive_timeout 값이 기본값(보통 8시간)보다 짧게 설정되어 있거나, n8n 워커가 DB에 몰리는 상황에서 발생합니다.

2-1. MySQL 서버 측 설정 조정

MySQL 서버 my.cnf 파일에서 다음 두 가지 설정을 확인하세요. wait_timeout과 interactive_timeout을 600(10분) 이상으로 증가시키고, max_allowed_packet 크기도 64MB 이상으로 상향 조정하는 것이 좋습니다. 특히 n8n에서 바이너리 데이터나 긴 텍스트를 처리한다면 이 패킷 크기 제한이 문제가 될 수 있습니다.

[mysqld]
wait_timeout = 600
interactive_timeout = 600
max_allowed_packet = 64M
skip-name-resolve

skip-name-resolve 옵션은 DNS 역방향 조회를 방지하여 연결 속도를 높여줍니다. 이 옵션을 활성화하면 n8n 워커가 호스트명을 IP로 변환하는 과정에서 발생하는 지연을 없앨 수 있습니다. 다만, 이 경우 MySQL 계정이 IP 기반으로 등록되어 있어야 합니다.

2-2. n8n 노드 파라미터 튜닝

n8n에서 MySQL 노드를 사용할 때 고급 옵션(Advanced Options)을 확장하면 connectionLimit, connectTimeout, acquireTimeout 파라미터를 직접 조정할 수 있습니다. 기본값은 보통 connectionLimit이 10, connectTimeout이 10000ms(10초)로 설정되어 있습니다. 트래픽이 많은 워크플로우라면 connectionLimit을 25~50으로 늘리고, connectTimeout을 30000ms로 조정해 보세요.

파라미터	기본값	권장값	설명
connectionLimit	10	25 ~ 50	동시 접속 커넥션 수
connectTimeout (ms)	10000	30000	커넥션 생성 대기 시간
acquireTimeout (ms)	10000	60000	풀에서 커넥션을 빌리는 시간

위 표에 제시된 파라미터는 n8n에서 MySQL을 사용할 때 타임아웃 에러를 대부분 해결할 수 있는 핵심 설정입니다. 다만, connectionLimit을 과도하게 높이면 DB 서버 자체의 부하가 증가할 수 있으므로, 워크플로우가 실행되는 빈도와 쿼리 복잡성을 고려해 단계적으로 늘리는 것이 안전합니다.

3. PostgreSQL 커넥터 타임아웃 실전 해결

PostgreSQL에서는 Connection terminated due to connection timeout 또는 timeout expired 메시지가 흔합니다. n8n에서 PostgreSQL을 사용할 때는 주로 statement_timeout, TCP keepalive 설정, 그리고 SSL 인증 세 가지가 핵심입니다.

3-1. PostgreSQL 설정 파일 수정

postgresql.conf 파일에서 statement_timeout을 기본값(0=무제한)에서 일정 값으로 제한하거나, 반대로 n8n의 타임아웃을 더 길게 조정해야 합니다. 특히 PostgreSQL 서버가 Docker 컨테이너에서 실행되는 경우, 컨테이너 재시작 시마다 설정이 초기화될 수 있으므로 docker-compose.yml에 직접 명시하는 것이 좋습니다.

# postgresql.conf
statement_timeout = 120000  # 2분으로 설정
idle_in_transaction_session_timeout = 60000
tcp_keepalives_idle = 60
tcp_keepalives_interval = 10
tcp_keepalives_count = 5

tcp_keepalives 설정은 n8n과 PostgreSQL 사이에 오래 지속되는 연결이 네트워크 장비에 의해 중간에 끊기는 것을 방지해 줍니다. 특히 클라우드 환경(예: AWS RDS, GCP Cloud SQL)에서 로드밸런서나 NAT 게이트웨이를 거칠 때 이 keepalive 값을 설정하지 않으면 수 분 후 연결이 조용히 종료되어 버립니다.

3-2. n8n에서 PostgreSQL 연결 문자열 조정

n8n의 PostgreSQL 노드에서 연결 옵션을 수동으로 설정할 때는 Connection String(연결 문자열)에 sslmode 및 keepalive 파라미터를 추가해야 합니다. 특히 기본적으로 n8n은 SSL을 비활성화하는데, PostgreSQL 서버가 SSL을 강제하는 경우 타임아웃이 발생할 수 있습니다.

postgresql://username:password@host:5432/dbname?sslmode=prefer&keepalives=1&keepalives_idle=60&keepalives_interval=10

위와 같이 연결 문자열에 keepalives 파라미터를 명시하면 n8n이 주기적으로 TCP 세션을 유지하기 위한 패킷을 보냅니다. 이렇게 하면 DB 서버나 중간 네트워크 장비가 연결을 비활성으로 판단하지 않아 타임아웃이 발생하지 않습니다. 또한, sslmode=prefer는 서버가 SSL을 지원하면 SSL로 연결하고, 그렇지 않으면 일반 연결로 대체합니다.

3-3. 헬스체크 및 재연결 로직 추가

아무리 설정을 잘 해도 장기간 실행되는 워크플로우는 예기치 못한 네트워크 단절을 경험할 수 있습니다. 이 경우 n8n 워크플로우 자체에 IF 노드를 활용한 사전 체크 로직이나 Error Trigger를 추가하여 자동으로 재시도하도록 구성하는 것이 좋습니다. 예를 들어, DB 노드 실행 전에 간단한 SELECT 1 쿼리를 던져 연결이 유효한지 확인하고, 실패 시 실제 데이터 쿼리를 건너뛰고 알림을 보내는 방식입니다.

4. MySQL vs PostgreSQL 타임아웃 특성 비교 및 공통 체크리스트

두 데이터베이스 모두 n8n에서 타임아웃 이슈를 일으키지만, 발생 패턴이 약간 다릅니다. 아래 표를 통해 차이점을 명확히 파악하고 자신의 환경에 맞는 우선순위를 정하세요.

비교 항목	MySQL	PostgreSQL
가장 빈번한 에러	Connection lost / ETIMEDOUT	timeout expired / connection reset
주요 원인	wait_timeout 불일치, 커넥션 풀 크기 부족	keepalive 미설정, statement_timeout 제한
핵심 해결책	connectionLimit 증가 + wait_timeout 조정	keepalives 파라미터 + sslmode 설정
자동 재연결 지원	MySQL2 드라이버에서 지원하나 기본 비활성	pg 드라이버에서 지원하지 않아 워크플로우 로직 필요

위 비교에서 확인할 수 있듯이, 두 데이터베이스 모두 단순히 서버 설정만 변경해서는 완벽한 해결이 어렵습니다. n8n 워크플로우 설계 단계에서부터 재시도 정책과 연결 검증 로직을 포함하는 것이 필수적입니다. 아래는 DB 종류에 관계없이 적용할 수 있는 공통 체크리스트입니다.

• ✅ DB 서버 방화벽에서 n8n 워커 IP의 포트(3306/5432)가 허용되었는지 확인
• ✅ n8n이 실행되는 환경이 Docker라면, 호스트 네트워크 모드로 실행하여 NAT 변환에 의한 지연을 최소화
• ✅ 자주 실행되는 워크플로우라면 DB 쿼리 자체의 인덱스 사용 여부를 EXPLAIN으로 확인하고, 필요한 인덱스 추가
• ✅ n8n 환경변수 N8N_DATABASE_TYPE과 관계없이, 각 DB 커넥터 노드에 타임아웃 관련 환경변수(예: N8N_DB_CONNECTION_TIMEOUT)가 있는지 공식 문서에서 확인

5. 사례: 실무에서 겪은 타임아웃 해결 경험

실제 이커머스 매출 집계 자동화를 n8n으로 구성하던 중, 매일 새벽 3시에 실행되는 워크플로우가 PostgreSQL과 연결될 때 정확히 2분마다 타임아웃이 발생하는 문제가 있었습니다. 원인을 추적한 결과, 웹훅으로 데이터를 받는 노드에서의 처리가 지연되면서 DB 커넥터가 풀에 남아 있는 시간이 길어졌고, PostgreSQL 서버의 idle_in_transaction_session_timeout 기본값(기본 5분)보다 연결이 오래 유지되어 트랜잭션이 강제로 롤백되었습니다.

해결책으로는 n8n 워크플로우에서 DB 노드를 실행하기 전에 별도의 Function 노드를 추가하여 커넥션을 사전에 검증하고, PostgreSQL 설정에서 idle_in_transaction_session_timeout 값을 30분으로 늘렸습니다. 이 조치 이후로 타임아웃 에러율이 0%로 감소했습니다. 이 경험에서 얻은 교훈은, 타임아웃 문제를 DB 설정 탓으로만 돌리지 말고 n8n 워크플로우의 전체 실행 시간과 커넥션 점유 시간을 함께 분석해야 한다는 것입니다.

6. 결론: n8n 타임아웃 해결을 위한 실행 순서

n8n DB 커넥터 타임아웃 에러는 단독 원인보다 여러 가지 요인이 복합적으로 작용할 때 발생합니다. 문제를 해결하기 위해서는 아래 순서로 단계를 밟아 보시기 바랍니다.

첫 번째 단계로, n8n에서 해당 DB 노드의 실행 로그를 켜고 정확한 에러 메시지와 함께 발생 시각과 연결 지속 시간을 기록합니다. 두 번째 단계로, DB 서버 측의 하드웨어 리소스(CPU, 메모리, 연결 수)를 확인하여 서버 자체가 정상인지 판별하세요. 세 번째 단계로, 앞서 설명한 MySQL 또는 PostgreSQL 설정을 적용한 후 n8n 워커를 재시작합니다. 네 번째 단계로, 아직 해결되지 않았다면 n8n 워크플로우에 재시도 로직을 추가하고, DB 쿼리 성능 최적화를 통해 쿼리 실행 시간을 단축하세요.

마지막으로, 클라우드 매니지드 DB(RDS, Cloud SQL 등)를 사용 중이라면 벤더의 문서를 반드시 확인하세요. 대부분의 매니지드 서비스는 keepalive 설정이나 timeout 설정이 파라미터 그룹에서 비활성화되어 있을 수 있으며, 사용자가 임의로 변경할 수 없는 경우가 많습니다. 이 경우에는 n8n의 커넥션 풀 크기를 줄이거나, 워크플로우 실행 빈도를 조절하여 연결 자체의 라이프사이클을 짧게 만드는 것이 대안입니다.

타임아웃 에러는 한번 해결해 두면 이후 재발 가능성이 낮으므로, 초기에 다소 시간을 투자하더라도 위의 설정값들을 코드나 설정 파일로 관리하여 재현 가능한 형태로 만들어 두는 것이 좋습니다. 이것이 장기적으로 안정적인 n8n 운영의 지름길입니다.