sqlite-utils는 SQLite 데이터베이스를 CLI와 Python 라이브러리로 다루는 도구입니다.1 2026년 7월 5일 공개된 4.0rc3는 릴리스 후보 버전이며, 핵심 변화는 스키마를 더 정확하게 해석하도록 외래 키 처리 방식을 고친 데 있습니다.2
이번 변경은 특히 복합 외래 키를 쓰는 프로젝트나 table.foreign_keys 결과를 코드에서 직접 다루는 사용자에게 중요합니다.
복합 외래 키를 “여러 개”가 아니라 “하나의 관계”로 본다
외래 키는 한 테이블의 값이 다른 테이블의 값과 연결되어야 한다는 제약입니다. SQLite에서 외래 키는 하나의 컬럼일 수도 있고, 여러 컬럼을 묶은 형태일 수도 있습니다.3
4.0rc3는 복합 외래 키를 검사하고 생성하는 기능을 포함합니다.2 예를 들어 campus_name과 dept_code가 함께 다른 테이블을 참조한다면, 이는 컬럼별로 따로 존재하는 외래 키 두 개가 아니라 두 컬럼이 함께 의미를 갖는 하나의 관계입니다.
이전 버전의 문제는 이 지점에 있었습니다. 복합 외래 키를 컬럼별 ForeignKey 여러 개로 반환했기 때문에, 실제로는 하나의 제약인데 독립된 외래 키 여러 개처럼 보일 수 있었습니다.2 4.0rc3에서는 이를 is_compound=True인 단일 ForeignKey 객체로 표현합니다.2
즉, 이번 변경은 단순한 출력 형식 조정이 아니라 데이터베이스 제약의 의미를 더 정확히 드러내는 방향입니다.
table.foreign_keys 사용 코드는 점검이 필요하다
가장 주의해야 할 호환성 깨짐 변경은 table.foreign_keys의 반환값입니다. 이제 이 값은 namedtuple이 아니라 dataclass 기반 ForeignKey 객체입니다.2
따라서 기존처럼 다음과 같은 방식으로 다룰 수 없습니다.
table, column, other_table, other_column = foreign_key또는 인덱스로 접근하는 방식도 더 이상 사용할 수 없습니다.2 대신 필드 이름으로 접근해야 합니다.
복합 외래 키의 경우 구조도 달라집니다. columns와 other_columns에는 튜플이 들어가고, 단일 컬럼 외래 키에 쓰이던 column과 other_column은 None이 됩니다.2
업그레이드 전에는 다음을 확인하는 것이 좋습니다.
table.foreign_keys결과를 언패킹하는 코드가 있는가foreign_key[0]처럼 인덱스로 접근하는 코드가 있는가복합 외래 키를 단일 컬럼 외래 키 여러 개처럼 처리하는 로직이 있는가
column,other_column만 보고 외래 키를 판단하는 코드가 있는가
이런 코드가 있다면 ForeignKey 객체의 필드 기반 접근 방식에 맞춰 수정해야 합니다.
컬럼 이름 비교는 SQLite 규칙에 더 가까워졌다
4.0rc3에는 컬럼 이름 처리 방식의 조정도 포함됐습니다. Python API에 넘긴 컬럼 이름을 실제 테이블 스키마와 비교할 때, 이제 대소문자를 구분하지 않도록 바뀌었습니다.2
이는 SQLite가 식별자를 대체로 대소문자 구분 없이 다루는 방식에 맞춘 변화입니다. 이전에는 SQL 생성 자체는 가능해도, Python 쪽 스키마 비교 과정에서 실패하거나 기대한 작업이 일어나지 않는 경우가 있었습니다.2
이 변경 역시 같은 방향을 가리킵니다. sqlite-utils가 자체적인 해석보다 SQLite의 실제 동작 방식에 더 맞춰지고 있습니다.
이번 릴리스에서 봐야 할 핵심
sqlite-utils 4.0rc3의 중요한 메시지는 “외래 키를 더 정확히 읽고 표현한다”는 것입니다. 복합 외래 키는 여러 개의 단순 외래 키가 아니라 하나의 복합 관계로 다뤄지고, ForeignKey 객체도 그 의미를 표현할 수 있도록 바뀌었습니다.
다만 그만큼 기존 코드와의 호환성에는 주의가 필요합니다. 특히 table.foreign_keys를 튜플처럼 사용하던 코드는 반드시 점검해야 합니다.
이번 릴리스 후보는 SQLite를 감싸는 도구가 어떤 방향으로 발전해야 하는지 잘 보여줍니다. 편의성만이 아니라, SQLite의 실제 스키마 규칙과 제약 의미를 정확히 반영하는 것이 더 중요해졌습니다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.