SQL, NoSQL, ja miksi aloitin Kanta DB:n

Jos rakentaisin tänään tavanomaista Python-palvelua, aloittaisin luultavasti PostgreSQL:llä, SQLAlchemyllä ja Alembicilla. PostgreSQL antaa minulle oikeat UUID:t, JSONB:n, taulukot, transaktiot, rajoitteet ja erinomaisen indeksoinnin. SQLAlchemy kuvaa suurimman osan tästä siististi Pythoniin. Alembic pitää skeemamuutokset eksplisiittisinä ja versioituina.

Tällä pääsee melko pitkälle ennen kuin mikään alkaa ärsyttää minua.

… mutta mallissa on reunaehtoja

Tietokannan skeema ja Python-tietorakenne eivät ole aivan sama asia.

SQLAlchemyllä voin määritellä tyypitettyjä malleja, käyttää uuid.UUID:tä suoraan PostgreSQL:n UUID-sarakkeita vasten, kuvata JSONB:n Python-säiliöihin ja pitää suurimman osan rutiinimuunnoksista poissa omasta koodistani. Tämä on huomattavasti parempaa kuin jokaisen tietokanta-arvon käsitteleminen merkkijonona tai SQL:n manuaalinen kasaaminen.

Siitä huolimatta ORM-mallista tulee eräänlainen erityisolio. Se kantaa sarakkeita, relaatioita, session käyttäytymistä ja pysyvyyden sääntöjä. Jos muu ohjelma haluaa tavallisia sovellusrakenteita, joko annan tietokanta-asioiden levitä ulospäin tai lisään uuden muunnoskerroksen.

Ongelma näkyy selvemmin, kun skeema muuttuu.

Kentän lisääminen Python-rakenteeseen tuntuu triviaalilta. Sarakkeen lisääminen pysyviin tietoihin tarkoittaa mallin muuttamista ja migraation luomista. Monimutkaisemmat muutokset vaativat tietomuunnoksia ja yhteensopivuuspäätöksiä. Alembic hoitaa tämän järkevästi, mutta minun on silti ylläpidettävä historiaa rakenteellisista muutoksista vain jotta vanhat rivit voivat muuttua uusiksi riveiksi.

Tämä ei ole PostgreSQL:n vika. Tietokanta on sitoutunut skeemaan, joten sen muuttamisella on seurauksensa.

Historia luo toisen kerroksen. Jos haluan tietää, kuka muutti arvoa, milloin hän muutti sen tai miltä tietue näytti viime tiistaina, minun on mallinnettava se. Voin lisätä audit-tauluja, triggereitä, aikaleimasarakkeita tai event sourcing -kerroksen. PostgreSQL voi tukea kaikkia näitä melko hyvin.

Mutta tavallinen rivi edustaa edelleen mitä on olemassa nyt. Historia jää joksikin, jonka rakennan sen ympärille.

MongoDB poistaa osan kitkasta

MongoDB siirtää datan muodon paljon lähemmäksi sitä muotoa, jota käytän ohjelmassa.

Voin tallentaa sisäkkäisiä dokumentteja suoraan, lisätä kenttiä muuttamatta taulua ja antaa vanhempien ja uudempien tietueiden elää rinnakkain sovelluksen ymmärtäessä molemmat. Tämä tekee usein skeeman kehittymisestä vähemmän seremoniallista. Sen sijaan että migraoisin koko tietokannan ensin, voin joskus päivittää vanhoja dokumentteja niitä lukiessani tai muuttaessani.

Skeema on silti olemassa. Koodini odottaa edelleen tiettyjä kenttiä tietyillä merkityksillä. MongoDB antaa minulle vain enemmän vapautta sen suhteen, milloin valvon tätä sopimusta.

Redis antaa minulle erinomaisia palasia

Redis on ihmeellisen käytännöllinen.

Jos tarvitsen välimuistin, jonon, laskurin, järjestetyn joukon, hajautetun lukon tai tilapäisen jaetun tilan, Redisillä on yleensä kompakti vastaus.

Tietysti kun datani tulee JSON-muodossa tai muussa jäsennellyssä muodossa, on myös täysin minun tehtäväni pilkkoa se noiksi Redis-primitiiveiksi, tai vain dumpata se sisään kokonaisena sivuuttaen kaikki hienot työkalut.

Kerro minulle, kun joku koskee dataani

