sqlite-utils 4.0rc1 adds migrations and nested transactions

sqlite-utils 4.0rc1 출시! 무엇이 달라졌을까요?

sqlite-utils는 파이썬(Python) 라이브러리와 CLI 도구를 하나로 합친 SQLite 유틸리티 모음집이에요. 파이썬의 기본 sqlite3 패키지 위에서 복잡한 테이블 변환, JSON 데이터로부터의 자동 테이블 생성 등 더 고차원의 풍부한 기능들을 제공해 줍니다.

이번에 첫 번째 릴리스 후보(Release Candidate) 버전인 sqlite-utils 4.0rc1이 공개되었는데요. 메이저 버전 숫자가 올라간 만큼 하위 호환성이 깨지는 변경 사항이 포함되어 있어서, 정식 출시 전에 많은 개발자분들이 직접 테스트해 보시길 권장하고 있답니다.

이번 RC 버전에서 가장 돋보이는 두 가지 핵심 신기능을 소개해 드릴게요!

새로운 기능 1: 마이그레이션(Migrations) 지원

첫 번째 주요 신기능은 바로 데이터베이스 마이그레이션 기능이에요. 완전히 새로 개발된 것은 아니고, 저자가 몇 년 전에 출시했던 sqlite-migrate 패키지를 약간 수정해서 이식한 것이랍니다. 오랜 기간 사용되며 안정성이 충분히 검증되었다고 판단하여 이번에 sqlite-utils에 직접 내장하게 되었어요.

migrations.py 파일에 정의하는 마이그레이션 코드 예시는 아래와 같아요.

from sqlite_utils import Database , Migrations 

migrations = Migrations ( "creatures" )

@ migrations () 
def create_table ( db ):
    db [ "creatures" ]. create (
        { "id" : int , "name" : str , "species" : str },
        pk = "id" ,
    )

@ migrations () 
def add_weight ( db ):
    db [ "creatures" ]. add_column ( "weight" , float )

위 코드는 creatures 테이블을 생성하고, 여기에 weight 컬럼을 추가하는 두 단계의 마이그레이션을 정의하고 있어요.

이렇게 정의한 마이그레이션은 파이썬 코드로 실행할 수 있어요.

db = Database ( "creatures.db" )
migrations . apply ( db )

또는 CLI 명령어로도 아주 간단하게 실행할 수 있답니다.

sqlite-utils migrate creatures.db migrations.py

이 마이그레이션 시스템은 의도적으로 단순하게 설계되었습니다. 롤백(Reverse Migration) 기능을 제공하지 않기 때문에, 실수가 있다면 롤백하는 대신 실수를 바로잡는 새로운 마이그레이션 코드를 작성해서 적용하는 방식으로 해결해야 해요.

이미 LLM 프로젝트를 비롯해 여러 프로젝트에서 수년간 사용되며 안정성과 유용함이 입증되었으니 안심하고 사용해 보세요!

새로운 기능 2: db.atomic()을 통한 중첩 트랜잭션

이 기능은 마이그레이션에 비해 아직 테스트가 덜 진행된 영역이라 개발자분들의 적극적인 피드백이 필요해요.

이전의 sqlite-utils는 트랜잭션 관리를 전적으로 사용자에게 맡겼고, with db.conn: 구조를 통해 파이썬 sqlite3 엔진의 메커니즘을 직접 활용해야 했어요. 하지만 SQLite는 세이브포인트(Savepoints) 형식의 중첩 트랜잭션을 지원하고 있죠. 이를 더 편리하게 쓸 수 있도록 Django나 Peewee에서 따온 atomic 개념의 추상화 API를 새롭게 도입했습니다.

새로운 API의 사용법은 다음과 같아요.

with db . atomic ():
    db . table ( "dogs" ). insert ({ "id" : 1 , "name" : "Cleo" }, pk = "id" )
    try :
        with db . atomic ():
            db . table ( "dogs" ). insert ({ "id" : 2 , "name" : "Pancakes" })
            raise ValueError ( "이 데이터는 건너뜁니다" )
    except ValueError :
        pass 
    db . table ( "dogs" ). insert ({ "id" : 3 , "name" : "Marnie" })

하위 호환성이 깨지는 변경 사항 (Breaking Changes)

4.0 버전으로 올라오면서 기존 버전과 호환되지 않는 변경점들이 꽤 있습니다. 주로 알파 버전(4.0a0, 4.0a1) 단계에서 정립된 내용들이에요.

추가적인 마이너 변경 사항

• `table.insert_all()` & `table.upsert_all()` 기능 확장: 딕셔너리 리스트 형태 외에도 리스트나 튜플의 이터레이터를 지원합니다. 단, 첫 번째 항목에는 컬럼 이름의 리스트/튜플을 지정해 주어야 합니다.
• `pyproject.toml` 전환: 패키징 도구로 기존 setup.py 대신 pyproject.toml을 사용하도록 현대화되었습니다.
• 스키마 상태 기억력 개선: Python API에서 테이블 객체가 처음 생성되었을 때의 기본 키(Primary Key)나 스키마 세부 사항을 훨씬 더 안정적으로 기억합니다.
• `--functions` 개선: CLI 환경에서 파이썬 코드 문자열뿐만 아니라 로컬 파이썬 파일의 경로 자체를 전달받을 수 있게 되었고, 이 옵션을 여러 번 사용하는 것도 가능해졌습니다.

🚀 지금 바로 테스트해 보기!

새로운 RC 버전은 다음 명령어로 간단히 설치하여 사용해 볼 수 있습니다.

pip install sqlite-utils==4.0rc1

혹은 uv가 설치되어 있다면 설치 과정 없이 일회성으로 CLI 버전을 바로 실행해 볼 수도 있어요.

uvx --with sqlite-utils==4.0rc1 sqlite-utils --help

의견이나 버그 제보가 있다면 Discord 채널에 방문하시거나 GitHub Issues를 통해 적극적으로 참여해 주세요!