SQLite는 파일 하나로 시작하기 쉽습니다. 작은 앱, 데이터 수집 도구, 개인용 자동화 스크립트에서는 그 단순함이 큰 장점입니다. 하지만 프로젝트가 오래 유지되면 문제는 데이터 자체보다 “스키마를 어떻게 바꿀 것인가”로 옮겨갑니다. 테이블을 수정하고, 컬럼을 추가하고, 기존 데이터를 보존하면서 여러 환경의 데이터베이스를 같은 상태로 맞춰야 하기 때문입니다.
sqlite-utils 4.0은 이 지점을 다루는 릴리스입니다. sqlite-utils는 Python 기본 sqlite3 패키지 위에서 더 높은 수준의 SQLite 작업을 제공하는 Python 라이브러리이자 CLI 도구입니다.1 복잡한 테이블 변환과 JSON 데이터 기반 자동 테이블 생성 같은 기능을 제공해 왔고,1 4.0에서는 여기에 스키마 변경 이력을 관리하는 기능이 더해졌습니다.
핵심 변화: 마이그레이션이 기본 기능이 됐다
sqlite-utils 4.0의 가장 중요한 변화는 데이터베이스 마이그레이션 지원입니다. 마이그레이션은 데이터베이스 스키마를 시간에 따라 구조적으로 변경하기 위한 메커니즘입니다.2 어떤 변경을 어떤 순서로 적용했는지 코드로 남기고, 이미 적용된 변경은 다시 실행하지 않도록 관리합니다.
sqlite-utils의 마이그레이션은 Python 파일에서 Migrations 객체와 데코레이터로 정의할 수 있습니다. 실행 방식도 두 가지입니다. Python 코드에서는 migrations.apply(db)를 호출하고, CLI에서는 다음 형식으로 실행합니다.1
sqlite-utils migrate 데이터베이스파일 마이그레이션파일적용된 마이그레이션 이력은 데이터베이스 안의 _sqlite_migrations 테이블에 기록됩니다.3 이 구조 덕분에 배포된 도구나 앱이 자신의 SQLite 데이터베이스를 현재 코드가 기대하는 스키마로 맞추는 흐름을 만들 수 있습니다.
작고 명시적인 설계
이번 마이그레이션 기능은 완전히 새로 만든 시스템이 아니라 기존 sqlite-migrate 패키지를 약간 수정해 sqlite-utils에 포함한 것입니다.1 즉, sqlite-utils의 성격에 맞게 작고 직접적인 방식으로 들어왔습니다.
이 점은 Django 같은 대형 프레임워크의 마이그레이션과 구분해서 이해하는 편이 좋습니다. sqlite-utils는 모델 정의를 분석해 자동으로 마이그레이션을 생성하는 도구가 아닙니다. 개발자가 필요한 스키마 변경을 Python 코드로 직접 작성하고, 그 변경 이력을 sqlite-utils가 추적하는 방식에 가깝습니다.
또 하나 중요한 제한이 있습니다. sqlite-utils의 마이그레이션 시스템은 reverse migration을 제공하지 않습니다.1 잘못된 마이그레이션을 되돌리는 별도 기능이 있는 것이 아니라, 문제를 수정하는 새 마이그레이션을 배포해야 합니다.1 따라서 실제 적용 전에는 데이터베이스 파일 백업이나 테스트 데이터베이스에서의 검증을 운영 습관으로 두는 편이 안전합니다.
왜 4.0인가
sqlite-utils 4.0은 2026년 7월 7일 공개된 프로젝트의 124번째 릴리스이며, 2020년 11월 3.0 이후 첫 메이저 버전 업데이트입니다.3 메이저 버전이 올라간 이유는 기능 추가뿐 아니라 일부 경미한 하위 호환성 깨짐 변경이 포함됐기 때문입니다.2
주요 추가 기능은 세 가지로 볼 수 있습니다.
데이터베이스 마이그레이션
db.atomic()을 통한 중첩 트랜잭션복합 외래 키 지원
이 가운데 마이그레이션은 스키마 이력을 관리하는 기능이고, db.atomic()은 여러 작업을 하나의 단위로 다루거나 중첩 트랜잭션을 다룰 때 유용합니다. 복합 외래 키 지원은 둘 이상의 컬럼 조합으로 관계를 표현해야 하는 스키마에서 의미가 있습니다.
어떻게 받아들이면 좋을까
sqlite-utils 4.0은 SQLite를 “가볍게 쓰는 파일 데이터베이스”로만 보는 관점에서 한 걸음 더 나아갑니다. 작은 도구라도 시간이 지나면 스키마 변경은 반복됩니다. 그때 변경 절차가 코드와 이력으로 남아 있으면, 새 설치 환경이나 오래된 데이터베이스를 훨씬 안정적으로 다룰 수 있습니다.
따라서 sqlite-utils를 쓰는 프로젝트라면 4.0의 마이그레이션을 단순한 새 기능이 아니라 유지보수 방식의 변화로 보는 것이 좋습니다. 스키마 변경을 즉석 SQL로 처리하기보다, 마이그레이션 파일로 남기고 적용 이력을 추적하는 흐름을 기본값으로 삼을 수 있기 때문입니다.
1sqlite-utils 4.0rc1 adds migrations and nested transactions
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.