데이터베이스 환경 변수
n8n v2.29이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요. 기본적으로 n8n은 SQLite를 사용합니다. 이 페이지에서는 셀프 호스팅 n8n 인스턴스에서 선택한 데이터베이스를 구성하기 위한 환경 변수를 설명합니다. n8n은 데이터베이스에 계속 접근할 수 있는지 지속적으로 확인합니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
기본적으로 n8n은 SQLite를 사용합니다. n8n은 PostgreSQL도 지원합니다. n8n은 v1.0에서 MySQL 및 MariaDB에 대한 지원을 중단했습니다.
이 페이지에서는 셀프 호스팅 n8n 인스턴스에서 선택한 데이터베이스를 구성하기 위한 환경 변수를 설명합니다.
| 변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
DB_TYPE/ _FILE |
Enum string:sqlite, postgresdb |
sqlite |
사용할 데이터베이스입니다. |
DB_TABLE_PREFIX |
* | - | 테이블 이름에 사용할 접두사입니다. |
DB_PING_INTERVAL_SECONDS |
Number | 2 |
n8n이 연결이 아직 살아 있는지 확인하기 위해 데이터베이스에 핑을 보내는 주기(초)입니다. |
DB_PING_TIMEOUT_MS |
Number | 5000 |
n8n이 단일 핑에 대한 응답을 실패로 간주하기 전까지 기다리는 시간(밀리초)입니다. 더 이상 사용되지 않는(deprecated) N8N_DB_PING_TIMEOUT이 설정되어 있으면 이 값으로 대체됩니다. |
DB_PING_MAX_FAILURES_BEFORE_RECOVERY |
Number | 3 |
n8n이 연결이 끊어졌다고 간주하고 복구를 시작하기 전까지 연속으로 실패해야 하는 핑 횟수입니다. |
DB_RECOVERY_BACKOFF_MIN_MS |
Number | 1000 |
n8n이 첫 번째 복구 시도를 하기 전까지 기다리는 시간(밀리초)입니다. 재시도할 때마다 대기 시간이 늘어납니다(지수 백오프). |
DB_RECOVERY_BACKOFF_MAX_MS |
Number | 30000 |
n8n이 복구 시도 사이에 기다리는 최대 시간(밀리초)입니다. 이 값은 백오프의 상한선입니다. DB_RECOVERY_BACKOFF_MIN_MS보다 크거나 같아야 합니다. |
DB_CONNECTION_ACQUISITION_TIMEOUT_MS |
Number | 30000 |
복구가 진행되는 동안 쿼리가 오류로 즉시 실패하기 전까지 기다리는 시간(밀리초)입니다. 무기한 대기하려면 0으로 설정합니다. PostgreSQL에만 적용됩니다. |
PostgreSQL#
| 변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
DB_POSTGRESDB_DATABASE/ _FILE |
String | n8n |
PostgreSQL 데이터베이스의 이름입니다. |
DB_POSTGRESDB_HOST/ _FILE |
String | localhost |
PostgreSQL 호스트입니다. |
DB_POSTGRESDB_PORT/ _FILE |
Number | 5432 |
PostgreSQL 포트입니다. |
DB_POSTGRESDB_USER/ _FILE |
String | postgres |
PostgreSQL 사용자입니다. |
DB_POSTGRESDB_PASSWORD/ _FILE |
String | - | PostgreSQL 비밀번호입니다. |
DB_POSTGRESDB_POOL_SIZE/ _FILE |
Number | 2 |
n8n이 가져야 할 병렬 열린 Postgres 연결 수를 제어합니다. 이 값을 늘리면 리소스 활용에 도움이 될 수 있지만, 연결이 너무 많으면 성능이 저하될 수 있습니다. |
DB_POSTGRESDB_CONNECTION_TIMEOUT/ _FILE |
Number | 20000 |
Postgres 연결 타임아웃(ms)입니다. |
DB_POSTGRESDB_IDLE_CONNECTION_TIMEOUT/ _FILE |
Number | 30000 |
유휴 연결이 제거 대상이 되기까지 걸리는 시간입니다. |
DB_POSTGRESDB_MAX_CONNECTION_LIFETIME_MS/ _FILE |
Number | 3600000 |
n8n이 풀링된 연결을 재활용하기 전까지 유지하는 시간(밀리초)입니다. 오래된 연결을 재활용하면 n8n이 알아채지 못한 채 데이터베이스나 네트워크에 의해 끊긴 유효하지 않은(stale) 연결을 방지하는 데 도움이 됩니다. 기본값은 1시간입니다. 재활용을 비활성화하려면 0으로 설정합니다. |
DB_POSTGRESDB_KEEP_ALIVE/ _FILE |
Boolean | true |
연결에서 TCP keep-alive를 활성화할지 여부입니다. Keep-alive를 사용하면 n8n이 쿼리를 먼저 실행하지 않고도 연결이 끊어진 것을 알아챌 수 있습니다. |
DB_POSTGRESDB_KEEP_ALIVE_INITIAL_DELAY_MS/ _FILE |
Number | 10000 |
n8n이 연결에서 첫 번째 TCP keep-alive 프로브를 보내기 전까지 기다리는 시간(밀리초)입니다. |
DB_POSTGRESDB_SCHEMA/ _FILE |
String | public |
PostgreSQL 스키마입니다. |
DB_POSTGRESDB_SSL_ENABLED/ _FILE |
Boolean | false |
SSL을 활성화할지 여부입니다. DB_POSTGRESDB_SSL_CA, DB_POSTGRESDB_SSL_CERT 또는 DB_POSTGRESDB_SSL_KEY가 정의되어 있으면 자동으로 활성화됩니다. |
DB_POSTGRESDB_SSL_CA/ _FILE |
String | - | PostgreSQL SSL 인증 기관입니다. |
DB_POSTGRESDB_SSL_CERT/ _FILE |
String | - | PostgreSQL SSL 인증서입니다. |
DB_POSTGRESDB_SSL_KEY/ _FILE |
String | - | PostgreSQL SSL 키입니다. |
DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED/ _FILE |
Boolean | true |
n8n이 인증되지 않은 SSL 연결을 거부해야 하는지(true) 아닌지(false)입니다. |
SQLite#
| 변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
DB_SQLITE_POOL_SIZE |
Number | 0 |
SQLite 파일을 WAL 모드로 열지 롤백 저널 모드로 열지를 제어합니다. 0으로 설정하면 롤백 저널 모드를 사용합니다. 0보다 크면 WAL 모드를 사용하며, 값에 따라 구성할 병렬 SQL 읽기 연결 수가 결정됩니다. WAL 모드는 롤백 저널 모드보다 훨씬 더 성능이 좋고 안정적입니다. |
DB_SQLITE_VACUUM_ON_STARTUP |
Boolean | false |
시작 시 데이터베이스를 재구축하기 위해 VACUUM 작업을 실행합니다. 파일 크기를 줄이고 인덱스를 최적화합니다. 이는 오래 실행되는 차단(blocking) 작업이며 시작 시간을 늘립니다. |
데이터베이스 연결 복구 작동 방식#
n8n은 데이터베이스에 계속 접근할 수 있는지 지속적으로 확인합니다. 데이터베이스 재시작이나 일시적인 네트워크 장애 등으로 연결이 끊어지면, n8n을 다시 시작할 때까지 계속 끊긴 상태로 있는 대신 n8n이 스스로 연결을 복구할 수 있습니다.
이 페이지의 변수들이 제어하는 주기는 다음과 같습니다.
DB_PING_INTERVAL_SECONDS마다 n8n이 핑을 보냅니다. 각 핑은 응답까지DB_PING_TIMEOUT_MS의 시간을 갖습니다.DB_PING_MAX_FAILURES_BEFORE_RECOVERY만큼 핑이 연속으로 실패하면, n8n은 연결이 끊어졌다고 간주합니다.- 그런 다음 n8n은 연결을 재구축하며,
DB_RECOVERY_BACKOFF_MIN_MS에서 시작해DB_RECOVERY_BACKOFF_MAX_MS를 넘지 않는 범위에서 점점 늘어나는 대기 시간을 두고 재시도합니다. - PostgreSQL의 경우, 복구가 진행되는 동안 새로운 쿼리는 연결이 복구되기를 최대
DB_CONNECTION_ACQUISITION_TIMEOUT_MS만큼 기다린 다음, 멈춰 있는 대신 오류로 실패합니다.
모든 데이터베이스에 적용됨
상태 확인 및 복구 주기(DB_PING_* 및 DB_RECOVERY_BACKOFF_* 변수)는 모든 데이터베이스 유형에 적용됩니다.
나머지 설정(DB_CONNECTION_ACQUISITION_TIMEOUT_MS, DB_POSTGRESDB_MAX_CONNECTION_LIFETIME_MS, DB_POSTGRESDB_KEEP_ALIVE, DB_POSTGRESDB_KEEP_ALIVE_INITIAL_DELAY_MS)은 PostgreSQL에만 적용됩니다. 기본값은 대부분의 배포 환경에 적합하므로 연결 문제가 발생하지 않는 한 변경하지 않고 그대로 두어도 됩니다.