SQL, NoSQL und warum ich Kanta DB angefangen habe

Wenn ich heute einen konventionellen Python-Dienst bauen würde, würde ich wahrscheinlich mit PostgreSQL, SQLAlchemy und Alembic anfangen. PostgreSQL gibt mir echte UUIDs, JSONB, Arrays, Transaktionen, Constraints und hervorragendes Indexing. SQLAlchemy bildet das meiste davon sauber auf Python ab. Alembic hält Schemaänderungen explizit und versioniert.

Damit kommt man ziemlich weit, bevor irgendetwas anfängt zu nerven.

… aber das Modell hat seine Ecken

Ein Datenbankschema und eine Python-Datenstruktur sind nicht ganz dasselbe.

Mit SQLAlchemy kann ich typisierte Modelle definieren, uuid.UUID direkt gegen PostgreSQL-UUID-Spalten verwenden, JSONB auf Python-Container abbilden und die meisten Routinekonvertierungen aus meinem eigenen Code heraushalten. Das ist erheblich besser, als jeden Datenbankwert als String zu behandeln oder SQL manuell zusammenzubauen.

Trotzdem wird das ORM-Modell zu einer besonderen Art von Objekt. Es trägt Spalten, Beziehungen, Session-Verhalten und Persistenzregeln in sich. Wenn der Rest des Programms schlichte Anwendungsstrukturen will, lasse ich entweder Datenbankbelange nach außen durchsickern oder füge eine weitere Konvertierungsschicht hinzu.

Das Problem wird sichtbarer, wenn sich das Schema ändert.

Ein Feld zu einer Python-Struktur hinzuzufügen fühlt sich trivial an. Eine Spalte zu persistierten Daten hinzuzufügen bedeutet, das Modell zu ändern und eine Migration zu erstellen. Aufwändigere Änderungen erfordern Datentransformationen und Kompatibilitätsentscheidungen. Alembic handhabt das vernünftig, aber ich muss trotzdem eine Historie struktureller Änderungen pflegen, nur damit alte Zeilen zu neuen Zeilen werden können.

Das ist kein Fehler von PostgreSQL. Die Datenbank hat sich auf ein Schema festgelegt, also hat dessen Änderung Konsequenzen.

Historie erzeugt eine weitere Schicht. Wenn ich wissen will, wer einen Wert geändert hat, wann er ihn geändert hat oder wie der Datensatz letzten Dienstag aussah, muss ich das modellieren. Ich kann Audit-Tabellen, Trigger, Zeitstempelspalten oder eine Event-Sourcing-Schicht hinzufügen. PostgreSQL kann all das ziemlich gut unterstützen.

Aber die normale Zeile repräsentiert weiterhin was jetzt existiert. Die Historie bleibt etwas, das ich darum herum baue.

MongoDB beseitigt etwas Reibung

MongoDB bringt die Form der Daten viel näher an die Form, die ich im Programm verwende.

Ich kann verschachtelte Dokumente direkt speichern, Felder hinzufügen, ohne eine Tabelle zu ändern, und ältere sowie neuere Datensätze koexistieren lassen, während die Anwendung beide versteht. Das macht Schemaevolution oft weniger zeremoniell. Statt zuerst die ganze Datenbank zu migrieren, kann ich manchmal alte Dokumente aktualisieren, wenn ich sie lese oder verändere.

Das Schema existiert trotzdem. Mein Code erwartet weiterhin bestimmte Felder mit bestimmten Bedeutungen. MongoDB gibt mir lediglich mehr Freiheit, wann ich diese Vereinbarung durchsetze.

Redis gibt mir hervorragende Bausteine

Redis ist wunderbar praktisch.

Wenn ich einen Cache, eine Queue, einen Zähler, ein Sorted Set, einen Distributed Lock oder einen flüchtigen gemeinsamen Zustand brauche, hat Redis meist eine kompakte Antwort.

Wenn meine Daten natürlich als JSON oder in einem anderen strukturierten Format ankommen, liegt es auch vollständig an mir, sie auf diese Redis-Primitiven herunterzubrechen oder sie einfach als Ganzes zu dumpen und all die feinen Werkzeuge zu ignorieren.

Lass es mich wissen, wenn jemand meine Daten anfasst

Firebase beginnt bei der Synchronisation

Firebase geht einen direkteren Weg. Seine Datenbanken behandeln Live-Client-Updates als Teil des Produkts.

Ich kann einen Listener an Daten hängen und der Client empfängt Änderungen, sobald sie passieren. Offline-Verhalten und Wiederverbindung gehören ebenfalls zum selben System, statt später als WebSocket-Projekt aufzutauchen.

