크래시 트러블슈팅

크래시 트러블슈팅 (Crashes)

DuckDB는 방대한 테스트 스위트로 철저히 테스트됩니다. 그렇지만 버그는 여전히 발생할 수 있고, 때로는 크래시로 이어지기도 해요. 이 페이지는 DuckDB 크래시를 트러블슈팅하는 실용적인 정보를 담고 있습니다.

크래시 유형 (Types of Crashes)

크래시는 크게 몇 가지 유형으로 나눌 수 있어요.

종료 시그널 (Termination signals): SIGSEGV(세그멘테이션 폴트), SIGABRT 등으로 프로세스가 멈추는 경우예요. 이런 경우는 절대 발생하면 안 되는 상황이라 이슈를 제출해 주세요.
내부 오류 (Internal errors): 연산이 Internal Error를 일으킬 수 있어요. 예:
```
INTERNAL Error:
Attempted to access index 3 within vector of size 3
```
내부 오류가 발생한 뒤 DuckDB는 제한 모드로 진입합니다. 이후의 모든 연산은 다음 오류 메시지를 냅니다.
```
FATAL Error:
Failed: database has been invalidated because of a previous fatal error.
The database must be restarted prior to being used again.
```
메모리 부족 오류 (Out of memory errors): DuckDB 크래시는 운영체제가 프로세스를 죽인 것의 증상일 수도 있어요. 예를 들어 많은 Linux 배포판은 OOM reaper/killer 프로세스를 실행해 메모리를 확보하기 위해 프로세스를 죽임으로써 OS가 메모리를 다 쓰는 걸 막습니다. DuckDB 세션이 OOM reaper에 의해 종료됐다면 “OOM errors” 페이지를 참고하세요.

데이터 복구 (Recovering Data)

크래시 전에 DuckDB 세션이 영구 데이터베이스 파일에 쓰고 있었다면, 데이터베이스 옆에 데이터베이스 파일명을 딴 ⟨database_filename⟩.wal라는 WAL(write-ahead log) 파일이 있을 수 있어요. WAL 파일에서 데이터를 복구하려면 그 영구 데이터베이스에서 새 DuckDB 세션을 시작하면 됩니다. DuckDB가 write-ahead 로그를 재생(replay)한 다음 체크포인트 연산을 수행하면서, 데이터베이스를 크래시 이전 상태로 되돌려 놓아요.

크래시 트러블슈팅 (Troubleshooting the Crash)

기존 이슈 검색하기

크래시를 일으키는 버그를 다른 누군가가 이미 보고했을 가능성이 있어요. GitHub 이슈 트래커에서 오류 메시지를 검색해 관련 이슈를 찾아보세요. DuckDB 커뮤니티가 크기 때문에 우회 방법(wokaround) 제안이 있을 수 있습니다.

쿼리 옵티마이저 비활성화하기

일부 크래시는 DuckDB의 쿼리 옵티마이저 컴포넌트가 원인이에요. 옵티마이저가 크래시를 일으키는지 확인하려면 옵티마이저를 끄고 쿼리를 다시 실행해 보세요.

PRAGMA disable_optimizer;

쿼리가 성공적으로 끝난다면 크래시는 하나 이상의 옵티마이저 규칙 때문이었던 셈이에요. 크래시를 일으킨 특정 규칙을 특정하려면 옵티마이저 규칙을 선택적으로 비활성화해 볼 수 있어요. 이렇게 하면 나머지 옵티마이저 규칙의 이점은 그대로 누릴 수 있습니다.

문제를 격리해 보기

일부 문제는 서로 다른 컴포넌트·확장의 상호작용 때문이거나, 특정 플랫폼·클라이언트 언어에만 국한됩니다. 문제를 더 작은 문제로 격리할 수 있는 경우가 많아요.

순수 SQL로 재현하기

클라이언트 라이브러리 차이 때문에 문제가 생길 수도 있어요. 그런지 확인하려면 DuckDB CLI 클라이언트로 순수 SQL 쿼리를 써서 문제를 재현해 보세요. 명령줄 클라이언트에서 재현할 수 없다면 클라이언트 라이브러리와 관련된 문제일 가능성이 큽니다.

다른 하드웨어 설정

경험상 여러 크래시는 결함 있는 하드웨어(과열된 하드디스크, 오버클럭된 CPU 등) 때문에 발생해요. 그래서 같은 작업을 다른 컴퓨터에서 실행해 보는 것도 시도할 가치가 있습니다.

쿼리 분해하기

쿼리를 각각 별도의 DuckDB 확장과 SQL 기능을 쓰는 여러 개의 더 작은 쿼리로 쪼개 보는 게 좋아요.

예를 들어 AWS S3 버킷의 데이터셋을 대상으로 조인 두 번을 수행하는 쿼리가 있다면, 다음처럼 일련의 더 작은 단계로 다시 써 보세요. 먼저 데이터셋 파일을 수동으로 다운로드해 DuckDB로 로드합니다. 그다음 첫 번째 조인과 두 번째 조인을 따로 수행하세요. 다단계 접근에서도 어떤 단계에서 크래시가 재현된다면, 그 크래시를 유발하는 쿼리가 최소 재현 예시(minimal reproducible example)를 만들기 좋은 기준이 됩니다. 다단계 방식이 잘 동작해서 더 이상 크래시가 나지 않는다면, 원래 쿼리를 재구성해 어느 단계가 오류를 다시 도입하는지 관찰해 보세요. 두 경우 모두 무엇이 문제를 일으키는지 더 잘 이해하게 되고, 바로 쓸 수 있는 우회 방법도 얻게 될 수 있어요. 어느 쪽이든 발견 내용을 담아 이슈 제출을 고려해 주세요.

이슈 제출 (Submitting an Issue)

DuckDB에서 크래시를 발견했다면, 최소 재현 예시와 함께 GitHub 이슈 트래커에 이슈를 제출해 주세요.