프렌들리 가이드: SQLite 오류 코드 뽀개기 (BUSY, LOCKED, CONSTRAINT)

2025-10-14

SQLite에서는 함수 호출 결과로 결과 코드 (Result Code)를 반환하는데요, 이 중 문제가 있음을 나타내는 코드들을 오류 코드 (Error Code)라고 부릅니다. 코드를 확인해서 문제가 없으면 다음 작업을 진행하고, 문제가 생겼다면 적절한 대처를 해야 합니다.

코드 (Code)	상수 (Constant)	의미 (Meaning)
0	`SQLITE_OK`	성공! 작업이 성공적으로 완료되었습니다. (가장 많이 보게 될 코드예요 )
1	`SQLITE_ERROR`	일반적인 오류. 구문 오류 등 다른 특정 오류 코드가 없을 때 사용됩니다.
5	`SQLITE_BUSY`	바쁨! 다른 연결/프로세스에서 데이터베이스 파일에 락(Lock)이 걸려 잠시 접근할 수 없을 때 발생합니다.
6	`SQLITE_LOCKED`	잠김! 동일한 연결 내에서 락(Lock) 충돌이 발생했을 때 나타납니다.
19	`SQLITE_CONSTRAINT`	제약 조건 위반! `NOT NULL`이나 `UNIQUE`, `FOREIGN KEY` 등 테이블에 설정된 제약 조건을 위반했을 때 발생합니다.
100	`SQLITE_ROW`	`sqlite3_step()` 함수 호출 시 결과 행이 준비되었음을 나타냅니다. (오류가 아닙니다!)
101	`SQLITE_DONE`	`sqlite3_step()` 함수 호출 시 모든 결과 행 처리가 완료되었음을 나타냅니다. (오류가 아닙니다!)

<hr>

문제
여러 스레드나 프로세스가 동시에 데이터베이스에 쓰기 작업을 하려고 할 때 발생합니다. 데이터베이스가 "바쁘다"고 응답하는 거죠.

해결책 재시도 로직 (Retry Logic)을 구현하거나 Busy Handler를 설정합니다.

import sqlite3
import time

DB_NAME = 'test.db'

def safe_db_operation(sql, params=()):
    """
    SQLITE_BUSY 오류 발생 시 일정 시간 기다린 후 재시도하는 함수
    """
    max_retries = 5
    delay = 1  # 1초 대기 후 재시도
    
    for attempt in range(max_retries):
        try:
            conn = sqlite3.connect(DB_NAME)
            cursor = conn.cursor()
            
            cursor.execute(sql, params)
            conn.commit()
            
            print(f" 시도 {attempt + 1}: 성공적으로 실행되었습니다.")
            conn.close()
            return True
            
        except sqlite3.OperationalError as e:
            # SQLITE_BUSY (5) 또는 SQLITE_LOCKED (6) 관련 오류 처리
            if "database is locked" in str(e):
                print(f" 시도 {attempt + 1}: 데이터베이스 잠금 발생. {delay}초 후 재시도합니다...")
                time.sleep(delay)
                delay *= 2 # 대기 시간을 늘려서 충돌 확률을 줄일 수 있어요 (지수 백오프)
            else:
                # 다른 OperationalError는 즉시 보고
                print(f" 데이터베이스 작업 오류: {e}")
                conn.close()
                return False
                
        except Exception as e:
            print(f" 알 수 없는 오류 발생: {e}")
            conn.close()
            return False

    print(f" 최대 재시도 횟수({max_retries}회) 초과로 작업 실패.")
    return False

# 사용 예시
safe_db_operation("INSERT INTO users (name) VALUES (?)", ("Alice",))

팁
Python의 sqlite3.connect() 함수에 timeout 인자를 설정하면, 해당 시간(초) 동안 자동으로 재시도를 시도하게 할 수 있어 더 간단합니다! (기본값은 5초예요)

문제
테이블에 데이터를 넣거나 수정하려는데, 테이블 정의 시 설정한 제약 조건 (예
고유해야 하는 값, NULL을 허용하지 않는 값 등)을 위반했을 때 발생합니다.

해결책
쿼리를 실행하기 전 입력 데이터의 유효성 검사를 하거나, 오류 발생 시 예외 처리를 통해 사용자에게 정확한 정보를 제공해야 합니다.

import sqlite3

DB_NAME = 'test_constraint.db'

# 테이블 생성 (UNIQUE 제약 조건 포함)
def setup_db():
    conn = sqlite3.connect(DB_NAME)
    cursor = conn.cursor()
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS products (
            id INTEGER PRIMARY KEY,
            name TEXT NOT NULL UNIQUE, -- 이름은 NULL이 아니어야 하고, 고유해야 함!
            price REAL
        )
    """)
    conn.commit()
    conn.close()

def insert_product(name, price):
    conn = sqlite3.connect(DB_NAME)
    cursor = conn.cursor()
    
    try:
        # 첫 번째 성공적인 삽입
        cursor.execute("INSERT INTO products (name, price) VALUES (?, ?)", (name, price))
        conn.commit()
        print(f" '{name}' 제품이 성공적으로 추가되었습니다.")
        
    except sqlite3.IntegrityError as e:
        # SQLITE_CONSTRAINT 오류가 여기에 해당됩니다.
        if "UNIQUE constraint failed" in str(e):
            print(f" 오류: 제품 이름 '{name}'은 이미 존재합니다. 고유해야 합니다! (SQLITE_CONSTRAINT)")
        elif "NOT NULL constraint failed" in str(e):
             print(f" 오류: 제품 이름은 비워둘 수 없습니다. (SQLITE_CONSTRAINT)")
        else:
            print(f" 무결성 오류 발생: {e}")
            
    finally:
        conn.close()

setup_db()
insert_product("Laptop Pro", 1200.00)
insert_product("Laptop Pro", 1500.00) # <- UNIQUE 제약 조건 위반!
insert_product(None, 50.00)           # <- NOT NULL 제약 조건 위반!