Das ist attraktiv.

Wir haben alle Änderungen

MongoDB hat hierauf die starke eingebaute Antwort. Change Streams lassen mich eine Collection, eine Datenbank oder ein ganzes Deployment beobachten und Inserts, Updates, Deletes usw. empfangen. Updates enthalten normalerweise die geänderten Felder, und jedes Event trägt ein Resume Token, sodass ich mich neu verbinden und dort weitermachen kann, wo ich aufgehört habe, solange das Oplog diesen Punkt noch enthält.

PostgreSQL kann tatsächliche Datenbankänderungen ebenfalls über Logical Decoding und Replikation bereitstellen. Redis Change Streams bieten eine ähnliche Lösung in diesem Bereich.

Change-Data-Capture-Systeme bauen darauf sehr leistungsfähige Pipelines, aber dann müssen wir SQL-Anweisungen oder Redis-Befehle parsen und den Zustand selbst verfolgen.

Publish und Subscribe

PostgreSQL und Redis bieten außerdem altmodische Message-Channels.

Ich könnte LISTEN/NOTIFY oder PUB/SUB verwenden und eine Benachrichtigung aus derselben Transaktion senden, die die Daten verändert. Das vermeidet einen Teil der Hässlichkeit eines unabhängigen Message Bus.

Aber ich muss trotzdem Benachrichtigungen erstellen und empfangen, um zu entscheiden, was gelesen und was gesendet werden soll. Und es kommt mit Race Conditions zwischen der tatsächlichen Änderung und der Benachrichtigung.

Für mein Problem fühlte es sich an, als würde man ziemlich weit unterhalb der Abstraktion anfangen, die ich eigentlich wollte.

Ich wollte nicht nur wissen, dass sich der Zustand geändert hatte.
Ich wollte die Änderung selbst, und den Zustand davor und danach.

Nachdem ich all das verwendet hatte und immer wieder feststellte, dass das ORM-Kriechen über meine Codebasis unerträglich wurde, begann ich schließlich an einer Idee zu arbeiten, die ich über Jahre und Jahre still entwickelt hatte.

Meine eigene Datenbank zu bauen. Du weißt schon, so etwas, von dem sie dir immer sagen, dass du es nicht einmal versuchen sollst.

Lass das Log die Datenbank sein

Das wurde der Ausgangspunkt für Kanta.

Statt den neuesten Zustand als primären Datensatz zu speichern und Historie darum herum anzufügen, wollte ich Änderungen speichern.

Ein Objekt beginnt mit leerem Zustand. Jede spätere Operation zeichnet nur auf, was sich geändert hat, zusammen mit einem Zeitstempel und allen anderen Metadaten, die zu dieser Änderung gehören.

Der aktuelle Zustand entsteht durch Anwenden des Logs. Jetzt braucht die Historie kein eigenes Schema mehr. Abfragen müssen nicht mehr den jüngsten Zeitstempel finden, weil sie auf dem Zustandsobjekt zu jedem beliebigen Zeitpunkt arbeiten.

Eine Struktur durchgehend

Msgspec gibt mir typisierte, kompakte Datenstrukturen mit sehr schneller Serialisierung. Ähnlich wie Dataclasses oder Pydantic verarbeitet es verschachtelte Strukturen und gängige native Typen wie UUIDs, Enums und Datetimes, ohne die Objekte in ORM-Entities zu verwandeln. Die Definition deiner Datenstrukturen wird so einfach:

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

Das bedeutet, dass ich dieselbe Art von Objekt im gesamten Programm verwenden kann. Ich kann es serialisieren. Ich kann es über das Netzwerk senden. Ich kann seine Änderungen persistieren. Ich kann es auf der anderen Seite rekonstruieren.

Ich brauche keine Klasse für meine Anwendung, eine weitere für SQLAlchemy, ein weiteres Schema für die Serialisierung und kleine Konvertierungsfunktionen, die zwischen all diesen vermitteln.

Ich habe einen einfachen JSONL-Logger zusammengehackt, eine Änderung pro Zeile, mit einem jsondiff-Änderungsdatensatz darauf. Es war kein Binärformat, wie ich es vielleicht bevorzugt hätte, aber es ist etwas, das sich zum Editieren und Debuggen geradezu trivial verhält.

Reads sind einfach Reads aus Python-Variablen, viel schneller als Redis oder jede externe Datenbank!

Writes erforderten zusätzliches Nachdenken. Statt der Datenbank zu sagen, was geändert werden soll, bearbeiten wir den Zustand, und die Datenbank persistiert einen Änderungsdatensatz.

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