Firebase alkaa synkronoinnista

Firebase ottaa suoremman reitin. Sen tietokannat pitävät reaaliaikaisia asiakaspäivityksiä osana tuotetta.

Voin kiinnittää kuuntelijan dataan ja saada asiakkaan vastaanottamaan muutokset niiden tapahtuessa. Offline-käyttäytyminen ja uudelleenyhdistäminen kuuluvat myös samaan järjestelmään sen sijaan että ne ilmestyisivät myöhemmin WebSocket-projektina.

Tämä on houkuttelevaa.

Meillä on kaikki muutokset

MongoDB:llä on vahva sisäänrakennettu vastaus tähän. Change Streams antavat minun seurata kokoelmaa, tietokantaa tai koko asennusta ja vastaanottaa lisäyksiä, päivityksiä, poistoja jne. Päivitykset sisältävät normaalisti muuttuneet kentät, ja jokainen tapahtuma kantaa mukanaan jatkotunnisteen (resume token), joten voin yhdistää uudelleen ja jatkaa siitä mihin jäin niin kauan kuin oplog sisältää vielä tuon pisteen.

PostgreSQL voi myös paljastaa varsinaiset tietokantamuutokset logical decoding:in ja replikoinnin kautta. Redisin Change Streams tarjoavat samanlaisen ratkaisun omassa maailmassaan.

Change-data-capture -järjestelmät rakentavat erittäin kyvykkäitä putkia tämän päälle, mutta silloin meidän täytyy jäsentää SQL-lauseita tai Redis-komentoja ja pitää kirjaa tilasta itse.

Julkaise ja tilaa

PostgreSQL ja Redis tarjoavat myös oldskool-viestikanavat.

Voisin käyttää LISTEN/NOTIFY:tä tai PUB/SUB:ia ja lähettää ilmoituksen samasta transaktiosta, joka muuttaa dataa. Tämä välttää osan erillisen viestiväylän rumuudesta.

Mutta minun on silti luotava ja vastaanotettava ilmoitusviestejä päättääkseni, mitä lukea ja mitä lähettää. Ja mukana tulee kilpailutilanteita varsinaisen muutoksen ja ilmoituksen välillä.

Omaan ongelmaani tämä tuntui aloittamiselta melko kaukana alhaalta sen abstraktion alapuolelta, jonka oikeastaan halusin.

En halunnut pelkästään tietää, että tila oli muuttunut.
Halusin itse muutoksen, sekä tilan ennen ja jälkeen.

Käytettyäni kaikkia yllä olevia ja huomattuani aina ORM:n leviämisen koodipohjaani sietämättömäksi, aloin vihdoin työstää ideaa, jota olin hiljaa kehittänyt vuosien ja vuosien ajan.

Tehdä oma tietokanta. Tiedättehän, sellainen, jota ne aina kehottavat olemaan edes yrittämättä.

Annetaan login olla tietokanta

Siitä tuli Kannan lähtökohta.

Sen sijaan että tallentaisin viimeisimmän tilan ensisijaisena tietueena ja lisäisin historian sen ympärille, halusin tallentaa muutoksia.

Objekti alkaa tyhjästä tilasta. Jokainen myöhempi operaatio tallentaa vain sen, mikä muuttui, yhdessä aikaleiman ja muun muutokseen kuuluvan metadatan kanssa.

Nykyinen tila tulee login soveltamisesta. Nyt historia ei enää tarvitse omaa skeemaansa. Kyselyjen ei enää tarvitse etsiä tuoreinta aikaleimaa, koska ne toimivat tilalla millä tahansa hetkellä.

Yksi rakenne alusta loppuun

Msgspec antaa minulle tyypitettyjä, kompakteja tietorakenteita erittäin nopealla serialisoinnilla. Kuten dataclassit tai Pydantic, se käsittelee sisäkkäiset rakenteet ja yleiset natiivityypit kuten UUID:t, enumit ja datetimet muuttamatta olioita ORM-entiteeteiksi. Tietorakenteiden määrittelystä tulee näin yksinkertaista:

class Data(msgspec.Struct):
    servername: str
    users: dict[UUID, User]   

Tämä tarkoittaa, että voin käyttää samanlaista oliota koko ohjelman läpi. Voin serialisoida sen. Voin lähettää sen verkon yli. Voin pysyväistää sen muutokset. Voin rekonstruoida sen toisella puolella.

