결과 및 오류 코드

결과 및 오류 코드 (Result and Error Codes)

이 문서는 SQLite가 반환하는 모든 결과 코드와 확장 결과 코드를 설명해요. SQLite C API 함수들은 이 중 하나의 코드를 반환하며, 이 코드로 작업의 성공 또는 실패 원인을 판단해요.

출처: 문서

본문

SQLite의 C API는 결과 코드를 정수로 반환해요. 코드 값의 의미는 다음과 같이 나뉘어요.

성공(success): 0
오류(error): 1~99 (기본 오류)
확장 결과 코드(extended result codes): 100~255 (세부 원인)

사실 대부분의 오류 코드 값은 컴파일 옵션(SQLITE_OMIT_...)에 따라 달라질 수 있으며, 애플리케이션은 코드의 이름(예: SQLITE_CORRUPT)에 의존하는 것이 안전해요. HTML 결과 코드 값이 항상 일치한다고 가정해서는 안 돼요.

성공 코드

SQLITE_OK — 정상적으로 완료되었어요. 가장 흔한 결과 코드예요.

기본 오류 코드

SQLITE_ERROR — 일반적인 오류(구체적 원인은 별도 오류 메시지로 확인)
SQLITE_INTERNAL — SQLite 내부 오류 (버그를 의미하며, 정상적인 경우엔 발생하지 않아요)
SQLITE_PERM — 권한이 없는 접근 요청
SQLITE_ABORT — 콜백이 중단(abort)을 요청했어요
SQLITE_BUSY — 데이터베이스 파일이 잠겨 있어(locked) 작업을 진행할 수 없어요
SQLITE_LOCKED — 같은 연결 안의 또 다른 부분이 데이터베이스에서 표를 잠갔어요
SQLITE_NOMEM — 메모리 할당 실패
SQLITE_READONLY — 읽기 전용 데이터베이스에 쓰기를 시도했어요
SQLITE_INTERRUPT — 중단 요청으로 인해 작업이 취소되었어요
SQLITE_IOERR — I/O 오류(디스크 읽기/쓰기 실패)
SQLITE_CORRUPT — 데이터베이스 파일이 손상되었어요
SQLITE_NOTFOUND — 찾을 수 없음 (대체로 내부 용도)
SQLITE_FULL — 데이터베이스 또는 디스크가 가득 찼어요
SQLITE_CANTOPEN — 데이터베이스 파일을 열 수 없어요
SQLITE_PROTOCOL — 잠금 프로토콜 오류 (여러 프로세스에서 동시 접근 시)
SQLITE_EMPTY — 빈 데이터베이스 (대체로 내부 용도)
SQLITE_SCHEMA — 스키마가 변경되어 문장을 다시 준비해야 해요
SQLITE_TOOBIG — 문자열이나 BLOB이 너무 커요 (기본 최대 10억 바이트)
SQLITE_CONSTRAINT — 제약 조건(constraint) 위반이 발생했어요
SQLITE_MISMATCH — 데이터 타입 불일치
SQLITE_MISUSE — API를 잘못 사용했어요
SQLITE_NOLFS — 대용량 파일 지원 없음 (32비트 빌드)
SQLITE_AUTH — 인증(authorization) 거부
SQLITE_FORMAT — 형식 오류 (대체로 내부 용도)
SQLITE_RANGE — 인덱스가 범위를 벗어났어요 (주로 바인딩 인덱스)
SQLITE_NOTADB — 파일이 SQLite 데이터베이스가 아니에요
SQLITE_NOTICE — 통지 (대체로 내부 용도)
SQLITE_WARNING — 경고 (대체로 내부 용도)
SQLITE_ROW — sqlite3_step()이 결과 행 하나를 반환했어요
SQLITE_DONE — sqlite3_step()이 문장 실행을 완료했어요

확장 결과 코드

확장 코드는 기본 코드에 세부 원인을 더해요. 예를 들어 SQLITE_IOERR_READ, SQLITE_IOERR_WRITE, SQLITE_IOERR_FSYNC 같은 코드는 SQLITE_IOERR의 세부 종류를 나타내요. 대표적인 것은 다음과 같아요.

SQLITE_CONSTRAINT_CHECK — CHECK 제약 위반
SQLITE_CONSTRAINT_FOREIGNKEY — 외래 키 제약 위반
SQLITE_CONSTRAINT_NOTNULL — NOT NULL 제약 위반
SQLITE_CONSTRAINT_PRIMARYKEY — 기본 키 제약 위반
SQLITE_CONSTRAINT_UNIQUE — 고유(UNIQUE) 제약 위반
SQLITE_CONSTRAINT_TRIGGER — 트리거가 RAISE로 제약을 발생시켰어요
SQLITE_BUSY_RECOVERY — 다른 연결이 복구 작업 중이어서 사용할 수 없어요
SQLITE_BUSY_SNAPSHOT — 스냅샷이 오래되어 갱신해야 해요
SQLITE_LOCKED_SHAREDCACHE — 공유 캐시에서 다른 연결이 테이블을 잠갔어요
SQLITE_READONLY_CANTINIT — 쓰기용으로 초기화할 수 없어요
SQLITE_READONLY_RECOVERY — 복구가 필요한 데이터베이스는 읽기 전용이에요
SQLITE_IOERR_READ, SQLITE_IOERR_WRITE, SQLITE_IOERR_FSYNC 등 — 구체적인 I/O 실패 원인

오류 메시지 얻기

const char *sqlite3_errmsg(sqlite3 *db);
const char *sqlite3_errstr(int rc);

sqlite3_errmsg()는 가장 최근 오류의 설명을, sqlite3_errstr()는 결과 코드의 고정 설명을 반환해요.

확장 코드 사용하기

sqlite3_extended_result_codes()를 호출하면 API가 확장 결과 코드를 반환하도록 설정할 수 있어요.

sqlite3_extended_result_codes(db, 1);

이 설정이 켜져 있으면 함수가 SQLITE_CONSTRAINT 대신 SQLITE_CONSTRAINT_UNIQUE 같은 확장 코드를 반환해요.

결과 및 오류 코드