Beachte, dass es dort kein async with oder await gibt, obwohl wir mit async Python arbeiten. Die Transaktion ist sofort und synchron. Du brauchst keine Locks oder Synchronisation darum. Die Zustände davor und danach werden gespeichert und verglichen, um das Change-Diff zu erzeugen. Im Fehlerfall wird der vorherige Zustand wiederhergestellt, wobei alles bereits in dieser Transaktion Getane zurückgerollt wird.

Die Änderungen werden von einem Hintergrund-Thread auf die Festplatte persistiert, in eine Append-only-Datei, die sich im Falle von Korruption durch Stromausfall oder Abstürze leicht reparieren lässt.

Das war ungefähr der Punkt, an dem Kanta aufhörte, wie ein Datenbankexperiment auszusehen, und anfing, wie ein kohärentes Modell auszusehen, auf dem man aufbauen kann.

Nachdem ich es mit meinen eigenen Projekten getestet hatte, verdrahtete ich es schnell mit einer ernsthafteren Anwendung, die schwerere Daten und viele Benutzer hatte. Das beantwortete meine Befürchtungen über mögliche Performance-Probleme, denn immerhin verwendeten wir tatsächlich JSON für eine Datenbank, und zwar in einer Logdb-Struktur, die andere meines Wissens seit den frühen Tagen der Computertechnik nicht mehr verwendet hatten.

Wie erwartet wurde das erneute Abspielen großer Changesets beim Anwendungsstart mit der Zeit langsam, also fügte ich vollständige Snapshot-Zeilen hinzu, um die langen Replays ab der initialen Revision zu vermeiden. Danach hat die Performance alle meine Anforderungen übertroffen.

Aber der entscheidende Punkt ist nicht die Performance, sondern die Einfachheit. Indem wir annehmen, dass unsere App in einem einzigen Worker-Prozess leben und den vollständigen Zustand in ihrem Speicher halten kann, beseitigen wir die meisten Probleme, die mit der typischen Datenbank einhergehen.

Dank der Log-Struktur kommt das Zurückspulen der Historie gratis. Ich habe sogar eine Reihe von Transaktionen mitten in der Historie rückgängig gemacht — um einen Benutzer zu retten, der einen Teil des Projekts gelöscht und danach weitere Änderungen vorgenommen hatte.

Diese Website ist ebenfalls auf Kanta gebaut (Pagerite CMS).

Das Single-Process-Modell beseitigt eine Menge Maschinerie, aber es beseitigt nicht die Tatsache, dass sich Software ändert.

Niemand mochte jemals Migrationen. Sie sind die Bürde, Wartungsänderungen an Daten vorzunehmen. Noch eine SQL-Migration oder noch ein Mongo-Legacy-Fallback mit Update-Zweig hinzuzufügen ist einfach zu viel Aufwand, also vermeidet man diese Änderungen lieber.

Auch hier übernimmt msgspec einen Großteil der schweren Arbeit. Wenn wir ein Feld hinzufügen oder entfernen wollen, setzen wir das neue Feld einfach mit einem Standardwert auf die Datenstrukturen oder entfernen ein beliebiges altes Feld. Es migriert stillschweigend in das neue Format. Wenn das zu ladende Format nicht zu den Strukturen passt, bekommen wir einen Fehler, der sagt, was und wo etwas falsch ist.

Cool und einfach, aber nicht ausreichend für eine Datenbank.

Hin und wieder wollen wir ein Feld umbenennen, Datentypen ändern oder die gesamten Daten glatt umstrukturieren, möglicherweise währenddessen neue externe Daten abrufen (habe ich gemacht). Das erfordert eine echte Migrationsfunktion, die weiß, was sie tut.

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

Das Format ist einfach: Die Datenbank-Revisionsnummer kommt direkt aus dem Funktionsnamen. Die Funktion manipuliert das schlichte Dict-Format, sodass wir keine msgspec.Structs älterer Versionen pflegen müssen. Der Docstring liefert die geloggte Beschreibung dessen, was getan wurde.

Um zu vermeiden, den Rest unseres Programms damit zu vermüllen, können die Migrationen in ihr eigenes Python-Modul gelegt werden, auf das wir beim Definieren der Datenbank einfach mit dem Python-Modulpfad verweisen:

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

Die Changeset-Metadaten und Snapshots enthalten die Versionsnummer, die sie repräsentieren, und wir wenden alle gefundenen Migrate-Funktionen aufwärts ab dieser Version an und führen zum Abschluss der Migration in jedem Fall die Msgspec-Konvertierung durch. Falls sich daraus Änderungen ergaben, loggen und speichern wir die durchgeführten Migrationen und erstellen danach einen Snapshot.