En tarvitse yhtä luokkaa sovellukselleni, toista SQLAlchemylle, toista skeemaa serialisoinnille ja pieniä muunnosfunktioita välittämässä niiden kaikkien välillä.

Hakkasin kasaan yksinkertaisen JSONL-lokittajan, yksi muutos per rivi, mukana jsondiff-muutostietue. Se ei ollut binääriformaatti kuten olisin ehkä halunnut, mutta se on jotain naurettavan yksinkertaista muokata ja debugata.

Lukemiset ovat yksinkertaisesti lukemisia Python-muuttujista, paljon nopeampia kuin Redis tai mikä tahansa ulkoinen tietokanta!

Kirjoitukset vaativat lisäajattelua. Sen sijaan että kertoisimme tietokannalle, mitä muuttaa, me muokkaisimme tilaa ja tietokanta tallentaisi muutostietueen.

with kanta.transaction(action="new_user"):
    data.users[uuid7()] = User(...)

Huomaa, ettei siinä ole async with:iä tai await:ia, vaikka työskentelemme async-Pythonin kanssa. Transaktio on välitön ja synkroninen. Et tarvitse mitään lukkoja tai synkronointia sen ympärille. Tilat ennen ja jälkeen tallennetaan ja niitä verrataan muutos-diffin tuottamiseksi. Virheen sattuessa edellinen tila palautetaan, peruttaen kaiken mitä transaktiossa on jo tehty.

Muutokset pysyväistetään levylle taustasäikeen toimesta append-only-tiedostoon, joka on helppo korjata jos virrankatkaisu tai kaatuminen aiheuttaa vaurioita.

Suunnilleen tuossa kohtaa Kanta lakkaa näyttämästä tietokantakokeilulta ja alkoi näyttää yhtenäiseltä mallilta, jonka varaan rakentaa.

Kokeiltuani sitä omissa projekteissani kytkin sen nopeasti vakavampaan sovellukseen, jossa oli raskaampaa dataa ja monta käyttäjää. Tämä vastasi pelkoihini mahdollisista suorituskykyongelmista, koska loppujen lopuksi käytimme itse asiassa JSON:a tietokantana, ja logdb-rakenteessa, jota tietääkseni kukaan ei ollut käyttänyt sitten tietojenkäsittelyn varhaisten aikojen.

Kuten arvata saattoi, suurten muutosjoukkojen toistaminen sovelluksen käynnistyksessä muuttui hitaaksi ajan myötä, joten lisäsin täydet snapshot-rivit välttääkseni pitkät toistot alun revisiosta. Sen jälkeen suorituskyky on ylittänyt kaikki tarpeeni.

Mutta pääasia ei ole suorituskyky, vaan yksinkertaisuus. Ottamalla oletukseksi, että sovelluksemme voi elää yhdessä worker-prosessissa ja ylläpitää koko tilan muistissaan, poistamme suurimman osan ongelmista, jotka liittyvät tyypilliseen tietokantaan.

Lokirakenteen ansiosta historian kelailu taaksepäin tulee ilmaiseksi. Olen jopa perunut sarjan transaktioita historian keskeltä — pelastaakseni käyttäjän, joka oli poistanut osan projektista ja tehnyt sen jälkeen vielä lisämuutoksia.

Tämäkin verkkosivusto on rakennettu Kannan päälle (Pagerite CMS).

Yhden prosessin malli poistaa valtavasti koneistoa, mutta se ei poista sitä tosiasiaa, että ohjelmistot muuttuvat.

Kukaan ei ole koskaan pitänyt migraatioista. Ne ovat se taakka, jonka minkä tahansa ylläpitomuutoksen tekeminen dataan aiheuttaa. Toinen SQL-migraatio tai toinen Mongo-legacy-varaus ja päivityshaara on aivan liikaa vaivaa, joten mieluummin vältät nämä muutokset.

Tässäkin msgspec tekee suurimman osan raskaasta työstä. Jos haluamme lisätä tai poistaa kentän, laita uusi kenttä tietorakenteisiin oletusarvolla, tai poista mikä tahansa vanha kenttä. Se migrautuu äänettömästi uuteen muotoon. Jos ladattava muoto ei täsmää rakenteiden kanssa, saamme virheen, joka kertoo mikä ja missä on vialla.

