2026-07-07-én megjelent a sqlite-utils 4.0, a projekt 124. kiadása és az első nagyobb verzióugrás a 3.0 óta (utóbbi 2020. novemberi). A kiadás tartalmaz néhány kisebb, de visszafelé inkompatibilis változtatást (erről részletesen a frissítési útmutató szól), valamint három fő újdonságot: adatbázis-séma migrációkat, beágyazott tranzakciók támogatását a db.atomic() segítségével, és összetett idegenkulcsok (compound foreign keys) kezelését.
Fő újítások
- Adatbázis-séma migrációk
- Beágyazott tranzakciók db.atomic() kontextuskezelővel
- Összetett idegenkulcsok támogatása (létrehozás, transzformáció, introspekció)
Ezek a funkciók együttesen célzottan egyszerűsítik a SQLite-projektek hosszú távú karbantartását és sémaváltozásainak kezelését.
Migrációk részletei
A migrációk sorozatként definiálják az adatbázison elvégzendő lépéseket, és nyilvántartják, hogy melyik migrációt futtatták már. A migrációk Python fájlokban készülnek a sqlite-utils könyvtár Migrations osztályának segítségével; a könyvtár erős eszköze a table.transform() metódus, amely olyan "alter table"-szerű műveleteket valósít meg, amelyeket a natív SQLite ALTER TABLE nem támogat. A transform() minta a SQLite dokumentáció által ajánlott eljárást követi: új ideiglenes táblát hoz létre az új sémával, átmásolja az adatokat, majd törli a régi táblát és átnevezi az ideigleneset.
Példa (szerkezetbe rendezett): három migrációs lépés, először létrehoz egy creatures táblát, aztán hozzáad egy weight oszlopot, majd megváltoztatja két oszlop típusát. A migrációk fájlban (migrations.py) definiált Migrations() példányok futtathatók parancssorból vagy Pythonból.
Parancssori példa új adatbázison futtatva:
- uvx sqlite-utils migrate data.db migrations.py
- uvx sqlite-utils schema data.db
A migrációk futtartását nyilvántartó tábla a _sqlite_migrations, amely tárolja a migration_set, name és applied_at mezőket. A példa után a creatures tábla végső sémája a migrációk alkalmazása után:
CREATE TABLE "creatures" ("id" INTEGER PRIMARY KEY, "name" TEXT, "species" INTEGER, "weight" TEXT);
A migrációk listáját a --list opcióval lehet megnézni; a cikk példájában a create_table, add_weight és change_column_types már alkalmazva lettek 2026-07-07 időbélyegekkel.
Ha nem adunk meg migrációs fájlt, a sqlite-utils migrate data.db parancs bejárja a jelenlegi könyvtárat és alkönyvtárakat, és alkalmaz minden megtalált migrations.py fájlban lévő Migrations() példányt. A migrációk Pythonból is futtathatók a migrations.apply(db) hívással, ami hasznos eszközök és CLI-k belső sémakezeléséhez.
Áttérés a sqlite-migrate csomagról
A migrációs mechanika eredetileg külön csomagként, sqlite-migrate néven indult, és három éve szerepel a tervezésben. A funkció mostantól alapértelmezett része lett a sqlite-utils csomagnak; a sqlite-migrate utolsó kiadása átállítja a függőséget sqlite-utils>=4-re és egyszerűen exportálja a Migrations osztályt, így a korábbi sqlite-migrate-függő projekteknek elvileg nincs szükségük módosításra.
Egyéb fontos változások és visszafelé inkompatibilitások
A 4.0 kiadás néhány törést okozó javítást is tartalmazott, ezért kapott nagyobb verziószámot. A jegyzetekből a legfontosabb pontok:
-
Upsert-ek most az SQLite INSERT ... ON CONFLICT ... DO UPDATE SET szintaxist használják; a rendszer automatikusan felismeri a meglévő tábla elsődleges kulcsát és elutasítja azokat a rekordokat, amelyek hiányzó elsődleges kulcsértékekkel próbálnának bekerülni. (PR #652)
-
A db.query() most azonnal végrehajtódik és elutasítja azokat az állításokat, amelyek nem adnak vissza sorokat; írásokhoz és DDL-hez a db.execute() használata javasolt. Ez a talán legzavaróbb visszafelé inkompatibilis változtatás lehet.
-
CSV és TSV importok most alapértelmezetten érzékelik az oszloptípusokat, és beillesztés meglévő táblába megtartja az adott tábla oszloptípusait. (PR #679)
-
table.extract() és extracts= viselkedése megváltozott: többé nem hoznak létre lookup táblarekordot teljesen null értékek esetén. (Issue #186)
Részletes útmutató található az Upgrading from 3.x to 4.0 dokumentumban.
Beágyazott tranzakciók: db.atomic()
A tranzakciók körüli viselkedésen sokáig dolgozott a szerző, mert a könyvtár tervezése 2018-ban indult, és csak most lett egy tisztább modell. A db.atomic() kontextuskezelő Savepoint-alapú működésének köszönhetően a tranzakciók egymásba ágyazhatók: a belső tranzakciók rollback-je nem feltétlenül érinti a külső mentést. Példa használat:
with db.atomic(): db.table("dogs").insert({...}, pk="id") db.table("dogs").insert({...})
Ez növeli a migrációk és egyéb többlépéses műveletek megbízhatóságát.
Összetett idegenkulcsok
A 4.0 immár kezeli a compound foreign key-ek létrehozását, transzformációját és introspekcióját table.foreign_keys segítségével (PR #594). A döntés része volt a kiadásra váró törődéses változások köreinek felmérésének: a compound foreign key-ek későbbi hozzáadása már törést okozott volna, ezért előre beletették.
Fejlesztési és tesztelési folyamat — LLM-segítség
A 4.0 kiadás dokumentációját és az upgrade guide-ot Claude Fable 5, Claude Opus 4.8 és GPT-5.5 készítette. A szerző kiemeli, hogy ezek a modellek hasznosak voltak a hibakeresésben és API-tervezésben: Claude Fable 5 különösen aktívan írt teszt-scripteket, talált több kulcsproblémát és együttesen sok hibát jelzett, amelyeket aztán PR-eken keresztül javítottak.
A Fable 5 által előállított reprodukciós futtatás például 10 jelentősebb problémát hozott felszínre (hibák a tranzakciók kezelésében, query() token-szkennerek kikerülése, autocommit probléma, compound FK-k helytelen rendezése stb.), amelyek mind szerepelnek az érintett javításokban.
A szerző megjegyzi, hogy a modellalapú segítség nélkül a 4.0 valószínűleg kevésbé alapos és több kompromisszumot tartalmazó kiadás lett volna.
Hol érhető el és további források
A részletes kiadási jegyzetek és az előzetes rc/alpha kiadások változáslistái elérhetők a projektben (4.0a0–4.0rc4), és az upgrade guide részletezi a visszafelé inkompatibilis változtatásokat. A migrációs mechanika korábbi csomagja, sqlite-migrate, egy utolsó kiadást kapott, amely átirányítja a Migrations osztályokat a sqlite-utils csomagra.
Összegzés
A sqlite-utils 4.0 mérföldkő a projekt életében: a beépített migrációs rendszer, a beágyazott tranzakciók és az összetett idegenkulcsok támogatása komoly előrelépést jelent a SQLite-alkalmazások hosszú távú karbantartásában. A kiadás néhány visszafelé inkompatibilis változást is hoz, ezért frissítés előtt érdemes áttanulmányozni az Upgrading from 3.x to 4.0 útmutatót.
Tags: schema-migrations, projects, sqlite, ai, sqlite-utils, generative-ai, llms, ai-assisted-programming, anthropic, claude, agentic-engineering, claude-mythos-fable