Die ältesten Migrationsfunktionen können ebenfalls entfernt werden, wenn solche Versionen nicht mehr unterstützt werden müssen, wodurch dieses gesamte Migrationssystem handhabbar bleibt.

Das Standardformat bleibt bewusst anspruchslos: JSON-Datensätze, einer pro Zeile. Msgspec kodiert Bytes und andere Typen hinein.

Vor der Veröffentlichung wollte ich eine Kritik adressieren, die ich selbst sicherlich am fehlenden Binärsupport üben würde, indem ich diesen als Option implementierte.

Während wir bei JSONL vom Dateiende aus nach Newlines suchen können, um einen Snapshot zu finden, könnten die Binärdaten den Parser verwirren. Wir können vom Dateianfang an lesen für einen vollständig deterministischen Ansatz, aber wenn die Datenbank groß wäre, würden wir es vorziehen, nahe dem Ende zu suchen. Ich wollte außerdem, dass es Append-only bleibt, also konnten wir den Snapshot-Offset nicht einfach an den Anfang schreiben.

Die Lösung ist zweiteilig:

• Unvorhersehbarer zufälliger Nonce als Syncword
• Blake3-Hash zur Integritätsprüfung

Die Change-Payloads selbst sind derzeit mit MessagePack kodiert, das in msgspec ohnehin unterstützt wird.

Ich würde das gerne durch etwas ersetzen, das näher an Protocol Buffers liegt, ohne Feldnamen und -typen überhaupt zu speichern, und dabei ausnutzen, dass msgspec die Struktur und Typen meiner Structs bereits kennt und daher in der Lage sein sollte, aus denselben Informationen eine kompakte Binärrepräsentation abzuleiten.

Das würde die Eigenschaft bewahren, die mir am wichtigsten ist: eine einzige Definition der Datenstruktur, statt eines Python-Modells plus eines ORM-Modells plus eines Serialisierungsschemas.

Den maßgeblichen Zustand im Speicher zu halten, macht etwas anderes schwer zu ignorieren: Die meisten interaktiven Anwendungen halten bereits eine weitere Kopie woanders.

Der Browser hat ebenfalls eine.

Sobald die Datenbank selbst einen geordneten Strom von Änderungen aufzeichnet, wird die Verwendung desselben Stroms zur Synchronisation ein offensichtlicher nächster Schritt.

Stores über WebSocket synchronisieren

Die FastAPI-App sendet Änderungen über einen WebSocket und wendet eingehende Änderungen zurück auf die Datenbank an.

Auf jedem Client pflegen wir eine Schattenkopie, also den zuletzt gesehenen Serverzustand, und den aktuellen Arbeitszustand des Clients in seinem nativen Vue Pinia-Store. Oder Svelte- oder React-Äquivalenten.

Der Store ist das verbindende Glied, das Reaktivität durchgehend von der Datenbank bis zur Benutzeroberfläche und zurück bietet.

Der Client kann offline oder gleichzeitig mit anderen Clients arbeiten, und die Änderungen werden zusammengeführt, wenn sie auf dem Server ankommen, unter Verwendung eines Three-way-Merge mit automatischer Auflösung. Kombiniert mit Überschreiben und Validierung/Ablehnung — wir wollen definitiv nicht, dass Merge-Konflikte eine manuelle Lösung im Git-Stil erfordern.

Diese Maschinerie ist derzeit eher in Anwendungen eingebettet, als dass sie als Teil von Kanta paketiert wäre. Der nächste Schritt ist, sie in ein separates Kanta-kompatibles Synchronisationsmodul zu extrahieren, mit Adaptern auch für die Javascript-Frontends.

Das ist wahrscheinlich ein weiterer Artikel.

All diese Designentscheidungen zählen nur, wenn sie gewöhnlichen Anwendungscode einfacher machen.

Mit Kanta ist die Datenbank nicht etwas, das ich über ein anderes Modell abfrage. Ich definiere den Zustand, den ich will, öffne ihn und arbeite mit normalen Python-Objekten. Reads sind einfach Reads:

user = data.users[user_id]

Wenn ich etwas ändern will, mache ich diese Änderung innerhalb einer Transaktion:

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

Es gibt keine Abfragesprache dazwischen, kein ORM-Objekt, das zurück in mein Anwendungsmodell übersetzt werden muss, und keinen separaten Audit-Code, an den man denken muss. Die Transaktion, Historie, Rollback und Persistenz kommen alle aus derselben Operation.

uv add kanta

Füge es deinem Projekt mit uv hinzu oder lies mehr auf 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())