Siistiä ja yksinkertaista, mutta ei riittävää tietokannalle.

Silloin tällöin haluamme nimetä kentän uudelleen, muuttaa tietotyyppejä tai suorastaan uudelleenjärjestää koko datan, mahdollisesti hakeaksemme samalla uutta ulkoista dataa (olen tehnyt sen). Tämä vaatii varsinaisen migraatiofunktion, joka tietää mitä tekee.

def migrate_v1(d: dict) -> None:
    """Rename counter to total"""
    d["total"] = d["counter"]

Muoto on yksinkertainen: tietokannan revisioluku tulee suoraan funktion nimestä. Funktio manipuloi tavallista dict-muotoa, jotta meidän ei tarvitse ylläpitää vanhempien versioiden msgspec.Structeja. Docstring antaa lokitetun kuvauksen siitä, mitä tehtiin.

Välttääksemme muun ohjelman sotkemisen näillä, migraatiot voidaan laittaa omaan Python-moduuliinsa, johon viitataan yksinkertaisesti Python-moduulipolulla tietokantaa määriteltäessä:

kanta = Kanta("foo.kantadb", migrations="foo.migrations")

Muutosjoukkojen metadata ja snapshotit sisältävät versionumeron, jota ne edustavat, ja sovellamme kaikkia löydettyjä migraatiofunktioita ylöspäin tuosta versiosta, ja migraation viimeistelemiseksi teemme msgspec-muunnoksen joka tapauksessa. Jos jokin tästä tuotti muutoksia, lokitamme ja tallennamme tehdyt migraatiot, ja otamme snapshotin jälkeen.

Vanhimmat migraatiofunktiot voidaan myös poistaa, kun kyseisiä versioita ei enää tarvitse tukea, pitäen koko tämän migraatiojärjestelmän hallittavana.

Oletusformaatti pysyy tarkoituksella yksinkertaisena: JSON-tietueita, yksi per rivi. Msgspec koodaa tavut ja muut tyypit siihen.

Ennen julkaisua halusin vastata kritiikkiin, jonka varmasti itsekin esittäisin binäärituen puutteesta, toteuttamalla sen vaihtoehtona.

Kun JSONL:ssä voimme etsiä rivinvaihtoja tiedoston lopusta löytääksemme snapshotin, binääridata saattaisi sekoittaa parserin. Voimme lukea tiedoston alusta täysin deterministisellä lähestymistavalla, mutta jos tietokanta olisi suuri, haluaisimme hakea läheltä loppua. Halusin myös pitää sen append-only:nä, joten emme voineet yksinkertaisesti kirjoittaa alkuun snapshotin offsettia.

Ratkaisu on kaksiosainen:

• Arvaamaton satunnainen nonce syncwordina
• Blake3-tiiviste eheyden varmistukseen

Itse muutospayloadit on tällä hetkellä koodattu MessagePackilla, jota msgspec tukee valmiiksi.

Haluaisin korvata sen jollain lähempänä Protocol Buffersia, tallentamatta kenttien nimiä ja tyyppejä lainkaan, hyödyntäen sitä, että msgspec jo tietää structieni rakenteen ja tyypit, ja sellaisenaan pitäisi pystyä johtamaan kompakti binääriesitys tuosta samasta tiedosta.

Tämä säilyttäisi ominaisuuden, josta välitän eniten: yksi tietorakenteen määritelmä, sen sijaan että olisi Python-malli plus ORM-malli plus serialisointiskeema.

Kun auktoritatiivinen tila pidetään muistissa, toinen asia on vaikea sivuuttaa: useimmat interaktiiviset sovellukset pitävät jo toista kopiota jossain muualla.

Selaimessakin on yksi.

Kun tietokanta itse tallentaa järjestetyn muutosvirran, saman virran käyttäminen synkronointiin muuttuu ilmeiseksi seuraavaksi askeleeksi.

Storejen synkronointi WebSocketin yli

FastAPI-sovellus lähettää muutoksia WebSocketin yli ja soveltaa saapuvat muutokset takaisin tietokantaan.

Jokaisella asiakkaalla ylläpidämme varjokopiota, eli viimeksi nähtyä palvelintilaa, ja asiakkaan nykyistä työtilaa sen omassa Vue Pinia -storessa. Tai Svelte- tai React-vastaavissa.

Store on yhdistävä lenkki, joka tarjoaa reaktiivisuuden koko matkan tietokannasta käyttöliittymään ja takaisin.

Asiakas voi työskennellä offlinessa tai samanaikaisesti muiden asiakkaiden kanssa, ja muutokset yhdistetään kun ne saapuvat palvelimelle, käyttäen kolmitie-yhdistämistä automaattisella ratkaisulla. Yhdistettynä ylikirjoitukseen ja validointiin/hylkäämiseen — emme todellakaan halua, että merge-konfliktit vaativat manuaalista git-tyylistä ratkaisua.

Tällä hetkellä tämä koneisto on upotettuna sovelluksiin sen sijaan että se olisi paketoituna osaksi Kantaa. Seuraava askel on irrottaa se erilliseksi Kanta-yhteensopivaksi synkronointimoduuliksi, sovittimilla myös Javascript-frontendeille.

Se on luultavasti toinen artikkeli.

Kaikilla näillä suunnitteluvalinnoilla on väliä vain, jos ne tekevät tavallisesta sovelluskoodista yksinkertaisempaa.

Kannan kanssa tietokanta ei ole jotain, jota kyselen toisen mallin kautta. Määrittelen haluamani tilan, avaan sen ja työskentelen tavallisten Python-olioiden kanssa. Lukemiset ovat vain lukemisia:

user = data.users[user_id]

Kun haluan muuttaa jotain, teen muutoksen transaktion sisällä:

with kanta.transaction(action="update"):
    data.users[user_id].name = "Alice"

Välissä ei ole kyselykieltä, ei ORM-oliota käännettäväksi takaisin sovellusmalliini, eikä erillistä audit-koodia muistettavaksi. Transaktio, historia, rollback ja pysyvyys tulevat kaikki samasta operaatiosta.

uv add kanta

Lisää se projektiisi uv:lla tai lue lisää osoitteessa git.zi.fi.

uv run --with kanta demo.py

import asyncio, msgspec
from kanta import Kanta, configure_logging

# For demonstration purposes, we use "original v0" and "modified v1" in this same script
# Normally your app would only have the latest supported data model

class Data(msgspec.Struct):  # type: ignore - intentionally redefined later
    users: dict[str, dict] = {}
    counter: int = 0

kanta_v0 = Kanta("demo.kantadb", Data())

@kanta_v0.bootstrap
def bootstrap(data: Data) -> None:
    """Create the initial admin user."""
    data.users["userid001"] = {"name": "Alice", "role": "admin"}


# Redefinition to simulate new version
class Data(msgspec.Struct):
    users: dict[str, dict] = {}
    total: int = 0  # Replaces old counter field
    lang: str = "en"  # New field

def migrate_v1(d: dict) -> None:
    """Rename counter to total"""
    d["total"] = d["counter"]

kanta_v1 = Kanta("demo.kantadb", Data(), migrations="demo")

@kanta_v1.logfmt
def resolve_user(value: str, path: str, state: dict) -> str | None:
    """Resolve user ids to names from the database state itself."""
    if path != "$user" and not path.startswith("users."):
        return None
    return state.get("users", {}).get(value, {}).get("name")


async def main() -> None:
    print("Database creation with v0 schema and basic transactions:\n")
    # Open and close automatically; you can also `await kanta.open()` instead
    async with kanta_v0 as kanta:
        with kanta.transaction(action="create", user="userid001") as data:
            data.users["userid002"] = {"name": "Bob", "role": "user"}

        with kanta.transaction(action="update", user="userid001") as data:
            data.users["userid002"]["role"] = "editor"
            data.counter = 1

        # Display-only extra string, appended after the action.
        with kanta.transaction(action="export", user="userid002", extra="(we are still v0)") as data:
            data.counter = 2

    print("\nA new data model, migrations and logfmt pretty names:\n")
    async with kanta_v1 as kanta:
        with kanta.transaction(action="update", user="userid002", extra="(new version)") as data:
            data.total += 1

        try:
            with kanta.transaction(action="reset", user="userid001") as data:
                data.total = 99
                raise ValueError("simulated failure")
        except ValueError:
            print(f"\nReset rolled back: {data.total=} (we can always read data without tx)\n")

        with kanta.transaction(action="delete", user="userid002") as data:
            data.users.pop("userid001", None)  # del if exists

if __name__ == "__main__":
    configure_logging(debug=True)
    asyncio.run(main())