DEV Community: Aleksei Aleinikov

JWT Explained: What a JSON Web Token Is and How It Breaks

Aleksei Aleinikov — Mon, 26 Oct 2026 08:00:00 +0000

Almost every login you use today ends with a JSON Web Token. The identity provider hands one to your app, the app sends it with every API call, and the API trusts it without asking anyone. That last part is the whole point of a JWT, and also the reason a small mistake in how it is checked turns into “anyone can be admin”.

This guide explains what a JWT is, part by part, how a server should verify one, which signing algorithm to pick, and the attacks that still work against real systems. Every example token in it can be pasted into the free JWT decoder and security analyzer, which runs entirely in your browser.

What is a JWT? A JSON Web Token example

A JWT (JSON Web Token, pronounced “jot”) is a compact, URL-safe string that carries a set of claims and a signature over them. It is defined in RFC 7519; the signing and encryption formats underneath it are JWS (RFC 7515) and JWE (RFC 7516).

A signed JWT has three parts separated by dots:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzQyIiwicm9sZSI6ImVkaXRvciIsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MjI2NTAwfQ.92XVsnsq7eHmUoHn1v4cCfyufbIv5l0Pm8L_Ec6PDH8

Decode the first two parts from base64url and you get two ordinary JSON objects:

header


{ "alg": "HS256", "typ": "JWT" }

payload


{ "sub": "user_42", "role": "editor", "iat": 1767225600, "exp": 1767226500 }

The third part is the signature : 32 bytes of HMAC-SHA256 over header.payload, computed with a secret only the issuer knows. Change one character of the payload, for example "role": "admin", and the signature no longer matches.

That is all a JWT is: claims plus proof of who wrote them. The interesting part is everything around it.

Anatomy of a JSON Web Token

Two readable JSON objects and one signature that binds them to a key.

The header

The header says how to verify the token. The fields that matter:

Field	Meaning	Watch out for
`alg`	Signing algorithm: `HS256`, `RS256`, `ES256`, `EdDSA`…	`none`, or an algorithm your server never issues
`typ`	Token type: `JWT`, or `at+jwt` for OAuth access tokens (RFC 9068)	Missing type makes token confusion easier
`kid`	Key ID: which key in the issuer’s key set signed it	Treated as a file path or SQL value
`jku`, `x5u`	URL of a key set or certificate	Fetched blindly by the verifier
`jwk`	A public key embedded in the token itself	Trusted as the verification key

The payload: claims

The payload is a JSON object of claims. RFC 7519 registers seven of them; everything else is up to the issuer.

Claim	Name	What the verifier does with it
`iss`	Issuer	Must match the identity provider you trust
`sub`	Subject	The user or client the token is about
`aud`	Audience	Must contain your API’s identifier
`exp`	Expiration time	Reject after this moment
`nbf`	Not before	Reject before this moment
`iat`	Issued at	Age checks, debugging
`jti`	JWT ID	Unique ID for one-time use or revocation

Times are NumericDate : whole seconds since 1970-01-01 UTC. A surprising number of bugs come from writing milliseconds (Date.now() in JavaScript) instead: the token then expires tens of thousands of years from now.

The signature

For HS256 the signature is:

HMAC-SHA256( base64url(header) + "." + base64url(payload), secret )

For RS256, ES256 or EdDSA it is a public-key signature over the same input. Either way it covers the encoded header and payload, so the server verifies exactly the bytes it received.

Signed is not encrypted

Base64url is an encoding, not encryption. Anyone holding a JWT can read every claim in it, no key needed:

Terminal window


node -e 'console.log(JSON.parse(Buffer.from(process.argv[1].split(".")[1], "base64url")))' "$TOKEN"

This is the most common misunderstanding about JWTs, and it has consequences. Tokens end up in browser storage, logs, analytics, crash reports and proxy caches. Whatever you put in the payload, you are publishing to all of them.

A JWT is a boarding pass. Anyone who sees it can read the name on it, whoever holds it gets on board, and only the issuer can print the seal that makes it valid.

So keep the payload to identifiers and permissions. No passwords, API keys, card numbers or personal data beyond what the API needs. If the content really must be confidential, use an encrypted JWT ( JWE , five dot-separated parts instead of three), or keep the data on the server and put an opaque ID in the token.

How to verify a JWT correctly

Decoding tells you what a token claims. Verifying tells you whether to believe it. Verification is a checklist, and the order matters: each step closes a specific attack.

Most JWT breaches skip one of these steps; none of them break the cryptography.

Bound the input. Reject tokens above a sane size before parsing.
Pin the algorithm. Accept only the algorithms you actually issue, configured on the server. Never let the token’s alg choose.
Choose the key yourself. Look the kid up in your key set (a JWKS from your identity provider). Ignore jwk, jku and x5u from the token.
Check the signature.
Check time: exp and nbf, with a small clock tolerance (30–60 seconds), and require exp to be present.
Check context: iss is your identity provider, aud contains your API, typ is what this endpoint expects.

With a maintained library this is a few lines. In Node.js with jose:

verify.js


import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL('https://auth.example.com/.well-known/jwks.json'));

const { payload } = await jwtVerify(token, jwks, {

    algorithms: ['ES256'],

    issuer: 'https://auth.example.com',

    audience: 'https://api.example.com',

    typ: 'at+jwt',

    clockTolerance: 30,

});

And in Python with PyJWT:

verify.py


import jwt

jwks = jwt.PyJWKClient("https://auth.example.com/.well-known/jwks.json")

key = jwks.get_signing_key_from_jwt(token).key

claims = jwt.decode(

    token, key,

    algorithms=["ES256"],

    issuer="https://auth.example.com",

    audience="https://api.example.com",

    leeway=30,

    options={"require": ["exp", "iat", "iss", "aud", "sub"]},

)

The highlighted lines are the security. Delete any one of them and the code still “works” in every test, which is exactly why they get deleted.

Warning

Never call a decode function to read claims and make an authorization decision on them. Functions named decode in many libraries skip the signature check by design or by flag. Only claims returned by a successful verify are facts.

HS256 vs RS256 vs ES256: which algorithm?

The real question is not speed or key length. It is who can mint tokens.

With a shared secret, every verifier is also a potential issuer.

Algorithm	Type	Signature size	Use it when
HS256	HMAC, shared secret	32 bytes	One service issues and verifies its own tokens
RS256	RSA PKCS#1 v1.5	256 bytes (2048-bit key)	Broadest library support; most identity providers default to it
PS256	RSA-PSS	256 bytes (2048-bit key)	RSA, with the more modern padding
ES256	ECDSA P-256	64 bytes	Small tokens, wide support; a good default for new systems
EdDSA	Ed25519	64 bytes	Simplest safe signatures, where your libraries support it

With HS256 the verification key is the signing key. If five microservices verify tokens, five services hold a secret that lets them create a token for any user, and a leak from the least protected one compromises all of them. With an asymmetric algorithm only the identity provider holds the private key; services fetch the public keys from a JWKS URL, and you can rotate keys by publishing a new kid.

If you do use HS256, the secret must be random and long: RFC 7518 requires a key at least as long as the hash output (256 bits for HS256), and RFC 8725 says human-memorable passwords must not be used as HMAC keys.

Terminal window


openssl rand -base64 32

Six JWT attacks that still work

None of these break HMAC, RSA or ECDSA. They exploit the verifier: code that trusts the token to explain how it should be trusted. Tim McLean’s 2015 write-up of critical vulnerabilities in JWT libraries made the first two famous, and they are still found in custom code and old dependencies.

1. `alg: none`

JWS defines an “unsecured” algorithm called none with an empty signature. An attacker takes a valid token, changes the payload, sets "alg": "none", removes the signature and keeps the trailing dot. A verifier that honours the header accepts it. Variants such as None or nOnE slip past naive string checks.

Fix: an explicit algorithm allow-list on the server, as in the code above.

2. Algorithm confusion (RS256 to HS256)

The server expects RS256 and verifies with the issuer’s public key. The attacker changes alg to HS256 and signs the token with HMAC, using that public key, which is public, as the secret. A library that picks the algorithm from the header now runs HMAC with the same key bytes, and the forged token verifies.

Fix: pin the algorithm, and use libraries that bind a key to one algorithm type.

3. Weak HMAC secrets

An HS256 token is an offline puzzle: anyone with one token can test candidate secrets without touching your server. secret, changeme, the framework’s sample value, or your-256-bit-secret copied from a tutorial fall in seconds; hashcat even has a dedicated mode for JWTs (16500).

Fix: a random 256-bit secret from a secret manager, or move to an asymmetric algorithm.

4. Key injection through the header

jwk embeds a public key in the token, and jku or x5u point to a URL where the key can be found. A verifier that uses them lets the attacker sign with their own key and supply the matching public key. kid is subtler: it is just a string, and code that uses it as a file path (../../dev/null) or inside a SQL query turns it into path traversal or injection.

Fix: take keys only from your own configured key set; treat kid as an opaque lookup key. RFC 8725 calls this out explicitly: do not trust received claims.

5. Missing audience and issuer checks

Your company has two APIs that trust the same identity provider. A token issued for the low-risk one is replayed against the payments API, and it verifies, because the signature and expiry are fine. Nobody checked aud.

Fix: every API checks that aud names it and that iss is the expected issuer. Use explicit typ values so an ID token cannot be used as an access token.

6. Tokens that live forever

A token without exp, or with a lifetime of months, is a long-lived password that cannot be changed. A stolen one keeps working after the user logs out, changes their password or leaves the company.

Fix: access tokens measured in minutes, exp required by the verifier, and rotating refresh tokens that the server can revoke.

Library bugs exist too: in 2022 Java’s ECDSA implementation (versions 15 to 18) accepted an all-zero signature as valid for any message, which made every ES256 token forgeable on unpatched runtimes (CVE-2022-21449, “Psychic Signatures”). Keeping crypto runtimes and JWT libraries patched is part of the checklist.

JWT decoder: read a token without leaking it

A JWT is a bearer credential : whoever holds an unexpired production token can usually call your API as that user. Pasting one into a random website that uploads it to a server is handing it over.

Three safe options:

Command line: the Node.js one-liner above, or your language’s equivalent. Nothing leaves the machine.
A local browser decoder: the JWT decoder and security analyzer on this site decodes, verifies and audits tokens with Web Crypto in the page itself; tokens, secrets and keys are never uploaded, stored or put into the URL.
Expired or test tokens , when you only need to see the structure.

Here is what the analyzer reports for a token signed with your-256-bit-secret, the sample secret that circulates in countless tutorials:

The analyzer tries more than 100 well-known secrets locally and explains every finding with a fix.

It flags the forgeable signature first, then the multi-year lifetime and the missing iss and aud, and gives a fix for each. Paste the issuer’s public key or JWKS and it verifies RS256, PS256, ES256 and EdDSA signatures as well. If you work with AI agents, the same analysis is exposed to them as a WebMCP tool, analyze_jwt.

JWT vs session cookies: when to use a JWT

JWTs are popular enough that they get used where a session would be simpler. An honest comparison:

	Server-side session	JWT
State	Stored on the server, cookie holds an ID	Self-contained, verified with a key
Revocation	Instant: delete the session	Waits for `exp`, unless you add server state
Scaling	Needs a shared session store	Any service with the public key can verify
Across services and domains	Awkward	What it was designed for
Size per request	A few dozen bytes	Hundreds of bytes to several KB

Use a session for a classic web app with one backend. Use JWTs when several services, an API gateway or third parties must verify identity without a shared store, and wherever OAuth 2.0 and OpenID Connect already hand you one: ID tokens are always JWTs, and many access tokens are.

JWT vs OAuth

They are not alternatives. OAuth 2.0 is a protocol for getting an access token on a user’s behalf; a JWT is a token format. An OAuth access token can be a JWT (RFC 9068 standardises that profile, with typ: at+jwt) or an opaque random string the API checks with the authorization server. OpenID Connect, the identity layer on top of OAuth, always uses a JWT for the ID token.

The two combine well. For browser apps, the safest place for a JWT is an HttpOnly cookie, not localStorage; the details, including CSRF protection, are in why you should stop storing JWTs in localStorage. If you run your own identity provider, Keycloak or Authentik will issue and sign the tokens for you, and a stronger login in front of them, such as passkeys, protects the moment a token is created.

The HMAC behind HS256 is the same primitive that signs webhooks; webhook signatures face the same rules about secret strength and constant-time comparison.

The Bottom Line

A JWT is a readable JSON document with a signature. The format is simple and the cryptography is sound; what fails in practice is the code around it. Pin the algorithm, choose the key yourself, require exp, check iss and aud, keep tokens short-lived and keep secrets out of the payload. Do that with a maintained library, and a JWT is one of the most convenient credentials you can hand out.

And the next time you need to see what is inside one, decode it locally, not in a page that uploads it.

Originally published at alekseialeinikov.com

JWT erklärt: Was ein JSON Web Token ist und wie es bricht

Aleksei Aleinikov — Mon, 26 Oct 2026 08:00:00 +0000

Fast jeder Login, den Sie heute nutzen, endet mit einem JSON Web Token. Der Identity Provider gibt Ihrer App eines, die App schickt es bei jedem API-Aufruf mit, und die API vertraut ihm, ohne jemanden zu fragen. Genau das ist der Sinn eines JWT, und genau deshalb wird aus einem kleinen Fehler bei der Prüfung schnell „jeder kann Admin sein”.

Dieser Leitfaden erklärt, was ein JWT ist, Teil für Teil, wie ein Server es prüfen sollte, welcher Signaturalgorithmus passt und welche Angriffe auf reale Systeme heute noch funktionieren. Jedes Beispiel-Token lässt sich in den kostenlosen JWT-Decoder mit Security-Analyse einfügen, der vollständig im Browser läuft.

Was ist ein JWT? Ein JSON Web Token als Beispiel

Ein JWT (JSON Web Token, ausgesprochen wie das englische „jot”) ist ein kompakter, URL-sicherer String, der eine Menge von Claims und eine Signatur darüber trägt. Definiert ist es in RFC 7519; die Formate für Signatur und Verschlüsselung darunter heißen JWS (RFC 7515) und JWE (RFC 7516).

Ein signiertes JWT hat drei Teile, getrennt durch Punkte:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzQyIiwicm9sZSI6ImVkaXRvciIsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MjI2NTAwfQ.92XVsnsq7eHmUoHn1v4cCfyufbIv5l0Pm8L_Ec6PDH8

Dekodiert man die ersten beiden Teile aus Base64url, erhält man zwei gewöhnliche JSON-Objekte:

header


{ "alg": "HS256", "typ": "JWT" }

payload


{ "sub": "user_42", "role": "editor", "iat": 1767225600, "exp": 1767226500 }

Der dritte Teil ist die Signatur : 32 Byte HMAC-SHA256 über header.payload, berechnet mit einem Secret, das nur der Aussteller kennt. Ändert man ein Zeichen der Payload, etwa "role": "admin", passt die Signatur nicht mehr.

Mehr ist ein JWT nicht: Claims plus Beweis, wer sie geschrieben hat. Spannend ist alles drumherum.

Aufbau eines JSON Web Tokens

Zwei lesbare JSON-Objekte und eine Signatur, die sie an einen Schlüssel bindet.

Der Header

Der Header sagt, wie das Token zu prüfen ist. Die wichtigen Felder:

Feld	Bedeutung	Vorsicht bei
`alg`	Signaturalgorithmus: `HS256`, `RS256`, `ES256`, `EdDSA` …	`none` oder einem Algorithmus, den Ihr Server nie ausstellt
`typ`	Tokentyp: `JWT` oder `at+jwt` für OAuth-Access-Tokens (RFC 9068)	Ohne Typ werden Token-Verwechslungen leichter
`kid`	Key ID: welcher Schlüssel aus dem Key Set signiert hat	Verwendung als Dateipfad oder SQL-Wert
`jku`, `x5u`	URL eines Key Sets oder Zertifikats	Wird vom Verifier blind abgerufen
`jwk`	Öffentlicher Schlüssel direkt im Token	Wird als Prüfschlüssel vertraut

Die Payload: Claims

Die Payload ist ein JSON-Objekt aus Claims. RFC 7519 registriert sieben davon; alles andere legt der Aussteller fest.

Claim	Name	Was der Verifier damit tut
`iss`	Issuer (Aussteller)	Muss zum vertrauenswürdigen Identity Provider passen
`sub`	Subject	Der Nutzer oder Client, um den es geht
`aud`	Audience (Zielgruppe)	Muss die Kennung Ihrer API enthalten
`exp`	Expiration Time	Nach diesem Zeitpunkt ablehnen
`nbf`	Not Before	Vor diesem Zeitpunkt ablehnen
`iat`	Issued At	Altersprüfung, Debugging
`jti`	JWT ID	Eindeutige ID für Einmalnutzung oder Widerruf

Zeiten sind NumericDate : ganze Sekunden seit 1970-01-01 UTC. Erstaunlich viele Fehler entstehen, weil Millisekunden geschrieben werden (Date.now() in JavaScript): Das Token läuft dann erst in Zehntausenden Jahren ab.

Die Signatur

Bei HS256 lautet die Signatur:

HMAC-SHA256( base64url(header) + "." + base64url(payload), secret )

Bei RS256, ES256 oder EdDSA ist es eine Public-Key-Signatur über dieselbe Eingabe. In beiden Fällen deckt sie den kodierten Header und die Payload ab, der Server prüft also genau die Bytes, die er erhalten hat.

Signiert ist nicht verschlüsselt

Base64url ist eine Kodierung, keine Verschlüsselung. Wer ein JWT hat, liest jeden Claim, ganz ohne Schlüssel:

Terminal window


node -e 'console.log(JSON.parse(Buffer.from(process.argv[1].split(".")[1], "base64url")))' "$TOKEN"

Das ist das häufigste Missverständnis rund um JWTs, und es hat Folgen. Tokens landen im Browser-Speicher, in Logs, Analytics, Crash-Reports und Proxy-Caches. Was in der Payload steht, veröffentlichen Sie an alle diese Orte.

Ein JWT ist eine Bordkarte. Wer sie sieht, liest den Namen darauf, wer sie hält, steigt ein, und nur der Aussteller kann das Siegel drucken, das sie gültig macht.

Die Payload also auf Kennungen und Berechtigungen beschränken. Keine Passwörter, API-Keys, Kartennummern und keine personenbezogenen Daten über das hinaus, was die API braucht. Muss der Inhalt wirklich vertraulich sein, ein verschlüsseltes JWT ( JWE , fünf statt drei Teile) verwenden oder die Daten auf dem Server halten und eine undurchsichtige ID ins Token schreiben.

Wie man ein JWT richtig prüft

Dekodieren zeigt, was ein Token behauptet. Prüfen entscheidet, ob man es glaubt. Die Prüfung ist eine Checkliste, und die Reihenfolge zählt: Jeder Schritt schließt einen bestimmten Angriff.

Die meisten JWT-Vorfälle überspringen einen dieser Schritte; keiner bricht die Kryptografie.

Eingabe begrenzen. Übergroße Tokens vor dem Parsen ablehnen.
Algorithmus festlegen. Nur die Algorithmen akzeptieren, die Sie tatsächlich ausstellen, konfiguriert auf dem Server. Nie das alg des Tokens entscheiden lassen.
Den Schlüssel selbst wählen. Die kid im eigenen Key Set nachschlagen (ein JWKS Ihres Identity Providers). jwk, jku und x5u aus dem Token ignorieren.
Signatur prüfen.
Zeit prüfen: exp und nbf mit kleiner Toleranz für Uhrabweichungen (30–60 Sekunden), und exp als Pflichtfeld verlangen.
Kontext prüfen: iss ist Ihr Identity Provider, aud enthält Ihre API, typ ist das, was dieser Endpunkt erwartet.

Mit einer gepflegten Bibliothek sind das wenige Zeilen. In Node.js mit jose:

verify.js


import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL('https://auth.example.com/.well-known/jwks.json'));

const { payload } = await jwtVerify(token, jwks, {

    algorithms: ['ES256'],

    issuer: 'https://auth.example.com',

    audience: 'https://api.example.com',

    typ: 'at+jwt',

    clockTolerance: 30,

});

Und in Python mit PyJWT:

verify.py


import jwt

jwks = jwt.PyJWKClient("https://auth.example.com/.well-known/jwks.json")

key = jwks.get_signing_key_from_jwt(token).key

claims = jwt.decode(

    token, key,

    algorithms=["ES256"],

    issuer="https://auth.example.com",

    audience="https://api.example.com",

    leeway=30,

    options={"require": ["exp", "iat", "iss", "aud", "sub"]},

)

Die hervorgehobenen Zeilen sind die Sicherheit. Streicht man eine davon, „funktioniert” der Code in jedem Test weiter, und genau deshalb werden sie gestrichen.

Achtung

Nie eine Decode-Funktion aufrufen, um Claims zu lesen und darauf eine Berechtigungsentscheidung zu stützen. Funktionen namens decode überspringen in vielen Bibliotheken die Signaturprüfung, absichtlich oder per Flag. Nur Claims aus einem erfolgreichen Verify sind Fakten.

HS256 vs. RS256 vs. ES256: welcher Algorithmus?

Die eigentliche Frage ist nicht Geschwindigkeit oder Schlüssellänge, sondern wer Tokens ausstellen kann.

Mit einem gemeinsamen Secret ist jeder Prüfer auch ein möglicher Aussteller.

Algorithmus	Typ	Signaturgröße	Einsetzen, wenn
HS256	HMAC, gemeinsames Secret	32 Byte	Ein Dienst seine eigenen Tokens ausstellt und prüft
RS256	RSA PKCS#1 v1.5	256 Byte (2048-Bit-Schlüssel)	Breiteste Unterstützung; Standard der meisten Identity Provider
PS256	RSA-PSS	256 Byte (2048-Bit-Schlüssel)	RSA mit dem moderneren Padding
ES256	ECDSA P-256	64 Byte	Kleine Tokens, breite Unterstützung; guter Standard für neue Systeme
EdDSA	Ed25519	64 Byte	Einfachste sichere Signaturen, wo Ihre Bibliotheken es unterstützen

Bei HS256 ist der Prüfschlüssel der Signaturschlüssel. Prüfen fünf Microservices Tokens, halten fünf Dienste ein Secret, mit dem sie für jeden beliebigen Nutzer ein Token erzeugen können, und ein Leck im am schlechtesten geschützten Dienst kompromittiert alle. Mit einem asymmetrischen Verfahren hält nur der Identity Provider den privaten Schlüssel; Dienste holen die öffentlichen Schlüssel von einer JWKS-URL, und Schlüsselrotation bedeutet einfach eine neue kid.

Wer HS256 nutzt, braucht ein zufälliges, langes Secret: RFC 7518 verlangt einen Schlüssel mindestens so lang wie die Hash-Ausgabe (256 Bit bei HS256), und RFC 8725 schließt merkbare Passwörter als HMAC-Schlüssel aus.

Terminal window


openssl rand -base64 32

Sechs JWT-Angriffe, die heute noch funktionieren

Keiner davon bricht HMAC, RSA oder ECDSA. Sie nutzen den Verifier aus: Code, der dem Token glaubt, wie es geprüft werden will. Tim McLeans Analyse kritischer Schwachstellen in JWT-Bibliotheken von 2015 hat die ersten beiden berühmt gemacht, und sie tauchen in Eigenbau-Code und alten Abhängigkeiten immer noch auf.

1. `alg: none`

JWS definiert einen „ungesicherten” Algorithmus namens none mit leerer Signatur. Ein Angreifer nimmt ein gültiges Token, ändert die Payload, setzt "alg": "none", entfernt die Signatur und lässt den letzten Punkt stehen. Ein Verifier, der dem Header folgt, akzeptiert es. Varianten wie None oder nOnE rutschen an naiven Stringvergleichen vorbei.

Fix: eine explizite Allow-List der Algorithmen auf dem Server, wie im Code oben.

2. Algorithm Confusion (RS256 zu HS256)

Der Server erwartet RS256 und prüft mit dem öffentlichen Schlüssel des Ausstellers. Der Angreifer ändert alg auf HS256 und signiert das Token per HMAC mit genau diesem öffentlichen Schlüssel als Secret, der ja öffentlich ist. Eine Bibliothek, die den Algorithmus aus dem Header nimmt, rechnet nun HMAC mit denselben Schlüssel-Bytes, und das gefälschte Token ist gültig.

Fix: den Algorithmus festlegen und Bibliotheken nutzen, die einen Schlüssel an genau einen Algorithmustyp binden.

3. Schwache HMAC-Secrets

Ein HS256-Token ist ein Offline-Rätsel: Wer ein Token hat, kann Kandidaten-Secrets testen, ohne Ihren Server zu berühren. secret, changeme, der Beispielwert des Frameworks oder your-256-bit-secret aus einem Tutorial fallen in Sekunden; hashcat hat sogar einen eigenen Modus für JWTs (16500).

Fix: ein zufälliges 256-Bit-Secret aus einem Secret Manager oder der Wechsel zu einem asymmetrischen Verfahren.

4. Schlüssel-Injection über den Header

jwk bettet einen öffentlichen Schlüssel ins Token ein, jku oder x5u zeigen auf eine URL mit dem Schlüssel. Ein Verifier, der sie nutzt, lässt den Angreifer mit dem eigenen Schlüssel signieren und den passenden öffentlichen Schlüssel gleich mitliefern. kid ist subtiler: Es ist nur ein String, und Code, der ihn als Dateipfad (../../dev/null) oder in einer SQL-Abfrage verwendet, macht daraus Path Traversal oder Injection.

Fix: Schlüssel nur aus dem eigenen, konfigurierten Key Set nehmen; kid als undurchsichtigen Lookup-Schlüssel behandeln. RFC 8725 sagt es ausdrücklich: empfangenen Claims nicht vertrauen.

5. Fehlende Prüfung von Audience und Issuer

Ihr Unternehmen hat zwei APIs, die demselben Identity Provider vertrauen. Ein Token für die harmlose API wird gegen die Payment-API wiederverwendet und ist gültig, denn Signatur und Ablauf stimmen. Niemand hat aud geprüft.

Fix: Jede API prüft, dass aud sie selbst nennt und iss der erwartete Aussteller ist. Explizite typ-Werte verhindern, dass ein ID-Token als Access Token durchgeht.

6. Tokens, die ewig leben

Ein Token ohne exp oder mit Monaten Laufzeit ist ein langlebiges Passwort, das sich nicht ändern lässt. Ein gestohlenes funktioniert weiter, nachdem sich der Nutzer abmeldet, sein Passwort ändert oder das Unternehmen verlässt.

Fix: Access Tokens mit Laufzeiten in Minuten, exp als Pflichtfeld im Verifier und rotierende Refresh Tokens, die der Server widerrufen kann.

Auch Bibliotheksfehler kommen vor: 2022 akzeptierte die ECDSA-Implementierung von Java (Versionen 15 bis 18) eine Signatur aus lauter Nullen als gültig für jede Nachricht. Damit war auf ungepatchten Laufzeitumgebungen jedes ES256-Token fälschbar (CVE-2022-21449, „Psychic Signatures”). Krypto-Laufzeiten und JWT-Bibliotheken aktuell zu halten, gehört zur Checkliste.

JWT-Decoder: ein Token lesen, ohne es preiszugeben

Ein JWT ist ein Bearer-Credential : Wer ein gültiges Produktions-Token hat, kann meist Ihre API im Namen dieses Nutzers aufrufen. Es in irgendeine Website einzufügen, die es an einen Server hochlädt, heißt, es zu verschenken.

Drei sichere Wege:

Kommandozeile: der Node.js-Einzeiler oben oder das Pendant Ihrer Sprache. Nichts verlässt den Rechner.
Ein lokaler Browser-Decoder: Der JWT-Decoder mit Security-Analyse auf dieser Website dekodiert, prüft und auditiert Tokens mit Web Crypto direkt in der Seite; Tokens, Secrets und Schlüssel werden nie hochgeladen, gespeichert oder in die URL geschrieben.
Abgelaufene oder Test-Tokens , wenn Sie nur die Struktur sehen wollen.

So sieht der Bericht für ein Token aus, das mit your-256-bit-secret signiert wurde, dem Beispiel-Secret aus unzähligen Tutorials:

Der Analyzer probiert lokal über 100 bekannte Secrets und erklärt jeden Fund mit einem Fix.

Zuerst meldet er die fälschbare Signatur, dann die mehrjährige Laufzeit und die fehlenden iss und aud, jeweils mit Fix. Fügen Sie den öffentlichen Schlüssel oder das JWKS des Ausstellers ein, prüft er auch RS256-, PS256-, ES256- und EdDSA-Signaturen. Für KI-Agenten steht dieselbe Analyse als WebMCP-Tool analyze_jwt bereit.

JWT oder Session-Cookie: wann ein JWT passt

JWTs sind so populär, dass sie auch dort landen, wo eine Session einfacher wäre. Ein ehrlicher Vergleich:

	Serverseitige Session	JWT
Zustand	Auf dem Server, Cookie enthält eine ID	In sich geschlossen, mit Schlüssel geprüft
Widerruf	Sofort: Session löschen	Wartet auf `exp`, außer man ergänzt Serverzustand
Skalierung	Braucht gemeinsamen Session-Store	Jeder Dienst mit dem öffentlichen Schlüssel kann prüfen
Über Dienste und Domains	Umständlich	Genau dafür gebaut
Größe pro Request	Ein paar Dutzend Byte	Hunderte Byte bis mehrere KB

Eine Session für die klassische Web-App mit einem Backend. JWTs , wenn mehrere Dienste, ein API-Gateway oder Dritte die Identität ohne gemeinsamen Store prüfen müssen, und überall dort, wo OAuth 2.0 und OpenID Connect ohnehin eines liefern: ID-Tokens sind immer JWTs, viele Access Tokens ebenfalls.

JWT vs. OAuth

Das sind keine Alternativen. OAuth 2.0 ist ein Protokoll , um im Namen eines Nutzers ein Access Token zu bekommen; ein JWT ist ein Tokenformat. Ein OAuth-Access-Token kann ein JWT sein (RFC 9068 standardisiert dieses Profil mit typ: at+jwt) oder ein undurchsichtiger Zufallsstring, den die API beim Authorization Server prüft. OpenID Connect, die Identitätsschicht über OAuth, nutzt für das ID-Token immer ein JWT.

Beides lässt sich gut kombinieren. In Browser-Apps gehört ein JWT in ein HttpOnly-Cookie, nicht in den localStorage; Details inklusive CSRF-Schutz stehen in JWT nicht in LocalStorage speichern. Wer den Identity Provider selbst betreibt, lässt Tokens von Keycloak oder Authentik ausstellen und signieren, und ein stärkerer Login davor, etwa mit Passkeys, schützt den Moment, in dem ein Token entsteht.

Das HMAC hinter HS256 ist dasselbe Primitiv, mit dem Webhooks signiert werden; Webhook-Signaturen unterliegen denselben Regeln für Secret-Stärke und zeitkonstanten Vergleich.

Fazit

Ein JWT ist ein lesbares JSON-Dokument mit Signatur. Das Format ist einfach und die Kryptografie solide; in der Praxis scheitert der Code drumherum. Algorithmus festlegen, Schlüssel selbst wählen, exp verlangen, iss und aud prüfen, Tokens kurzlebig halten und Secrets aus der Payload heraushalten. Mit einer gepflegten Bibliothek umgesetzt, ist ein JWT eines der bequemsten Credentials, die man ausgeben kann.

Und wenn Sie das nächste Mal sehen wollen, was in einem steckt: lokal dekodieren, nicht in einer Seite, die es hochlädt.

Ursprünglich veröffentlicht auf alekseialeinikov.com

PostgreSQL-Indizes: Welcher Typ wann? (10-Mio-Zeilen-Benchmark)

Aleksei Aleinikov — Fri, 23 Oct 2026 06:00:00 +0000

Früher oder später tippt jedes Postgres-Team in Eile CREATE INDEX, und die meisten tippen denselben. B-tree ist der richtige Standard, aber nicht immer die richtige Antwort. Auf einer Tabelle mit 10 Millionen Zeilen fand ich einen Index, der 3.000-mal kleiner und nur 3-mal langsamer war, einen Index, der gar nichts bewirkte, und einen „abdeckenden“ Index, der Abfragen beschleunigte, bis ein ganz normales UPDATE den Vorteil wieder auffraß.

Das ist Teil 1 von Postgres in Production , einer Serie über die Entscheidungen, die zählen, sobald eine Datenbank das Tutorial verlässt: Indizes, VACUUM und Bloat, Connection Pooling, Partitionierung und JSONB. Jeder Teil folgt einer Regel: erst messen, dann erklären. Die Zahlen unten stammen von PostgreSQL 18.6 und einem Open-Source-Benchmark, den du selbst ausführen kannst.

Welcher PostgreSQL-Index-Typ passt: die kurze Antwort

Ein PostgreSQL-Index ist eine eigene Datenstruktur, mit der die Datenbank Zeilen findet, ohne die ganze Tabelle zu lesen. Der Typ bestimmt, welche Fragen er beantworten kann und wie viel Platz und Schreibzeit er kostet.

Deine Abfrage	Index	Gemessen auf 10 Millionen Zeilen
`WHERE user_id = 42`, Bereiche, `ORDER BY`	B-tree (Standard)	158 ms Scan, 0,11 ms mit Index
Nur ein seltener Ausschnitt zählt (`status = 'failed'`)	Partieller B-tree	1,8 MiB statt 301 MiB, gleiche Geschwindigkeit
Wenige Spalten, viele Zugriffe	Abdeckender B-tree (`INCLUDE`)	0,109 auf 0,078 ms, bei 4,4-facher Größe
Zeitbereich auf geordneten Append-only-Daten	BRIN	72 KiB statt 214 MiB, 3-mal langsamer
Enthält: Arrays, `jsonb`, Volltext, `LIKE '%x%'`	GIN	360 ms auf 2,8 ms bei seltenem Tag
Geometrie, Bereiche, nächster Nachbar	GiST oder SP-GiST	hier nicht gemessen
Nur Gleichheit	Hash	nicht schneller als B-tree, 3-mal größer

Fang bei der Abfrage an, nicht beim Index-Typ.

Wie ein Index eine Zeile findet und was ein Scan kostet

Ohne Index liest PostgreSQL die Tabelle Seite für Seite und prüft jede Zeile. Die Testtabelle ist 1,6 GB groß, 208.376 Seiten à 8 KB, und ein Sequential Scan hat jede einzelne gezählt. Ein B-tree-Index auf derselben Tabelle ist ein drei bis vier Ebenen tiefer Baum, ein Schlüssel kostet also eine Handvoll Seiten: Die Abfrage unten las 14 Buffer statt 208.376.

Das ist die ganze Idee, alles andere sind Abwägungen. Ein größerer Index beantwortet mehr Arten von Fragen, kostet aber Platz, Aufbauzeit und Schreibzeit. Der Planer wählt anhand geschätzter Kosten zwischen Scan und Index, deshalb wird ein vorhandener Index nicht immer benutzt (mehr dazu unten). Was wirklich passiert ist, zeigt EXPLAIN (ANALYZE, BUFFERS). Seit PostgreSQL 18 ist BUFFERS bei ANALYZE automatisch dabei.

Der Benchmark: eine Tabelle, 10 Millionen Zeilen, und was jeder Index kostet

Eine Tabelle events mit bigint-Primärschlüssel, user_id (zufällig, etwa 10 Zeilen pro Nutzer), status (70 % done, 20 % active, 9 % pending, 0,85 % failed, 0,15 % archived), created_at (eine Zeile alle 3 Sekunden, wächst also mit id), einer Spalte tags text[] und einer Spalte payload jsonb. Die Tabelle ist 1,6 GB groß, der Primärschlüssel 214 MiB. Die Daten kommen aus einem festen Zufalls-Seed, jeder Lauf erzeugt also dieselben Zeilen.

Jede Abfrage lief einmal zum Aufwärmen und danach dreimal, die Tabellen zeigen den Median. Punkt- und Bereichsabfragen wurden für mehrere Parameterwerte wiederholt. Jede gemessene Abfrage lief außerdem mit deaktivierten Index-Scans, und die Antworten mussten übereinstimmen , sonst bricht das Skript ab. PostgreSQL 18.6, warmer Cache, autovacuum aus, damit die Visibility Map unter Kontrolle bleibt (eine Produktionsdatenbank sollte so nicht laufen).

Hinweis

Nachstellen in drei Befehlen: git clone https://github.com/LF3551/postgres-index-benchmark, dann npm run up und npm run all. Das Repository startet ein festgelegtes PostgreSQL 18.6 in Docker, lädt dieselben Daten, führt jedes Experiment unten aus und gibt die Tabellen aus. Du kannst es auch über die PG*-Variablen auf deinen eigenen Server richten. Messwerte von einer einzelnen Maschine sind ein Plausibilitätscheck, keine Rangliste: Vergleiche Verhältnisse, Größen und Pläne, nicht Millisekunden.

B-tree: der Standard aus gutem Grund

B-tree ist ein balancierter Baum aus sortierten Schlüsseln. Weil die Schlüssel sortiert sind, beantwortet eine Struktur =, <, >, BETWEEN, ORDER BY und IS NULL, und er ist das, was CREATE INDEX baut, solange du nichts anderes verlangst.


CREATE INDEX ix_user ON events (user_id);

SELECT * FROM events WHERE user_id = 424242;

Suche nach `user_id`	Zeit	Buffer	Indexgröße	Aufbau
Ohne Index (Sequential Scan)	158 ms	208.376	keiner	keiner
B-tree	0,112 ms	14	88,5 MiB	1,4 s

Das ist etwa 1.400-mal schneller für einen zusätzlichen Index von 88,5 MiB, aufgebaut in 1,4 Sekunden auf einer 1,6-GB-Tabelle. Der Index ist klein, weil B-tree jeden doppelten Schlüssel nur einmal speichert und eine Liste von Zeilenzeigern führt (Deduplizierung, seit PostgreSQL 13). Derselbe Index auf einer Zeitspalte, in der jeder Schlüssel einzigartig ist, ist 214 MiB groß.

Wenn eine Spalte im WHERE, JOIN oder ORDER BY einer häufigen Abfrage steht, die wenige Zeilen liefert, ist ein B-tree fast immer die Antwort. Die anderen Typen gibt es für das, was B-tree schlecht kann.

Hash-Index: nicht besser als B-tree

Ein Hash-Index speichert einen Hash des Schlüssels und unterstützt nur Gleichheit. Die Theorie sagt, er müsse bei Punktabfragen schneller sein. In diesem Test war er es nicht:

`user_id = ?`	Suche	Indexgröße	Aufbau
B-tree	0,112 ms	88,5 MiB	1,4 s
Hash	0,115 ms	267,6 MiB	13,0 s

Gleiche Geschwindigkeit, dreifacher Platz, neunfache Aufbauzeit, und keine Bereiche oder Sortierung. Hash-Indizes sind seit PostgreSQL 10 absturzsicher, gefährlich sind sie also nicht, aber bei vielen doppelten Schlüsseln haben sie keinen Vorteil gegenüber einem B-tree, der dedupliziert. Das ist ein Datensatz, kein Gesetz: Bei langen String-Schlüsseln kann Hashing Platz sparen, miss also, bevor du ihn abschreibst.

BRIN: ein 72-KiB-Index für zeitlich geordnete Daten

Ein BRIN (Block Range Index) speichert für jeden Bereich von Tabellenseiten eine Zusammenfassung, normalerweise Minimum und Maximum. Eine Abfrage überspringt jeden Bereich, dessen Zusammenfassung nicht passen kann. Er ist winzig, funktioniert aber nur, wenn die Werte der Spalte der physischen Reihenfolge der Tabelle folgen, und ein Append-only-created_at tut genau das: pg_stats meldet hier eine Korrelation von 1,0 für created_at und etwa 0 für user_id.


CREATE INDEX ix_ts_brin ON events USING brin (created_at);

Die Abfrage: ein Tag Ereignisse, 28.800 Zeilen von 10 Millionen.

Ein Tag nach `created_at`	Zeit	Buffer	Indexgröße	Aufbau
Ohne Index	635 ms	208.376	keiner	keiner
B-tree	3,0 ms	690	214,2 MiB	1,7 s
BRIN (Standardbereich von 128 Seiten)	9,1 ms	785	72 KiB	0,2 s
BRIN (`pages_per_range = 32`)	8,2 ms	683	232 KiB	0,2 s

B-tree ist dreimal schneller, und BRIN ist etwa 3.000-mal kleiner. Bei einer Tabelle, die um Milliarden Zeilen wächst, ist das der Unterschied zwischen einem Index, der in den Speicher passt, und einem, der es nicht tut, und ein BRIN-Index lässt sich in Sekundenbruchteilen neu bauen. Wenn deine Abfragen immer „der letzte Tag“ oder „der letzte Monat“ lauten, ist BRIN die günstige Wahl. Wenn eine einzelne Suche unter einer Millisekunde antworten muss, nimm B-tree. Ein kleineres pages_per_range macht den Index etwas größer und schärfer.

Achtung

BRIN auf einer Spalte, die nicht physisch geordnet ist, ist nutzlos: Er kann keinen Blockbereich überspringen, und der Planer benutzt ihn nicht. Prüfe zuerst SELECT attname, correlation FROM pg_stats WHERE tablename = 'events';. Wenn Zeilen aktualisiert und verschoben werden, sinkt die Korrelation, und BRIN verfällt mit ihr.

Partielle Indizes: nur die Zeilen indizieren, die zählen

Ein partieller Index hat eine WHERE-Klausel und enthält nur die passenden Zeilen. Er ist die günstigste Optimierung in diesem Artikel, weil viele Abfragen einen kleinen, klar definierten Ausschnitt betreffen: unverarbeitete Jobs, fehlgeschlagene Zahlungen, aktive Sessions.


CREATE INDEX ix_failed_ts ON events (created_at) WHERE status = 'failed';

SELECT id, created_at FROM events

WHERE status = 'failed' ORDER BY created_at DESC LIMIT 50;

Die neuesten 50 fehlgeschlagenen Ereignisse	Zeit	Indexgröße	Aufbau
Ohne Index	177 ms	keiner	keiner
Voller Index `(status, created_at)`	0,138 ms	301,0 MiB	3,5 s
Partieller Index `WHERE status = 'failed'`	0,125 ms	1,8 MiB	0,2 s

Fehlgeschlagene Ereignisse sind 0,85 % der Zeilen. Der partielle Index beantwortet die Abfrage so schnell wie der volle und ist etwa 160-mal kleiner , baut in einem Bruchteil der Zeit und kostet beim Schreiben fast nichts, weil 99 % der Inserts ihn nie berühren. Die Regel: Das WHERE der Abfrage muss das WHERE des Index implizieren, schreibe die Bedingung also in beiden gleich. Ein Parameter wie status = $1 kann den Planer in einem generischen Plan daran hindern, den Treffer zu beweisen, prüfe mit EXPLAIN, ob der partielle Index genutzt wird.

Abdeckende Indizes: schneller, aber nur auf einer sauberen Tabelle

Ein Index-Only-Scan beantwortet eine Abfrage allein aus dem Index, ohne die Tabelle zu besuchen. INCLUDE (ab PostgreSQL 11) fügt dem Index genau dafür zusätzliche Spalten hinzu.


CREATE INDEX ix_user_cov ON events (user_id) INCLUDE (created_at, status);

SELECT created_at, status FROM events WHERE user_id = 424242;

Abdeckender Index gegen einfachen B-tree	Zeit	Buffer	Indexgröße
Einfacher B-tree auf `user_id`	0,109 ms	14	88,5 MiB
Abdeckend, Tabelle frisch vakuumiert	0,078 ms	9	386,7 MiB
Abdeckend, nach Update von 1 % der Zeilen	0,109 ms	13	386,7 MiB
Abdeckend, nach `VACUUM`	0,079 ms	9	386,7 MiB

Zwei Lehren. Erstens: Der Gewinn ist echt, aber bescheiden (1,4-fach), während der Index 4,4-mal größer ist: Für eine Abfrage mit zehn Ergebniszeilen ist ein einfacher B-tree schon gut. Abdeckende Indizes lohnen sich in der Theorie mehr, wenn eine Abfrage viele Zeilen aus einem Indexbereich liefert und jeder Heap-Zugriff zählt; miss das auf deinen eigenen Daten. Zweitens: Ein Index-Only-Scan prüft weiterhin die Visibility Map, um zu sehen, ob eine Seite vollständig sichtbar ist, und ein UPDATE löscht diese Bits. Nachdem 1 % der Zeilen angefasst wurden, verteilt über jede Seite, war der Vorteil weg, bis VACUUM wieder lief. Autovacuum übernimmt das normalerweise; der Benchmark schaltet es ab, um den Effekt sichtbar zu machen.

Mehrspaltige Indizes und Skip Scan in PostgreSQL 18

Ein mehrspaltiger B-tree sortiert nach der ersten Spalte, dann innerhalb jedes ersten Werts nach der zweiten, die Reihenfolge der Spalten zählt also. Vor PostgreSQL 18 konnte eine Abfrage, die nur nach der zweiten Spalte filterte, so einen Index nicht effizient nutzen. PostgreSQL 18 bringt Skip Scan , der durch die verschiedenen Werte der führenden Spalte springt.


CREATE INDEX ix_status_ts ON events (status, created_at);

-- gar kein Filter auf status:

SELECT count(*) FROM events

WHERE created_at >= '2025-02-12' AND created_at < '2025-02-12 01:00';

Eine Stunde nach `created_at`	Zeit	Buffer	Plan
Ohne Index	233 ms	210.460	Seq Scan
Index `(status, created_at)`	0,246 ms	72	Index Only Scan, Index Searches: 11

EXPLAIN meldet jetzt Index Searches: 11 Abstiege durch den Index statt einem, was immer noch winzig ist. Skip Scan macht einen Index nützlicher, den du ohnehin hast. Er funktioniert, wenn die übersprungene Spalte wenige verschiedene Werte hat (hier fünf Status). Bei Millionen verschiedener führender Werte lässt er nach, ersetzt also keinen eigenen Index auf die Spalte, nach der du filterst.

GIN: wenn eine Zeile viele Werte enthält

Ein GIN (Generalized Inverted Index) bildet jedes Element auf die Zeilen ab, die es enthalten, wie das Register hinten in einem Buch. Er ist der Index für Arrays, jsonb, Volltextsuche (tsvector) und, mit der Erweiterung pg_trgm, für LIKE '%text%'.


CREATE INDEX ix_tags ON events USING gin (tags);

CREATE INDEX ix_payload ON events USING gin (payload jsonb_path_ops);

SELECT count(*) FROM events WHERE tags @> ARRAY['rare'];

SELECT count(*) FROM events WHERE payload @> '{"beta": true}';

Abfrage	Treffer	Ohne Index	GIN	Indexgröße
Array, seltener Tag	1.042 Zeilen	360 ms	2,8 ms (129x)	39,1 MiB
Array, häufiger Tag	99.778 Zeilen (1 %)	364 ms	113 ms (3,2x)	39,1 MiB
`jsonb @>` seltenes Flag	5.064 Zeilen	353 ms	34,1 ms (10x) mit Standard-Ops	86,0 MiB
`jsonb @>` seltenes Flag	5.064 Zeilen	353 ms	9,9 ms (36x) mit `jsonb_path_ops`	44,5 MiB
`jsonb @>` Land und Tarif	250.512 Zeilen (2,5 %)	399 ms	347 ms (1,1x) Standard, 262 ms (1,5x) `jsonb_path_ops`	86,0 / 44,5 MiB

Indexgröße auf logarithmischer Skala. Der günstigste Index ist selten der langsamste.

Drei Dinge zum Mitnehmen:

Die Selektivität entscheidet alles. GIN glänzt, wenn der Treffer selten ist (129-mal schneller), und hilft kaum, wenn der Treffer 2,5 % der Tabelle sind, weil die Heap-Seiten trotzdem gelesen werden müssen. Eine unselektive Enthält-Abfrage ist ein Hinweis auf das Datenmodell, kein Indexproblem.
Probiere bei jsonb jsonb_path_ops. Er ist etwa halb so groß und bei @>-Abfragen schneller, unterstützt dafür aber die Operatoren zur Schlüsselprüfung (?, ?|, ?&) nicht.
Parallele Builds sind neu. PostgreSQL 18 kann einen GIN-Index mit parallelen Workern bauen: 3,8 s mit vier Workern gegenüber 14,4 s seriell beim tags-Index, 3,8-mal schneller, was beim Neuaufbau großer Tabellen zählt.

GiST und SP-GiST: für Formen und Bereiche

Diese habe ich auf diesen Daten nicht gemessen, weil die Testtabelle keine Geometrie und keine Bereiche enthält, und ein erfundener Benchmark würde nur mein Schema messen. GiST ist ein Rahmen für baumbasierte Indizes über Daten ohne lineare Ordnung: geometrische Typen (PostGIS nutzt ihn), Bereichstypen und Nächste-Nachbarn-Suche (ORDER BY location <-> point). Er stützt auch Exclusion Constraints wie „zwei Buchungen desselben Raums dürfen sich nicht überschneiden“. SP-GiST unterstützt raumpartitionierte Strukturen wie Quad-Trees und Radix-Tries, nützlich für unbalancierte Daten wie IP-Adressen oder Telefonvorwahlen. Wenn deine Abfrage &&, <-> oder @> auf Formen oder Bereichen nutzt, fang hier an.

Wenn der Planer deinen Index ignoriert

Der häufigste Index-Fehler ist nicht der falsche Typ, sondern eine Abfrage, die der Index nicht bedienen kann. Zwei Fälle, gemessen auf derselben Tabelle:

Ein Tag nach `created_at` oder ein Status-Filter	Plan	Zeit
`created_at >= ... AND created_at < ...`	Index Scan	3,0 ms
`created_at::date = '2025-04-01'`	Seq Scan	329 ms
Dasselbe, mit Ausdrucks-Index auf `(created_at AT TIME ZONE 'UTC')::date`	Index Scan	2,7 ms
`status = 'done'` (70 % der Zeilen), Index auf `status`	Seq Scan	263 ms
`status = 'archived'` (0,15 % der Zeilen), derselbe Index	Index Scan	20,9 ms

Eine indizierte Spalte in eine Funktion oder einen Cast zu packen macht den Index unbrauchbar. Schreibe die Bedingung also als Bereich um oder indiziere den Ausdruck. Beachte, dass timestamptz::date von der Zeitzone der Session abhängt und sich deshalb nicht direkt indizieren lässt: Der Ausdrucks-Index nutzt AT TIME ZONE 'UTC'. Und wenn eine Abfrage den Großteil der Tabelle trifft, hat der Planer recht, den Index zu überspringen: 70 % einer Tabelle über einen Index zu lesen ist langsamer als ein Sequential Scan.

Die Schreibsteuer: Jeder Index kostet bei jedem Insert

Lesen ist nur die halbe Rechnung. Jeder Insert muss in jedem Index der Tabelle einen Eintrag ergänzen. Ich habe 1 Million Zeilen in eine leere Tabelle mit Primärschlüssel und dann 0, 1, 3 und 5 weiteren Indizes eingefügt:

Sekundäre Indizes	1 Mio. Zeilen einfügen	Im Vergleich zu nur Primärschlüssel
0	1,9 s	1,0x
1 (B-tree auf `user_id`)	4,3 s	2,3x
3 (dazu `created_at` und `(status, created_at)`)	5,8 s	3,1x
5 (dazu GIN auf `tags` und auf `payload`)	12,1 s	6,4x

Der erste zusätzliche Index und die GIN-Indizes kosten am meisten.

Der Sprung von 3 auf 5 Indizes, mehr als eine Verdopplung der Zeit, sind die beiden GIN-Indizes: Sie sind am teuersten in der Pflege, und PostgreSQL puffert GIN-Updates standardmäßig in einer Pending-Liste, um das abzumildern. Indizes verlangsamen auch UPDATE (wenn sich eine indizierte Spalte ändert) und VACUUM, und sie brauchen Speicher und Platte. Ein Index, den du nicht nutzt, ist reine Kostenstelle.

Zufällige UUID-Schlüssel: versteckte Indexkosten

Ein Primärschlüssel ist ebenfalls ein Index, und sein Typ bestimmt, wie der B-tree wächst. Eine zufällige UUIDv4 landet irgendwo im Baum, Inserts berühren also Seiten im ganzen Baum und spalten sie. Eine UUIDv7 beginnt mit einem Zeitstempel, neue Schlüssel kommen also der Reihe nach am rechten Rand an, wie bei einer Sequenz. PostgreSQL 18 hat dafür ein eingebautes uuidv7(). Ich habe 5 Millionen Zeilen in eine Tabelle mit je einer Art von Primärschlüssel eingefügt:

Primärschlüssel	5 Mio. Zeilen einfügen	Größe des Primärschlüssels
UUIDv4 (`gen_random_uuid()`)	12,9 s	191 MiB
UUIDv7 (`uuidv7()`)	9,6 s	150 MiB

Der zeitlich geordnete Schlüssel fügte 1,3-mal schneller ein und erzeugte einen etwa ein Fünftel kleineren Index. Diese Tabellen passen in den Speicher, der Abstand dürfte also wachsen, sobald der Index nicht mehr hineinpasst, weil zufällige Schlüssel dann bei jedem Insert den Cache verfehlen. UUIDv7 verrät außerdem die Erstellungszeit in der ID, was zählt, wenn die ID öffentlich ist. Eine bigint-Sequenz ist noch kleiner (8 gegen 16 Byte).

So findest du ungenutzte und fehlende Indizes

Rate nicht, frag die Statistik. Indizes, die seit dem letzten Zurücksetzen der Statistik nie gescannt wurden (pg_stat_database.stats_reset zeigt, wie lange die Zähler schon laufen):


SELECT s.relname AS table_name, s.indexrelname AS index_name,

       pg_size_pretty(pg_relation_size(s.indexrelid)) AS size, s.idx_scan

FROM pg_stat_user_indexes s

JOIN pg_index i ON i.indexrelid = s.indexrelid

WHERE s.idx_scan = 0 AND NOT i.indisunique AND NOT i.indisprimary

ORDER BY pg_relation_size(s.indexrelid) DESC;

Lass eindeutige und Primärschlüssel-Indizes aus, sie erzwingen Constraints. Beobachte über einen vollen Geschäftszyklus (Monatsabschluss-Jobs), und denk daran, dass jedes Replikat eigene Zähler führt. Für fehlende Indizes schau auf Tabellen, bei denen Sequential Scans viele Zeilen lesen:


SELECT relname, seq_scan, seq_tup_read, idx_scan, n_live_tup

FROM pg_stat_user_tables

WHERE seq_scan > 0

ORDER BY seq_tup_read DESC LIMIT 10;

Finde dann die Abfragen dahinter mit pg_stat_statements und prüfe den Plan mit EXPLAIN (ANALYZE, BUFFERS). Auf einem Live-System baust du immer mit CREATE INDEX CONCURRENTLY, das Schreibzugriffe nicht blockiert (es kann nicht in einer Transaktion laufen, und ein fehlgeschlagener Build hinterlässt einen INVALID-Index, den du löschen musst), und entfernst Indizes mit DROP INDEX CONCURRENTLY. Ein Index, der nach vielen Updates und Deletes aufgebläht ist, lässt sich ohne Blockieren von Schreibzugriffen mit REINDEX INDEX CONCURRENTLY neu bauen.

Was sich bei Indizes in PostgreSQL 18 und 19 ändert

PostgreSQL 18, das aktuelle Major-Release, brachte vier indexbezogene Änderungen, die in diesem Artikel vorkommen: Skip Scan für mehrspaltige B-tree-Indizes, parallele GIN-Builds, Index Searches und automatisches BUFFERS bei EXPLAIN ANALYZE sowie das eingebaute uuidv7() für indexfreundliche Schlüssel. Es hat außerdem das neue asynchrone I/O-Subsystem eingeführt, das die Sequential und Bitmap Scans beschleunigt, gegen die diese Indizes antreten. PostgreSQL 19 ist im Release-Candidate-Stadium, und PostgreSQL 14 erreicht am 12. November 2026 das Support-Ende, jetzt ist also ein guter Zeitpunkt zu prüfen, welche Version deine eigene Datenbank nutzt. Die offiziellen Release Notes haben die vollständige Liste, und wenn du dich noch für eine Datenbank entscheidest, vergleicht Postgres vs. MySQL 2026 die beiden.

Hinweis

Als Nächstes in Postgres in Production: VACUUM und Bloat (warum eine Tabelle wächst, obwohl du löschst), Connection Pooling, Partitionierung und JSONB im Detail. Indizes sind der erste Hebel für Performance, und die nächsten Teile behandeln, was sie nach einem Jahr Produktion schnell hält.

Eine praktische Checkliste

Schreibe zuerst die Abfrage und sieh dir ihren Plan mit EXPLAIN (ANALYZE, BUFFERS) an.
Fang mit einem B-tree auf den Spalten in WHERE und JOIN an, Gleichheitsspalten zuerst.
Wenn nur ein kleiner Ausschnitt der Zeilen zählt, mach ihn partiell.
Wenn die Tabelle riesig, append-only und zeitlich geordnet ist, probiere BRIN vor B-tree.
Für Arrays, jsonb und Textsuche nimm GIN und prüfe, ob die Treffer selektiv sind.
Füge INCLUDE nur für heiße Abfragen hinzu, die viele Zeilen liefern, und lass VACUUM laufen.
Baue mit CREATE INDEX CONCURRENTLY und prüfe pg_stat_user_indexes jedes Quartal.
Lege für die referenzierende Spalte jedes Fremdschlüssels, nach der du joinst oder löschst, einen Index an: PostgreSQL erzeugt ihn nicht von selbst.
Nimm für UUID-Primärschlüssel unter PostgreSQL 18 lieber UUIDv7 als zufällige UUIDv4.

Für Gewohnheiten auf Abfrageebene, die dazu passen, siehe SQL Query Optimization 2026, und für Vektoren in Postgres Brauchst du eine Vektordatenbank?.

Das Fazit

Nimm standardmäßig B-tree und miss, bevor du zu etwas anderem greifst. Mach ihn partiell, wenn nur ein Ausschnitt der Zeilen zählt, nutze BRIN bei riesigen, zeitlich geordneten Tabellen und GIN, wenn du in Arrays und Dokumenten suchst und die Treffer selten sind. Sei vorsichtig mit dem Rest: Ein Hash-Index war nicht schneller, ein abdeckender Index war 4,4-mal größer für einen 1,4-fachen Gewinn, und jeder zusätzliche Index verlangsamte Inserts. Der beste Index ist der kleinste, der deine Abfrage beantwortet, und der zweitbeste ist der, den du gelöscht hast.

Indizes sind keine Geschwindigkeit zum Nulltarif. Jeder ist ein Tausch zwischen Lesezeit, Platte, Speicher und Schreibzeit, wähle den Typ also nach der Form der Abfrage und behalte nur die, die laut Statistik genutzt werden.

Postgres, PostgreSQL und das Slonik-Logo sind Marken oder eingetragene Marken der PostgreSQL Community Association of Canada.

Ursprünglich veröffentlicht auf alekseialeinikov.com

PostgreSQL Indexes: Which Type to Use (10M-Row Benchmark)

Aleksei Aleinikov — Fri, 23 Oct 2026 06:00:00 +0000

Every Postgres team eventually types CREATE INDEX in a hurry, and most of them type the same one. B-tree is the right default, but it is not always the right answer. On a table with 10 million rows I found an index that was 3,000 times smaller and only 3 times slower, an index that did nothing at all, and a “covering” index that made queries faster until a routine UPDATE took the advantage away.

This is Part 1 of Postgres in Production , a series about the decisions that matter once a database leaves the tutorial: indexes, VACUUM and bloat, connection pooling, partitioning and JSONB. Each part follows one rule: measure first, then explain. The numbers below come from PostgreSQL 18.6 and an open-source benchmark that you can run yourself.

Which PostgreSQL index type to use: the short answer

A PostgreSQL index is a separate data structure that lets the database find rows without reading the whole table. The type decides which questions it can answer and how much space and write time it costs.

Your query	Index to use	Measured on 10 million rows
`WHERE user_id = 42`, ranges, `ORDER BY`	B-tree (the default)	158 ms scan, 0.11 ms with the index
Only a rare slice of rows matters (`status = 'failed'`)	Partial B-tree	1.8 MiB instead of 301 MiB, same speed
Few columns, many lookups	Covering B-tree (`INCLUDE`)	0.109 to 0.078 ms, at 4.4 times the size
Time range on append-only, ordered data	BRIN	72 KiB instead of 214 MiB, 3 times slower
Contains: arrays, `jsonb`, full-text, `LIKE '%x%'`	GIN	360 ms to 2.8 ms for a rare tag
Geometry, ranges, nearest neighbour	GiST or SP-GiST	not benchmarked here
Equality only	Hash	no faster than B-tree, 3 times bigger

Start from the query, not from the index type.

How an index finds a row, and what a scan costs

Without an index, PostgreSQL reads the table page by page and checks every row. The test table here is 1.6 GB, 208,376 pages of 8 KB, and a sequential scan counted every one of them. A B-tree index on the same table is a tree three to four levels deep, so finding one key touches a handful of pages instead: the lookup below read 14 buffers instead of 208,376.

That is the whole idea, and everything else is a trade. A bigger index answers more kinds of questions but costs space, build time and write time. The planner chooses between a scan and an index by estimated cost, which is why an index that exists is not always used (more on that below). To see what actually happened, run EXPLAIN (ANALYZE, BUFFERS). Since PostgreSQL 18, BUFFERS is included automatically with ANALYZE.

The benchmark: one table, 10 million rows, and what each index costs

One events table with a bigint primary key, user_id (random, about 10 rows per user), status (70% done, 20% active, 9% pending, 0.85% failed, 0.15% archived), created_at (one row every 3 seconds, so it grows with id), a tags text[] column and a payload jsonb column. The table is 1.6 GB and the primary key 214 MiB. Data comes from a fixed random seed, so every run produces the same rows.

Each query ran once as a warm-up and then three times, and the table shows the median. Point and range queries were repeated for several parameter values. Every measured query was also run with index scans disabled, and the answers had to match , otherwise the script stops. PostgreSQL 18.6, warm cache, autovacuum off so the visibility map stays under control (a production database should not run like that).

Note

Reproduce it in three commands: git clone https://github.com/LF3551/postgres-index-benchmark, then npm run up and npm run all. The repository starts a pinned PostgreSQL 18.6 in Docker, loads the same data, runs every experiment below and prints the tables. You can also point it at your own server with the PG* variables. Single-machine numbers are a sanity check, not a leaderboard: compare ratios, sizes and plans, not milliseconds.

B-tree: the default for a reason

B-tree is a balanced tree of sorted keys. Because the keys are sorted, one structure answers =, <, >, BETWEEN, ORDER BY and IS NULL, and it is what CREATE INDEX builds unless you ask for something else.


CREATE INDEX ix_user ON events (user_id);

SELECT * FROM events WHERE user_id = 424242;

Lookup on `user_id`	Time	Buffers	Index size	Build
No index (sequential scan)	158 ms	208,376	none	none
B-tree	0.112 ms	14	88.5 MiB	1.4 s

That is about 1,400 times faster for one extra index of 88.5 MiB, built in 1.4 seconds on a 1.6 GB table. The index is small because B-tree stores each duplicate key once and keeps a list of row pointers (deduplication, since PostgreSQL 13). The same index on a time column, where every key is unique, is 214 MiB.

If a column appears in WHERE, JOIN or ORDER BY of a query that runs often and returns few rows, a B-tree is almost always the answer. The other types exist for what B-tree does badly.

Hash index: no better than B-tree

A hash index stores a hash of the key and supports only equality. The theory says it should be faster for point lookups. In this test it was not:

`user_id = ?`	Lookup	Index size	Build
B-tree	0.112 ms	88.5 MiB	1.4 s
Hash	0.115 ms	267.6 MiB	13.0 s

Same speed, three times the space, nine times the build time, and no ranges or sorting. Hash indexes have been crash-safe since PostgreSQL 10, so they are not dangerous, but with duplicate-heavy keys they have no advantage over a B-tree that deduplicates. This is one data set, not a law: if your keys are long strings, hashing them may save space, so measure before dismissing it.

BRIN: a 72 KiB index for time-ordered data

A BRIN (block range index) stores a summary, normally the minimum and maximum value, for each range of table pages. A query skips every range whose summary cannot match. It is tiny, but it works only if the values in the column follow the physical order of the table, and an append-only created_at does exactly that: here pg_stats reports a correlation of 1.0 for created_at and about 0 for user_id.


CREATE INDEX ix_ts_brin ON events USING brin (created_at);

The query: one day of events, 28,800 rows out of 10 million.

One day by `created_at`	Time	Buffers	Index size	Build
No index	635 ms	208,376	none	none
B-tree	3.0 ms	690	214.2 MiB	1.7 s
BRIN (default range of 128 pages)	9.1 ms	785	72 KiB	0.2 s
BRIN (`pages_per_range = 32`)	8.2 ms	683	232 KiB	0.2 s

B-tree is three times faster, and BRIN is about 3,000 times smaller. For a table that grows by billions of rows, that is the difference between an index that fits in memory and one that does not, and a BRIN index can be rebuilt in a fraction of a second. If your queries are always “the last day” or “last month”, BRIN is the cheap choice. If one lookup must return in under a millisecond, use B-tree. A smaller pages_per_range makes the index slightly larger and sharper.

Warning

BRIN on a column that is not physically ordered is useless: it cannot skip any block range and the planner will not use it. Check SELECT attname, correlation FROM pg_stats WHERE tablename = 'events'; first. If rows are updated and moved around, correlation decays and BRIN decays with it.

Partial indexes: index only the rows that matter

A partial index has a WHERE clause and contains only the rows that match. It is the cheapest optimisation in this article because many queries care about a small, well-defined slice: unprocessed jobs, failed payments, active sessions.


CREATE INDEX ix_failed_ts ON events (created_at) WHERE status = 'failed';

SELECT id, created_at FROM events

WHERE status = 'failed' ORDER BY created_at DESC LIMIT 50;

Newest 50 failed events	Time	Index size	Build
No index	177 ms	none	none
Full index `(status, created_at)`	0.138 ms	301.0 MiB	3.5 s
Partial index `WHERE status = 'failed'`	0.125 ms	1.8 MiB	0.2 s

Failed events are 0.85% of the rows. The partial index answers the query as fast as the full one and is about 160 times smaller , builds in a fraction of the time, and costs almost nothing on writes because 99% of inserts never touch it. The rule: the query’s WHERE must imply the index’s WHERE, so write the condition the same way in both. A parameter such as status = $1 can keep the planner from proving the match in a generic plan, so confirm with EXPLAIN that the partial index is used.

Covering indexes: faster, but only on a clean table

An index-only scan answers a query from the index alone, without visiting the table. INCLUDE (PostgreSQL 11 and later) adds extra columns to the index for exactly that purpose.


CREATE INDEX ix_user_cov ON events (user_id) INCLUDE (created_at, status);

SELECT created_at, status FROM events WHERE user_id = 424242;

Covering index vs plain B-tree	Time	Buffers	Index size
Plain B-tree on `user_id`	0.109 ms	14	88.5 MiB
Covering, table just vacuumed	0.078 ms	9	386.7 MiB
Covering, after updating 1% of the rows	0.109 ms	13	386.7 MiB
Covering, after `VACUUM`	0.079 ms	9	386.7 MiB

Two lessons here. First, the gain is real but modest (1.4 times) while the index is 4.4 times bigger : for a query that returns ten rows, a plain B-tree is already good. In theory a covering index pays off more when a query returns many rows from one index range and every heap fetch counts; measure that on your own data. Second, an index-only scan still checks the visibility map to see whether a page is all-visible, and an UPDATE clears those bits. After touching 1% of the rows, spread over every page, the advantage was gone until VACUUM ran again. Autovacuum normally does this for you; the benchmark turns it off to make the effect visible.

Multicolumn indexes and skip scan in PostgreSQL 18

A multicolumn B-tree sorts by the first column, then the second within each first value, so the order of the columns matters. Before PostgreSQL 18, a query that filtered only on the second column could not use such an index efficiently. PostgreSQL 18 adds skip scan , which jumps through the distinct values of the leading column.


CREATE INDEX ix_status_ts ON events (status, created_at);

-- no filter on status at all:

SELECT count(*) FROM events

WHERE created_at >= '2025-02-12' AND created_at < '2025-02-12 01:00';

One hour by `created_at`	Time	Buffers	Plan
No index	233 ms	210,460	Seq Scan
`(status, created_at)` index	0.246 ms	72	Index Only Scan, Index Searches: 11

EXPLAIN now reports Index Searches: 11 descents through the index instead of one, which is still tiny. Skip scan makes an index you already have more useful. It works when the skipped column has few distinct values (five statuses here). With millions of distinct leading values it degrades, so it does not replace a dedicated index on the column you filter by.

GIN: when a row contains many values

A GIN (generalized inverted index) maps each element to the rows that contain it, like the index at the back of a book. It is the index for arrays, jsonb, full-text search (tsvector) and, with the pg_trgm extension, LIKE '%text%'.


CREATE INDEX ix_tags ON events USING gin (tags);

CREATE INDEX ix_payload ON events USING gin (payload jsonb_path_ops);

SELECT count(*) FROM events WHERE tags @> ARRAY['rare'];

SELECT count(*) FROM events WHERE payload @> '{"beta": true}';

Query	Matches	No index	GIN	Index size
Array, rare tag	1,042 rows	360 ms	2.8 ms (129x)	39.1 MiB
Array, common tag	99,778 rows (1%)	364 ms	113 ms (3.2x)	39.1 MiB
`jsonb @>` rare flag	5,064 rows	353 ms	34.1 ms (10x) with default ops	86.0 MiB
`jsonb @>` rare flag	5,064 rows	353 ms	9.9 ms (36x) with `jsonb_path_ops`	44.5 MiB
`jsonb @>` country and plan	250,512 rows (2.5%)	399 ms	347 ms (1.1x) default, 262 ms (1.5x) `jsonb_path_ops`	86.0 / 44.5 MiB

Index size on a log scale. The cheapest index is rarely the slowest.

Three things to take from this:

Selectivity decides everything. GIN shines when the match is rare (129 times faster) and barely helps when the match is 2.5% of the table, because the heap pages still have to be read. An unselective containment query is a data-modelling signal, not an index problem.
For jsonb, try jsonb_path_ops. It is about half the size and faster on @> containment, at the cost of not supporting the key-existence operators (?, ?|, ?&).
Parallel builds are new. PostgreSQL 18 can build a GIN index with parallel workers: 3.8 s with four workers against 14.4 s serial on the tags index, 3.8 times faster, which matters when you rebuild on a large table.

GiST and SP-GiST: for shapes and ranges

I did not benchmark these on this data, because the test table has no geometry or ranges, and inventing a benchmark would only measure my schema. GiST is a framework for balanced-tree indexes over data that is not linearly ordered: geometric types (PostGIS uses it), range types, and nearest-neighbour search (ORDER BY location <-> point). It also backs exclusion constraints such as “no two bookings of the same room overlap”. SP-GiST supports space-partitioned structures like quad-trees and radix tries, useful for unbalanced data such as IP addresses or phone-number prefixes. If your query uses &&, <-> or @> on shapes or ranges, start here.

When the planner ignores your index

The most common index mistake is not choosing the wrong type, it is writing a query the index cannot serve. Two cases measured on the same table:

One day by `created_at` or a status filter	Plan	Time
`created_at >= ... AND created_at < ...`	Index Scan	3.0 ms
`created_at::date = '2025-04-01'`	Seq Scan	329 ms
Same, with an expression index on `(created_at AT TIME ZONE 'UTC')::date`	Index Scan	2.7 ms
`status = 'done'` (70% of rows), index on `status`	Seq Scan	263 ms
`status = 'archived'` (0.15% of rows), same index	Index Scan	20.9 ms

Wrapping an indexed column in a function or a cast makes the index unusable, so rewrite the condition as a range, or index the expression. Note that timestamptz::date depends on the session time zone and so cannot be indexed directly: the expression index uses AT TIME ZONE 'UTC'. And when a query matches most of the table, the planner is right to skip the index: reading 70% of a table through an index is slower than a sequential scan.

The write tax: every index costs on every insert

Reads are only half of the bill. Every insert must add an entry to every index on the table. I inserted 1 million rows into an empty table with a primary key and then 0, 1, 3 and 5 more indexes:

Secondary indexes	Insert 1M rows	Compared with primary key only
0	1.9 s	1.0x
1 (B-tree on `user_id`)	4.3 s	2.3x
3 (adds `created_at` and `(status, created_at)`)	5.8 s	3.1x
5 (adds GIN on `tags` and on `payload`)	12.1 s	6.4x

The first extra index and the GIN indexes cost the most.

The jump from 3 to 5 indexes, more than doubling the time, is the two GIN indexes: they are the most expensive to maintain, and by default PostgreSQL buffers GIN updates in a pending list to soften that. Indexes also slow UPDATE (when an indexed column changes) and VACUUM, and take memory and disk. An index you do not use is pure cost.

Random UUID keys: a hidden index cost

A primary key is an index too, and its type decides how the B-tree grows. A random UUIDv4 lands anywhere in the tree, so inserts touch pages all over it and split them. A UUIDv7 starts with a timestamp, so new keys arrive in order at the right edge, like a sequence. PostgreSQL 18 has a built-in uuidv7() for this. I inserted 5 million rows into a table with each kind of primary key:

Primary key	Insert 5M rows	Primary key size
UUIDv4 (`gen_random_uuid()`)	12.9 s	191 MiB
UUIDv7 (`uuidv7()`)	9.6 s	150 MiB

The time-ordered key inserted 1.3 times faster and produced an index about a fifth smaller. These tables fit in memory, so the gap is likely to widen once the index no longer does, because random keys then miss the cache on every insert. UUIDv7 also reveals the creation time inside the id, which matters if the id is public. A bigint sequence is smaller still (8 bytes against 16).

How to find unused and missing indexes

Do not guess, ask the statistics. Indexes that were never scanned since the last statistics reset (check pg_stat_database.stats_reset to see how long the counters have been collecting):


SELECT s.relname AS table_name, s.indexrelname AS index_name,

       pg_size_pretty(pg_relation_size(s.indexrelid)) AS size, s.idx_scan

FROM pg_stat_user_indexes s

JOIN pg_index i ON i.indexrelid = s.indexrelid

WHERE s.idx_scan = 0 AND NOT i.indisunique AND NOT i.indisprimary

ORDER BY pg_relation_size(s.indexrelid) DESC;

Skip unique and primary-key indexes, they enforce constraints. Observe over a full business cycle (month-end jobs), and remember that each replica keeps its own counters. For missing indexes, look at tables with many rows read by sequential scans:


SELECT relname, seq_scan, seq_tup_read, idx_scan, n_live_tup

FROM pg_stat_user_tables

WHERE seq_scan > 0

ORDER BY seq_tup_read DESC LIMIT 10;

Then find the queries behind them with pg_stat_statements and check the plan with EXPLAIN (ANALYZE, BUFFERS). On a live system, always build with CREATE INDEX CONCURRENTLY, which does not block writes (it cannot run inside a transaction, and a failed build leaves an INVALID index that you must drop), and remove an index with DROP INDEX CONCURRENTLY. An index that has bloated after many updates and deletes can be rebuilt without blocking writes with REINDEX INDEX CONCURRENTLY.

What changed in PostgreSQL 18 and 19 for indexes

PostgreSQL 18, the current major release, brought four index-related changes used in this article: skip scan for multicolumn B-tree indexes, parallel GIN builds, Index Searches plus automatic BUFFERS in EXPLAIN ANALYZE, and the built-in uuidv7() for index-friendly keys. It also added the new asynchronous I/O subsystem, which speeds up the sequential and bitmap scans that these indexes are competing with. PostgreSQL 19 is at the release candidate stage, and PostgreSQL 14 reaches end of life on 12 November 2026, so now is a good moment to check which version your own database runs. The official release notes have the full list, and if you are still deciding on a database, Postgres vs MySQL in 2026 compares the two.

Note

Next in Postgres in Production: VACUUM and bloat (why a table grows although you delete from it), connection pooling, partitioning and JSONB in depth. Indexes are the first lever for performance, and the next parts cover what keeps them fast after a year in production.

A practical checklist

Write the query first and look at its plan with EXPLAIN (ANALYZE, BUFFERS).
Start with a B-tree on the columns in WHERE and JOIN, equality columns first.
If only a small slice of rows matters, make it partial.
If the table is huge, append-only and time-ordered, try BRIN before B-tree.
For arrays, jsonb and text search, use GIN, and check that the matches are selective.
Add INCLUDE only for hot queries returning many rows, and keep VACUUM running.
Build with CREATE INDEX CONCURRENTLY, and review pg_stat_user_indexes every quarter.
Index the referencing column of every foreign key you join or delete by: PostgreSQL does not create it for you.
For UUID primary keys, prefer UUIDv7 over random UUIDv4 on PostgreSQL 18.

For query-level habits that go together with this, see SQL Query Optimization in 2026, and for the case of vectors inside Postgres, Do You Need a Vector Database?.

The Bottom Line

Use B-tree by default and measure before reaching for anything else. Make it partial when only a slice of rows matters, use BRIN when the table is huge and time-ordered, and use GIN when you search inside arrays and documents and the matches are rare. Be careful with the rest: a hash index was no faster, a covering index was 4.4 times bigger for a 1.4 times gain, and every extra index slowed inserts. The best index is the smallest one that answers your query, and the second best is the one you deleted.

Indexes are not free speed. Each one is a trade between read time, disk, memory and write time, so choose the type from the shape of the query and keep only the ones the statistics show are used.

Postgres, PostgreSQL and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada.

Originally published at alekseialeinikov.com

AI Gateway (LLM Gateway) Explained: What It Does, When You Need One and What It Costs

Aleksei Aleinikov — Thu, 22 Oct 2026 07:00:00 +0000

The first LLM feature is easy. You put an API key in an environment variable, call the provider’s SDK and ship. The trouble starts with the second and third: three provider keys copied into five services, nobody able to say which team spent the money last Tuesday, and one provider’s outage taking the whole product down with it. The usual answer to all three is the same piece of infrastructure, and it goes by two names: AI gateway and LLM gateway.

This guide explains what an AI gateway is, what sits inside one, how it differs from the API gateway you already run, when it is worth adding, what changes in your code, and what breaks once real traffic runs through it. It also measures the part that vendors’ landing pages skip: what the extra hop costs. Four gateways, one mock model, the same CPU budget for each, and a repository you can run yourself.

What is an AI gateway?

An AI gateway, also called an LLM gateway, is a proxy between your applications and the model providers they call. Every app sends its requests to one endpoint, usually OpenAI-compatible, with a key the gateway issued. The gateway checks who is calling, enforces request and token limits and budgets, picks the provider and model, retries or falls back when a provider fails, and logs tokens, cost and latency for every call. The real provider keys never leave it.

That is the whole idea: one door between your code and every model. The rest of this article is about what happens at that door.

AI gateway vs LLM gateway vs LLM proxy vs LLM router

The vocabulary is messier than the concept, so here are the terms you will meet in docs and vendor pages:

Term	What it means in practice
AI gateway	The full thing: auth, limits, budgets, routing, fallback, caching, guardrails, logs. Covers chat and usually also embeddings, images, audio and MCP tool calls.
LLM gateway	The same product under another name, with the emphasis on text models. Used interchangeably with “AI gateway”.
LLM proxy	The minimal version: one OpenAI-compatible endpoint that forwards and translates requests to many providers. Often the starting point of a gateway.
LLM router	The part that decides which model answers: by alias, price, latency, load or the content of the prompt. Sometimes a feature of a gateway, sometimes a separate service.
API gateway	The general-purpose proxy for HTTP APIs (Kong, Envoy, NGINX, cloud API gateways). Some of them grow AI plugins and become AI gateways too.

What sits inside an AI gateway

Every gateway on the market is a combination of the same building blocks. Some do all of them, some only a few:

Request path left to right, response path back. The provider keys live in the control plane and never reach an app.

Auth and virtual keys. Apps get keys issued by the gateway, one per team, app or user, and the gateway swaps them for the real provider key on the way out. Revoking a leaked key no longer means rotating your OpenAI key in twelve places.
Limits. Not just requests per second: tokens per minute and tokens per day , because one request can cost 200 tokens or 200,000. The algorithms are the same as for any API, and so are the mistakes; I wrote about those in rate limiting in practice.
Budgets. Spend caps per team, key or project, counted in money. The gateway knows the price of every model, so it can stop a runaway agent at a fixed amount instead of at the end of the month.
Routing, retries and fallback. Model aliases (chat-default maps to whatever you decide this week), load balancing across keys or regions, retries with backoff, and fallback to another provider when the first returns 429 or 5xx. Because providers have different APIs, the gateway translates request and response formats on the fly.
Caching. Exact-match caching of identical prompts is cheap and safe. Semantic caching answers prompts that are merely similar, which saves more and is wrong more often.
Guardrails. Checks on prompts and answers: personal data, secrets, banned topics, prompt-injection patterns. They help, but they are not a security boundary on their own; why, is in prompt injection defence.
Observability and cost. Every call logged with model, tokens, latency, cost, team and key. This is often the first reason a company installs a gateway: finance wants the report.

The gateway also gives the same treatment to self-hosted models. A vLLM or Ollama server becomes one more provider behind the same endpoint, with the same keys, limits and logs.

AI gateway vs API gateway

If you already run an API gateway, the obvious question is why it is not enough. It can be, partly. Kong is literally an API gateway with an AI plugin set. But a plain API gateway misses the parts that make LLM traffic different:

	API gateway	AI gateway
Unit of limits	requests per second	requests and tokens per minute, per key
Cost	not its concern	price per model, budgets, spend per team
Typical response	small JSON in milliseconds	long text, often streamed for seconds or minutes
Failover	another replica of the same service	another vendor with a different API and model
Cache key	URL and headers	the prompt, optionally by meaning
Content checks	schema, size, injection patterns	personal data, secrets, prompt injection, policy
Logs	status, latency, bytes	model, prompt and completion tokens, cost, user

The short version: an API gateway counts requests, an AI gateway counts tokens and money.

Do you need an AI gateway?

Not always. A gateway is one more service to run, secure and keep up to date, and it sits on the hot path of every model call. For a single app on a single provider it mostly adds a hop. Three questions decide it:

Most teams cross question 2 sooner than they expect: the second team that wants the same OpenAI key is the moment.

The middle option deserves a word. A client library that wraps many providers (the LiteLLM Python SDK, the Vercel AI SDK and others) gives you one API, retries and fallback inside your process, without a network hop. What it cannot give you is a central place for keys, budgets and logs across teams. That is the line where a library stops and a gateway starts.

And writing your own? A proxy that forwards OpenAI-format requests is an afternoon of work. The months go into what comes after: translating between provider APIs that keep changing (new endpoints, reasoning parameters, tool formats), counting tokens correctly on streams, keeping price tables current, and every edge case of server-sent events. Unless the gateway is your product, start from an existing one.

Putting one in: what changes in your code

Less than you might expect. Most gateways speak the OpenAI API, so the application change is two lines, the base URL and the key:

app.py: the only change on the client side


import os

from openai import OpenAI

client = OpenAI(

    base_url="https://llm-gateway.internal/v1", # the gateway, not the provider

    api_key=os.environ["LLM_GATEWAY_KEY"], # a virtual key for this app

    max_retries=0, # the gateway retries; see below

)

reply = client.chat.completions.create(

    model="chat-default", # an alias that the gateway resolves

    messages=[{"role": "user", "content": "Summarise this support ticket."}],

)

The model name is now an alias. Which provider and model sit behind chat-default, and what happens when it fails, lives in the gateway. In the LiteLLM proxy it looks like this:

config.yaml (LiteLLM proxy)


model_list:

  - model_name: chat-default

    litellm_params:

      model: anthropic/claude-sonnet-5-5

      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: chat-backup

    litellm_params:

      model: openai/gpt-6.1-sol

      api_key: os.environ/OPENAI_API_KEY

litellm_settings:

  num_retries: 2

  fallbacks: [{"chat-default": ["chat-backup"]}]

general_settings:

  master_key: os.environ/LITELLM_MASTER_KEY

Kong, Portkey and the managed gateways write it differently, but the shape is the same: aliases on the outside, providers and keys on the inside. Changing the default model becomes a config change instead of a redeploy of every service.

A rollout order that avoids surprises:

Route and observe, change nothing. Point one service at the gateway with generous limits and only logging on. You get the first honest cost report and a latency baseline.
Issue virtual keys, then revoke the direct ones. One key per app or team. A provider key still sitting in some .env file makes the gateway optional, and optional controls get bypassed.
Run budgets and limits in report-only mode first. Look at who would have been blocked last week before you block anyone.
Add fallback last, and test it. Run your evals against the fallback model before it ever serves a user. The production section below explains why.

The benchmark: what does the extra hop cost?

An AI gateway is one more network hop and one more process on every model call, so the fair question is what that costs. Vendor pages answer with a single number measured on their own hardware. I wanted all of them on the same terms.

The setup. A small Go server plays the model: it speaks the OpenAI chat API and answers instantly, with a 1.4 KB reply or a stream of 40 chunks. Because the model takes no time, every millisecond above a direct call is the gateway’s own work. Each gateway runs alone in Docker with the same budget of 2 CPUs and 2 GB , default settings, no caching, no guardrails and no logging database. A plain nginx reverse proxy sets the floor: the cost of one extra hop that does nothing. The load is open-loop, so requests keep arriving on schedule even when a gateway slows down, and a request only counts if the answer is complete and valid. Chat runs at 100, 500, 1,000 and 2,000 requests per second, streaming at 100 and 500; each scenario runs 3 rounds of 20 seconds after a warm-up, and the tables show the median round.

Bars: median time added over a direct call at 100 rps. Right: the highest tested rate with every answer valid and p99 under 100 ms.

Gateway (version)	Added to chat reply, p50 / p99	Added to first streamed token, p50	Chat, 2,000 rps	Stream, 500 rps	Peak CPU / memory
nginx 1.29 (floor)	+0.31 / +1.84 ms	+0.48 ms	100% valid	100% valid	18% / 10 MiB
Kong 3.9, `ai-proxy`	+0.85 / +2.55 ms	+1.07 ms	100% valid	100% valid	32% / 300 MiB
Portkey 1.15	+1.73 / +1.40 ms	+27.9 ms	100% valid	100% valid	118% / 80 MiB
LiteLLM 1.106, 2 workers	+3.82 / +3.72 ms	+10.1 ms	28% valid , 368 rps served	28% valid	200% / 2 GiB

Added latency is measured at 100 requests per second; CPU and memory are the peaks over all scenarios, and 200% means both CPUs of the budget were busy. What the numbers say:

The hop itself is cheap. Below their limits, nginx, Kong and Portkey added less than 2 ms to a chat reply and LiteLLM about 4 ms. A hosted model usually needs hundreds of milliseconds before its first token, so a gateway in normal operation is a rounding error next to it.
Capacity is where they really differ. With two workers on two CPUs, LiteLLM kept up to about 400 chat requests per second : 100% valid and a p99 of 51 ms in a separate step test. At 500 the median reply already took 0.7 s, at 1,000 only 60% of requests completed, and both CPUs sat at 100% the whole time. Streaming tops out lower, at about 100 per second : at 150 it served only 114 per second and the first token took two seconds. nginx, Kong and Portkey handled every scenario without a single invalid answer.
Memory differs by two orders of magnitude. nginx needed 10 MiB, Portkey 80 MiB, Kong 300 MiB. LiteLLM with two workers used 1.5 GiB while idle and stayed just under the 2 GB limit under load, without being killed. Give it more memory than this test did.
Portkey adds a fixed 28 ms to the first streamed token. It does not depend on load: 28 ms at 100 streams per second, 26 ms at 500. To check whether Portkey buffers whole streams, I slowed the mock down to 20 ms and then 100 ms between chunks. The full stream took exactly as long as a direct call, and the first chunk still arrived about 30 ms late. So the stream is passed through as it arrives, and the cost is a constant on the first chunk. For a chat window that is invisible; for a voice agent that chains several model calls it adds up.
Kong stays closest to the floor. About half a millisecond above plain nginx, which is what you would expect from Lua running inside nginx, with moderate memory. The catch is the license: open-source images stop at 3.9, so new AI plugin features land in the commercial versions.

What this test does not show: a real model’s latency, a logging database, caching or guardrails, and anything above 2 CPUs. Adding a database for keys and spend logs costs every gateway something, and LiteLLM is usually run with one. All of it ran on a single machine under Docker, which makes p99 values noisy; compare gateways within one run, not with numbers from other benchmarks. More replicas raise capacity for every gateway here. The point of the test is what one replica on a fixed budget does.

Tip

Check it yourself in three commands: git clone https://github.com/LF3551/ai-gateway-benchmark, then docker compose build and node scripts/bench.mjs && node scripts/report.mjs. The repository has the mock model, the load generator, every gateway config and every image pinned by digest. No provider account or API key is needed. Single-machine numbers are a sanity check, not a leaderboard: compare gateways within one run, not with numbers from another machine.

Self-hosted or managed?

Both kinds do the core job, whether you are choosing a first gateway or looking for a LiteLLM alternative. The difference is who sees your traffic, who runs the service, and how you pay.

	Type	Written in	License / pricing	Notes
LiteLLM	self-hosted (also a Python SDK)	Python	open source core, paid enterprise features	100+ providers, virtual keys, budgets, Postgres for keys and spend
Kong AI Gateway	self-hosted or Konnect	Lua on NGINX	the last open-source image is 3.9; newer Kong Gateway images need a license	a full API gateway with a large AI plugin set: proxy, semantic cache, guardrails, PII sanitizer, MCP proxy
Portkey Gateway	self-hosted or hosted	TypeScript (Node.js)	MIT; hosted plans from free (10,000 logged requests a month)	now part of Palo Alto Networks as Prisma AIRS AI Gateway; open-source 2.0 in pre-release
Cloudflare AI Gateway	managed	runs on Cloudflare’s network	core features free	caching, rate limiting, retries and fallback, logs; unified billing adds a fee on credits
Vercel AI Gateway	managed	runs on Vercel	no markup on provider token prices, also with your own keys	budgets per team, project, key or member; fallbacks
OpenRouter	managed	hosted service	pay per token through one account	one key for hundreds of models from many providers; check the current fees on its pricing page

Two practical notes from building the benchmark. Kong : the kong/kong-gateway images from 3.10 onwards start in read-only mode without a license and answered every request with 426, so the benchmark uses kong:3.9, the last open-source image, where the ai-proxy plugin works without one. LiteLLM : the 1.106 proxy refuses to start without a strong master key (UnsafeMasterKeyError), which is the right default and one more reason to read the next section.

Note

The European angle. A managed gateway sees every prompt and every answer, so under the GDPR its operator is a processor: you need a data processing agreement, and you need to know where the logs are stored and for how long. If that is hard to answer for your data, the gateway belongs in your own network, next to the self-hosted model servers it fronts.

What bites in production

On a diagram a gateway is a clean box. These are the parts that hurt once real traffic runs through it.

Streaming

Buffering. Any proxy on the path that buffers responses turns a stream into one late blob, and the user stares at an empty box. NGINX buffers by default (proxy_buffering on); switch it off for streaming routes on every hop, not only in the gateway.
Idle timeouts. Reasoning models can think for a minute before the first token. The common 60-second defaults, NGINX’s proxy_read_timeout or the idle timeout of an AWS Application Load Balancer, cut those requests off. The client sees a dropped connection, retries, and you pay twice.
Token counts. In OpenAI-style streaming, usage arrives only in the last chunk and only when requested (stream_options: {"include_usage": true}). A gateway that does not ask for it has to estimate, and its cost report drifts.
No fallback after the first token. Once a chunk has reached the client, the gateway cannot switch providers without sending a second, different answer. Fallback covers failures before the first chunk; after that, a broken stream is a client-side retry.

Fallback is not free

Another model is another product. Different tokenizer, context window, tool-calling quirks, JSON behaviour and refusal style. A prompt tuned for one model can come back in a different shape from the other, and your parsing breaks at the worst moment: during an outage.
Reasoning state does not travel. Encrypted reasoning from one provider cannot be read by another. LiteLLM’s documentation describes dropping it on fallback, so the backup model starts that turn’s thinking from scratch. Long agent runs that fail over get slower and may take a different path.
Retries multiply. The OpenAI Python SDK retries twice by default. Two retries in the SDK, two in the gateway and two in your own code turn one failed call into up to 27 attempts against a provider that is already rate-limiting you. Retry in one layer, the gateway, and set the client to zero, as in the snippet above.
Budgets and access rules must cover the fallback target. A request for a cheap model that falls back to an expensive one is billed at the expensive price. LiteLLM re-checks budget and model access for every fallback target; whatever you run, test that a key without access to a model cannot reach it through a fallback.

Budgets are estimates

A gateway cannot know what a request costs until the answer exists. It either reserves the worst case from max_tokens (safe, but blocks early) or charges afterwards (accurate, but overshoots: fifty parallel agent calls all pass the check before the first one is billed). With several gateway replicas the counters live in a shared store such as Redis and have the same race conditions as any distributed rate limiter. Treat a budget as a soft cap with a known overshoot, and alert well before it.

Caching can leak, and can break the cheaper cache

The cache key must include everything that changes the answer: model, system prompt, parameters, tools, and the tenant. A shared semantic cache that ignores the tenant can hand one customer’s answer, with their data in it, to another customer.
Providers cache too. OpenAI and Anthropic bill repeated prompt prefixes at a discount, but only when the prefix is byte-for-byte identical. A gateway that injects a timestamp, a request ID or per-user guardrail text at the start of the prompt breaks that prefix and quietly raises your bill. Anything dynamic goes at the end.

The gateway is now on every critical path

Once all model traffic goes through it, a gateway outage is an outage of every AI feature you have. Run at least two replicas, keep the request path stateless, and decide per function what happens when its database or Redis is down: logging can fail open, authentication and budgets should fail closed. Deploy it close to the apps, because every hop shows up in time to first token.

Agents multiply everything

One click in an agent product can mean dozens of model calls and tool calls. Per-request limits stop meaning much; you want budgets and step caps per run, a loop detector, and the run ID on every log line so a single runaway task is visible as one thing. Many gateways now also sit in front of MCP tool calls, which is the same idea applied to tools: one place that decides which agent may call what.

For logs, use a format your stack already understands. OpenTelemetry defines GenAI semantic conventions (gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens), and gateways that export them plug into the tracing you already run. Do not log full prompts and answers by default; the next section shows why.

A gateway holds all your keys: the LiteLLM 1.107.0 lesson

Putting every provider key behind one door also means one door to break. On 21 October 2026 , all seven wheels of LiteLLM 1.107.0 on PyPI shipped with two extra files, cook.pth and sitecustomize.py, which Python runs at startup in every process of the environment. According to the analysis by SafeDep and LiteLLM’s incident report, the first collected SSH keys, cloud and Kubernetes credentials, CI secrets, browser passwords, tokens of AI coding tools and environment variables, and the second started a daemon that fetched and ran new code every hour. For a gateway the worst detail is this: when DATABASE_URL was set, the stealer also dumped the proxy’s credentials and model tables, which means every provider key the gateway stored.

The timeline, in UTC: the wheels went up at 11:39–11:40, compromised Docker images followed at 11:46 (tags v1.107.0, latest, main-latest, main-stable), PyPI removed the release by 13:23, and the last Docker tags were fixed at 14:20. Clean versions are 1.106.2 and the 1.107.0 release candidates. The root cause is the uncomfortable part for every gateway operator. The attacker held GitHub CLI tokens of three developers, and LiteLLM believes they came from the logs of an internal LiteLLM deployment that was reachable from the internet : a coding agent had put the token into a response body, and the gateway logged response bodies. With those tokens the attacker pointed the release workflow at a lookalike repository, and the official pipeline built, signed and published the result, so a valid signature did not help.

What to take from it, whichever gateway you run:

Pin by digest, update on purpose. latest and main-stable were among the poisoned tags; the benchmark repository pins every image by sha256. Pinning is not “never update”: LiteLLM suspects the way into its internal deployment was a recently patched vulnerability. The npm supply-chain checklist applies to PyPI almost word for word.
Logged prompts and answers are secrets. Whatever passes through the gateway ends up in its logs: tokens pasted by users, keys echoed by agents, personal data. Redact before storing, keep retention short and restrict who can read them.
Treat the gateway’s admin side as the crown jewels. No admin UI or API on the internet, SSO in front of it, and an alert on every new user or key.
Keep provider keys out of the gateway’s database if you can. Read them from a secret manager at runtime and rotate them; a stolen database dump is then worth much less.
Give the gateway its own narrow network path. It needs to reach the providers, not your whole cloud account or the instance metadata service.
If you installed 1.107.0 anywhere, follow the incident report and rotate every key that machine could read, not only the provider keys.

The bottom line

An AI gateway, or LLM gateway, is not a new idea. It is the API gateway pattern applied to a kind of traffic that is billed by the token, streams for minutes and fails over between vendors. When the second team, the second provider or the first compliance question arrives, it pays for itself.

The benchmark puts a number on the fear of the extra hop: a gateway with enough capacity adds a millisecond or a few, far less than any model takes to answer. What separates the options is how much traffic one replica carries, how it streams, where it runs and who holds the keys.

To measure it on your own hardware, the benchmark repository runs everything with Docker in three commands.

Originally published at alekseialeinikov.com

AI Gateway (LLM Gateway) erklärt: was es tut, wann Sie eins brauchen und was es kostet

Aleksei Aleinikov — Thu, 22 Oct 2026 07:00:00 +0000

Die erste LLM-Funktion ist einfach. Ein API-Schlüssel in eine Umgebungsvariable, das SDK des Anbieters aufrufen, ausliefern. Ärger macht die zweite und dritte: drei Anbieterschlüssel in fünf Diensten, niemand kann sagen, welches Team letzten Dienstag das Geld ausgegeben hat, und der Ausfall eines Anbieters reißt das ganze Produkt mit. Die übliche Antwort auf alle drei Probleme ist dasselbe Stück Infrastruktur, und es hat zwei Namen: AI Gateway und LLM Gateway.

Dieser Leitfaden erklärt, was ein AI Gateway ist, was darin steckt, wie es sich von Ihrem vorhandenen API Gateway unterscheidet, wann es sich lohnt, was sich in Ihrem Code ändert und was bricht, sobald echter Verkehr hindurchläuft. Und er misst den Teil, den die Landingpages der Anbieter auslassen: was der zusätzliche Hop kostet. Vier Gateways, ein Mock-Modell, dasselbe CPU-Budget für jedes und ein Repository, das Sie selbst ausführen können.

Was ist ein AI Gateway?

Ein AI Gateway, auch LLM Gateway genannt, ist ein Proxy zwischen Ihren Anwendungen und den Modellanbietern, die sie aufrufen. Jede Anwendung schickt ihre Anfragen an einen Endpunkt, meist OpenAI-kompatibel, mit einem Schlüssel, den das Gateway ausgegeben hat. Das Gateway prüft, wer anfragt, setzt Request- und Token-Limits sowie Budgets durch, wählt Anbieter und Modell, wiederholt oder weicht aus, wenn ein Anbieter ausfällt, und protokolliert Tokens, Kosten und Latenz jedes Aufrufs. Die echten Anbieterschlüssel verlassen es nie.

Das ist die ganze Idee: eine Tür zwischen Ihrem Code und jedem Modell. Der Rest dieses Artikels handelt davon, was an dieser Tür passiert.

AI Gateway vs. LLM Gateway vs. LLM Proxy vs. LLM Router

Das Vokabular ist unübersichtlicher als das Konzept. Diese Begriffe begegnen Ihnen in Dokus und auf Anbieterseiten:

Begriff	Was er in der Praxis bedeutet
AI Gateway	Das Gesamtpaket: Auth, Limits, Budgets, Routing, Fallback, Caching, Guardrails, Logs. Deckt Chat und meist auch Embeddings, Bilder, Audio und MCP-Tool-Aufrufe ab.
LLM Gateway	Dasselbe Produkt unter anderem Namen, mit Schwerpunkt auf Textmodellen. Wird austauschbar mit “AI Gateway” verwendet.
LLM Proxy	Die minimale Variante: ein OpenAI-kompatibler Endpunkt, der Anfragen an viele Anbieter weiterleitet und übersetzt. Oft der Ausgangspunkt eines Gateways.
LLM Router	Der Teil, der entscheidet, welches Modell antwortet: nach Alias, Preis, Latenz, Last oder Inhalt des Prompts. Mal Funktion eines Gateways, mal eigener Dienst.
API Gateway	Der allgemeine Proxy für HTTP-APIs (Kong, Envoy, NGINX, API Gateways der Clouds). Manche bekommen KI-Plugins und werden so ebenfalls zu AI Gateways.

Was in einem AI Gateway steckt

Jedes Gateway am Markt kombiniert dieselben Bausteine. Manche bieten alle, manche nur einige:

Anfrageweg von links nach rechts, Antwortweg zurück. Die Anbieterschlüssel liegen in der Control Plane und erreichen nie eine Anwendung.

Auth und virtuelle Schlüssel. Anwendungen bekommen Schlüssel vom Gateway, je Team, Anwendung oder Nutzer, und das Gateway tauscht sie auf dem Weg nach draußen gegen den echten Anbieterschlüssel. Ein geleakter Schlüssel bedeutet nicht mehr, den OpenAI-Schlüssel an zwölf Stellen zu rotieren.
Limits. Nicht nur Anfragen pro Sekunde, sondern Tokens pro Minute und Tokens pro Tag , denn eine Anfrage kann 200 oder 200.000 Tokens kosten. Die Algorithmen sind dieselben wie bei jeder API, die Fehler auch; dazu habe ich Rate Limiting in der Praxis geschrieben.
Budgets. Ausgabengrenzen je Team, Schlüssel oder Projekt, in Geld gezählt. Das Gateway kennt den Preis jedes Modells und kann einen außer Kontrolle geratenen Agenten bei einem festen Betrag stoppen statt am Monatsende.
Routing, Retries und Fallback. Modell-Aliase (chat-default zeigt auf das, was Sie diese Woche festlegen), Lastverteilung über Schlüssel oder Regionen, Wiederholungen mit Backoff und Ausweichen auf einen anderen Anbieter, wenn der erste 429 oder 5xx liefert. Weil Anbieter unterschiedliche APIs haben, übersetzt das Gateway Anfrage- und Antwortformate im Flug.
Caching. Exaktes Caching identischer Prompts ist billig und sicher. Semantisches Caching beantwortet auch nur ähnliche Prompts, spart mehr und liegt öfter daneben.
Guardrails. Prüfungen von Prompts und Antworten: personenbezogene Daten, Geheimnisse, gesperrte Themen, Muster von Prompt Injection. Sie helfen, sind allein aber keine Sicherheitsgrenze; warum, steht in Prompt-Injection-Abwehr.
Observability und Kosten. Jeder Aufruf protokolliert mit Modell, Tokens, Latenz, Kosten, Team und Schlüssel. Oft ist das der erste Grund für ein Gateway: Die Finanzabteilung will den Bericht.

Selbst betriebene Modelle behandelt das Gateway genauso. Ein vLLM- oder Ollama-Server wird ein weiterer Anbieter hinter demselben Endpunkt, mit denselben Schlüsseln, Limits und Logs.

AI Gateway vs. API Gateway

Wenn Sie bereits ein API Gateway betreiben, liegt die Frage nahe, warum das nicht reicht. Teilweise reicht es. Kong ist buchstäblich ein API Gateway mit KI-Plugins. Einem reinen API Gateway fehlt aber, was LLM-Verkehr anders macht:

	API Gateway	AI Gateway
Einheit der Limits	Anfragen pro Sekunde	Anfragen und Tokens pro Minute, je Schlüssel
Kosten	nicht sein Thema	Preis je Modell, Budgets, Ausgaben je Team
Typische Antwort	kleines JSON in Millisekunden	langer Text, oft über Sekunden oder Minuten gestreamt
Failover	andere Replik desselben Dienstes	anderer Anbieter mit anderer API und anderem Modell
Cache-Schlüssel	URL und Header	der Prompt, optional nach Bedeutung
Inhaltsprüfung	Schema, Größe, Injection-Muster	personenbezogene Daten, Geheimnisse, Prompt Injection, Richtlinien
Logs	Status, Latenz, Bytes	Modell, Prompt- und Completion-Tokens, Kosten, Nutzer

Kurz: Ein API Gateway zählt Anfragen, ein AI Gateway zählt Tokens und Geld.

Brauchen Sie ein AI Gateway?

Nicht immer. Ein Gateway ist ein weiterer Dienst, den Sie betreiben, absichern und aktuell halten müssen, und es liegt im heißen Pfad jedes Modellaufrufs. Für eine einzelne Anwendung mit einem Anbieter fügt es vor allem einen Hop hinzu. Drei Fragen entscheiden:

Die meisten Teams kommen schneller an Frage 2 als gedacht: Das zweite Team, das denselben OpenAI-Schlüssel will, ist der Moment.

Die mittlere Option verdient einen Satz. Eine Client-Bibliothek , die viele Anbieter kapselt (das LiteLLM-Python-SDK, das Vercel AI SDK und andere), liefert eine API, Retries und Fallback in Ihrem Prozess, ohne Netzwerk-Hop. Was sie nicht liefern kann, ist ein zentraler Ort für Schlüssel, Budgets und Logs über Teams hinweg. An dieser Linie hört die Bibliothek auf und das Gateway fängt an.

Und selbst schreiben? Ein Proxy, der Anfragen im OpenAI-Format weiterleitet, ist ein Nachmittag Arbeit. Die Monate stecken in dem, was danach kommt: Übersetzen zwischen Anbieter-APIs, die sich ständig ändern (neue Endpunkte, Reasoning-Parameter, Tool-Formate), korrektes Token-Zählen bei Streams, aktuelle Preistabellen und jeder Sonderfall von Server-Sent Events. Solange das Gateway nicht Ihr Produkt ist, starten Sie mit einem vorhandenen.

Einbau: was sich in Ihrem Code ändert

Weniger als gedacht. Die meisten Gateways sprechen die OpenAI-API, die Änderung in der Anwendung sind also zwei Zeilen: Basis-URL und Schlüssel.

app.py: die einzige Änderung auf Client-Seite


import os

from openai import OpenAI

client = OpenAI(

    base_url="https://llm-gateway.internal/v1", # das Gateway, nicht der Anbieter

    api_key=os.environ["LLM_GATEWAY_KEY"], # ein virtueller Schlüssel für diese App

    max_retries=0, # Retries macht das Gateway, siehe unten

)

reply = client.chat.completions.create(

    model="chat-default", # ein Alias, den das Gateway auflöst

    messages=[{"role": "user", "content": "Fasse dieses Support-Ticket zusammen."}],

)

Der Modellname ist jetzt ein Alias. Welcher Anbieter und welches Modell hinter chat-default stehen und was bei einem Fehler passiert, liegt im Gateway. Im LiteLLM-Proxy sieht das so aus:

config.yaml (LiteLLM-Proxy)


model_list:

  - model_name: chat-default

    litellm_params:

      model: anthropic/claude-sonnet-5-5

      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: chat-backup

    litellm_params:

      model: openai/gpt-6.1-sol

      api_key: os.environ/OPENAI_API_KEY

litellm_settings:

  num_retries: 2

  fallbacks: [{"chat-default": ["chat-backup"]}]

general_settings:

  master_key: os.environ/LITELLM_MASTER_KEY

Kong, Portkey und die gemanagten Gateways schreiben es anders, die Form ist aber dieselbe: Aliase nach außen, Anbieter und Schlüssel innen. Ein anderes Standardmodell wird zur Konfigurationsänderung statt zum Redeploy aller Dienste.

Eine Einführungsreihenfolge ohne böse Überraschungen:

Umleiten und beobachten, nichts ändern. Einen Dienst mit großzügigen Limits und nur aktiviertem Logging auf das Gateway zeigen lassen. Sie bekommen den ersten ehrlichen Kostenbericht und eine Latenz-Baseline.
Virtuelle Schlüssel ausgeben, dann die direkten widerrufen. Ein Schlüssel je App oder Team. Ein Anbieterschlüssel, der noch in irgendeiner .env-Datei liegt, macht das Gateway optional, und optionale Kontrollen werden umgangen.
Budgets und Limits zuerst nur berichten lassen. Prüfen Sie, wer letzte Woche blockiert worden wäre, bevor Sie jemanden blockieren.
Fallback zuletzt, und getestet. Lassen Sie Ihre Evals gegen das Fallback-Modell laufen, bevor es je einen Nutzer bedient. Warum, steht im Abschnitt zum Betrieb weiter unten.

Der Benchmark: was kostet der zusätzliche Hop?

Ein AI Gateway ist ein zusätzlicher Netzwerk-Hop und ein zusätzlicher Prozess bei jedem Modellaufruf, die faire Frage ist also, was das kostet. Anbieterseiten antworten mit einer einzelnen Zahl, gemessen auf eigener Hardware. Ich wollte alle unter denselben Bedingungen.

Der Aufbau. Ein kleiner Go-Server spielt das Modell: Er spricht die OpenAI-Chat-API und antwortet sofort, mit einer 1,4-KB-Antwort oder einem Stream aus 40 Chunks. Weil das Modell keine Zeit braucht, ist jede Millisekunde über einem direkten Aufruf Arbeit des Gateways. Jedes Gateway läuft allein in Docker mit demselben Budget von 2 CPUs und 2 GB , Standardeinstellungen, ohne Caching, ohne Guardrails und ohne Logging-Datenbank. Ein einfacher nginx -Reverse-Proxy setzt die Untergrenze: die Kosten eines zusätzlichen Hops, der nichts tut. Die Last ist open-loop, Anfragen kommen also weiter nach Plan, auch wenn ein Gateway langsamer wird, und eine Anfrage zählt nur, wenn die Antwort vollständig und gültig ist. Chat läuft mit 100, 500, 1.000 und 2.000 Anfragen pro Sekunde, Streaming mit 100 und 500; jedes Szenario läuft 3 Runden zu 20 Sekunden nach einer Aufwärmphase, die Tabellen zeigen die mittlere Runde.

Balken: mittlere Zusatzzeit gegenüber einem direkten Aufruf bei 100 rps. Rechts: die höchste getestete Rate mit nur gültigen Antworten und p99 unter 100 ms.

Gateway (Version)	Zusatz zur Chat-Antwort, p50 / p99	Zusatz zum ersten gestreamten Token, p50	Chat, 2.000 rps	Stream, 500 rps	Spitze CPU / Speicher
nginx 1.29 (Untergrenze)	+0,31 / +1,84 ms	+0,48 ms	100 % gültig	100 % gültig	18 % / 10 MiB
Kong 3.9, `ai-proxy`	+0,85 / +2,55 ms	+1,07 ms	100 % gültig	100 % gültig	32 % / 300 MiB
Portkey 1.15	+1,73 / +1,40 ms	+27,9 ms	100 % gültig	100 % gültig	118 % / 80 MiB
LiteLLM 1.106, 2 Worker	+3,82 / +3,72 ms	+10,1 ms	28 % gültig , 368 rps bedient	28 % gültig	200 % / 2 GiB

Die Zusatzlatenz ist bei 100 Anfragen pro Sekunde gemessen; CPU und Speicher sind die Spitzen über alle Szenarien, 200 % heißt, beide CPUs des Budgets waren ausgelastet. Was die Zahlen sagen:

Der Hop selbst ist billig. Unterhalb ihrer Grenzen fügten nginx, Kong und Portkey einer Chat-Antwort weniger als 2 ms hinzu, LiteLLM etwa 4 ms. Ein gehostetes Modell braucht meist Hunderte Millisekunden bis zum ersten Token, ein Gateway im Normalbetrieb ist daneben ein Rundungsfehler.
Bei der Kapazität unterscheiden sie sich wirklich. Mit zwei Workern auf zwei CPUs hielt LiteLLM etwa 400 Chat-Anfragen pro Sekunde durch: 100 % gültig und p99 von 51 ms in einem separaten Stufentest. Bei 500 dauerte die mittlere Antwort schon 0,7 s, bei 1.000 kamen nur 60 % der Anfragen durch, und beide CPUs standen die ganze Zeit auf 100 %. Streaming endet früher, bei etwa 100 pro Sekunde : Bei 150 bediente es nur 114 pro Sekunde, und das erste Token kam nach zwei Sekunden. nginx, Kong und Portkey bewältigten jedes Szenario ohne eine einzige ungültige Antwort.
Der Speicher unterscheidet sich um zwei Größenordnungen. nginx brauchte 10 MiB, Portkey 80 MiB, Kong 300 MiB. LiteLLM mit zwei Workern belegte im Leerlauf 1,5 GiB und blieb unter Last knapp unter der 2-GB-Grenze, ohne beendet zu werden. Geben Sie ihm mehr Speicher als dieser Test.
Portkey fügt dem ersten gestreamten Token feste 28 ms hinzu. Das hängt nicht von der Last ab: 28 ms bei 100 Streams pro Sekunde, 26 ms bei 500. Um zu prüfen, ob Portkey ganze Streams puffert, habe ich den Mock auf 20 ms und dann 100 ms zwischen den Chunks verlangsamt. Der gesamte Stream dauerte genau so lange wie ein direkter Aufruf, und der erste Chunk kam trotzdem rund 30 ms später. Der Stream wird also so durchgereicht, wie er ankommt, und die Kosten sind eine Konstante beim ersten Chunk. In einem Chatfenster ist das unsichtbar; bei einem Sprachagenten, der mehrere Modellaufrufe verkettet, summiert es sich.
Kong bleibt am nächsten an der Untergrenze. Etwa eine halbe Millisekunde über reinem nginx, wie man es von Lua innerhalb von nginx erwartet, bei moderatem Speicher. Der Haken ist die Lizenz: Open-Source-Images enden bei 3.9, neue KI-Plugin-Funktionen landen in den kommerziellen Versionen.

Was dieser Test nicht zeigt: die Latenz eines echten Modells, eine Logging-Datenbank, Caching oder Guardrails und alles über 2 CPUs. Eine Datenbank für Schlüssel und Ausgaben-Logs kostet jedes Gateway etwas, und LiteLLM läuft meist mit einer. Alles lief auf einer einzigen Maschine unter Docker, deshalb sind die p99-Werte verrauscht; vergleichen Sie Gateways innerhalb eines Laufs, nicht mit Zahlen aus anderen Benchmarks. Mehr Replikas erhöhen die Kapazität bei jedem Gateway hier. Der Test zeigt, was eine Replika mit festem Budget leistet.

Tipp

Prüfen Sie es selbst in drei Befehlen: git clone https://github.com/LF3551/ai-gateway-benchmark, dann docker compose build und node scripts/bench.mjs && node scripts/report.mjs. Das Repository enthält das Mock-Modell, den Lastgenerator, jede Gateway-Konfiguration und jedes Image per Digest gepinnt. Sie brauchen weder ein Konto bei einem Anbieter noch einen API-Schlüssel. Messungen auf einer Maschine sind eine Plausibilitätsprüfung, keine Rangliste: Vergleichen Sie Gateways innerhalb eines Laufs, nicht mit Zahlen von einer anderen Maschine.

Selbst betreiben oder gemanagt?

Beide Arten erledigen die Kernaufgabe, ob Sie Ihr erstes Gateway wählen oder eine Alternative zu LiteLLM suchen. Der Unterschied: wer Ihren Verkehr sieht, wer den Dienst betreibt und wie Sie bezahlen.

	Art	Geschrieben in	Lizenz / Preis	Hinweise
LiteLLM	selbst betrieben (auch Python-SDK)	Python	Open-Source-Kern, kostenpflichtige Enterprise-Funktionen	über 100 Anbieter, virtuelle Schlüssel, Budgets, Postgres für Schlüssel und Ausgaben
Kong AI Gateway	selbst betrieben oder Konnect	Lua auf NGINX	letztes Open-Source-Image ist 3.9; neuere Kong-Gateway-Images brauchen eine Lizenz	vollwertiges API Gateway mit großem KI-Plugin-Set: Proxy, semantischer Cache, Guardrails, PII Sanitizer, MCP Proxy
Portkey Gateway	selbst betrieben oder gehostet	TypeScript (Node.js)	MIT; gehostete Pläne ab kostenlos (10.000 protokollierte Anfragen pro Monat)	gehört jetzt zu Palo Alto Networks als Prisma AIRS AI Gateway; Open-Source-2.0 als Pre-Release
Cloudflare AI Gateway	gemanagt	läuft im Netz von Cloudflare	Kernfunktionen kostenlos	Caching, Rate Limiting, Retries und Fallback, Logs; Unified Billing erhebt eine Gebühr auf Guthaben
Vercel AI Gateway	gemanagt	läuft bei Vercel	kein Aufschlag auf die Token-Preise der Anbieter, auch mit eigenen Schlüsseln	Budgets je Team, Projekt, Schlüssel oder Mitglied; Fallbacks
OpenRouter	gemanagt	gehosteter Dienst	Bezahlung pro Token über ein Konto	ein Schlüssel für Hunderte Modelle vieler Anbieter; aktuelle Gebühren auf der Preisseite prüfen

Zwei praktische Hinweise aus dem Bau des Benchmarks. Kong : Die Images kong/kong-gateway ab 3.10 starten ohne Lizenz im Read-only-Modus und beantworteten jede Anfrage mit 426, deshalb nutzt der Benchmark kong:3.9, das letzte Open-Source-Image, in dem das Plugin ai-proxy ohne Lizenz funktioniert. LiteLLM : Der Proxy in 1.106 startet ohne starken Master Key nicht (UnsafeMasterKeyError). Das ist der richtige Standard und ein Grund mehr, den nächsten Abschnitt zu lesen.

Hinweis

Der europäische Blick. Ein gemanagtes Gateway sieht jeden Prompt und jede Antwort, sein Betreiber ist nach DSGVO also Auftragsverarbeiter: Sie brauchen einen Auftragsverarbeitungsvertrag und müssen wissen, wo die Logs liegen und wie lange. Lässt sich das für Ihre Daten schwer beantworten, gehört das Gateway ins eigene Netz, neben die selbst betriebenen Modellserver, vor denen es steht.

Was im Betrieb wehtut

Im Diagramm ist ein Gateway ein sauberer Kasten. Diese Stellen schmerzen, sobald echter Verkehr hindurchläuft.

Streaming

Pufferung. Jeder Proxy auf dem Weg, der Antworten puffert, macht aus einem Stream einen späten Block, und der Nutzer starrt auf ein leeres Feld. NGINX puffert standardmäßig (proxy_buffering on); schalten Sie das für Streaming-Routen auf jedem Hop ab, nicht nur im Gateway.
Idle-Timeouts. Reasoning-Modelle denken mitunter eine Minute vor dem ersten Token. Die üblichen 60-Sekunden-Standards, proxy_read_timeout von NGINX oder das Idle-Timeout eines AWS Application Load Balancers, schneiden diese Anfragen ab. Der Client sieht eine abgebrochene Verbindung, wiederholt, und Sie zahlen doppelt.
Token-Zählung. Beim Streaming im OpenAI-Stil kommt die Nutzung erst im letzten Chunk und nur auf Anfrage (stream_options: {"include_usage": true}). Ein Gateway, das sie nicht anfordert, muss schätzen, und sein Kostenbericht driftet.
Kein Fallback nach dem ersten Token. Ist ein Chunk beim Client angekommen, kann das Gateway nicht mehr den Anbieter wechseln, ohne eine zweite, andere Antwort zu senden. Fallback deckt Fehler vor dem ersten Chunk ab; danach ist ein abgebrochener Stream ein Retry auf Client-Seite.

Fallback ist nicht gratis

Ein anderes Modell ist ein anderes Produkt. Anderer Tokenizer, anderes Kontextfenster, andere Eigenheiten beim Tool Calling, bei JSON und bei Ablehnungen. Ein auf ein Modell abgestimmter Prompt kommt vom anderen in anderer Form zurück, und Ihr Parsing bricht im schlechtesten Moment: während eines Ausfalls.
Reasoning-Zustand wandert nicht mit. Verschlüsseltes Reasoning eines Anbieters kann ein anderer nicht lesen. Die LiteLLM-Dokumentation beschreibt, dass es beim Fallback verworfen wird, das Backup-Modell denkt diesen Schritt also neu. Lange Agentenläufe mit Failover werden langsamer und nehmen eventuell einen anderen Weg.
Retries multiplizieren sich. Das OpenAI-Python-SDK wiederholt standardmäßig zweimal. Zwei Retries im SDK, zwei im Gateway und zwei im eigenen Code machen aus einem fehlgeschlagenen Aufruf bis zu 27 Versuche gegen einen Anbieter, der Sie ohnehin schon drosselt. Wiederholen Sie in einer Schicht, dem Gateway, und setzen Sie den Client auf null, wie im Beispiel oben.
Budgets und Zugriffsregeln müssen das Fallback-Ziel abdecken. Eine Anfrage an ein billiges Modell, die auf ein teures ausweicht, wird zum teuren Preis abgerechnet. LiteLLM prüft Budget und Modellzugriff für jedes Fallback-Ziel erneut; egal, was Sie betreiben: Testen Sie, dass ein Schlüssel ohne Zugriff auf ein Modell es nicht über einen Fallback erreicht.

Budgets sind Schätzungen

Ein Gateway weiß erst, was eine Anfrage kostet, wenn die Antwort existiert. Entweder reserviert es den schlimmsten Fall aus max_tokens (sicher, blockiert aber früh) oder rechnet hinterher ab (genau, schießt aber über: Fünfzig parallele Agentenaufrufe bestehen alle die Prüfung, bevor der erste abgerechnet ist). Mit mehreren Gateway-Replikas liegen die Zähler in einem gemeinsamen Speicher wie Redis und haben dieselben Race Conditions wie jeder verteilte Rate Limiter. Behandeln Sie ein Budget als weiche Grenze mit bekanntem Überschuss und alarmieren Sie deutlich vorher.

Caching kann leaken und den billigeren Cache zerstören

Der Cache-Schlüssel muss alles enthalten, was die Antwort ändert: Modell, System-Prompt, Parameter, Tools und den Mandanten. Ein geteilter semantischer Cache, der den Mandanten ignoriert, kann die Antwort eines Kunden samt dessen Daten an einen anderen Kunden ausliefern.
Anbieter cachen auch. OpenAI und Anthropic rechnen wiederholte Prompt-Präfixe mit Rabatt ab, aber nur, wenn das Präfix Byte für Byte identisch ist. Ein Gateway, das einen Zeitstempel, eine Request-ID oder nutzerspezifischen Guardrail-Text an den Anfang des Prompts setzt, zerstört dieses Präfix und erhöht still Ihre Rechnung. Alles Dynamische gehört ans Ende.

Das Gateway liegt jetzt auf jedem kritischen Pfad

Läuft aller Modellverkehr darüber, ist ein Ausfall des Gateways ein Ausfall jeder KI-Funktion, die Sie haben. Betreiben Sie mindestens zwei Replikas, halten Sie den Anfragepfad zustandslos und entscheiden Sie je Funktion, was passiert, wenn Datenbank oder Redis weg sind: Logging darf offen ausfallen, Authentifizierung und Budgets sollten geschlossen ausfallen. Platzieren Sie es nah an den Anwendungen, denn jeder Hop zeigt sich in der Zeit bis zum ersten Token.

Agenten multiplizieren alles

Ein Klick in einem Agentenprodukt kann Dutzende Modell- und Tool-Aufrufe bedeuten. Limits pro Anfrage sagen dann wenig; Sie brauchen Budgets und Schrittgrenzen pro Lauf, eine Schleifenerkennung und die Lauf-ID in jeder Logzeile, damit eine einzelne außer Kontrolle geratene Aufgabe als ein Ding sichtbar wird. Viele Gateways stehen inzwischen auch vor MCP-Tool-Aufrufen, dieselbe Idee für Tools: ein Ort, der entscheidet, welcher Agent was aufrufen darf.

Für Logs nehmen Sie ein Format, das Ihr Stack schon versteht. OpenTelemetry definiert GenAI Semantic Conventions (gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens), und Gateways, die sie exportieren, docken an das vorhandene Tracing an. Protokollieren Sie vollständige Prompts und Antworten nicht standardmäßig; warum, zeigt der nächste Abschnitt.

Ein Gateway hält alle Ihre Schlüssel: die Lehre aus LiteLLM 1.107.0

Wer jeden Anbieterschlüssel hinter eine Tür legt, hat auch nur eine Tür, die aufgebrochen werden muss. Am 21. Oktober 2026 enthielten alle sieben Wheels von LiteLLM 1.107.0 auf PyPI zwei zusätzliche Dateien, cook.pth und sitecustomize.py, die Python beim Start jedes Prozesses der Umgebung ausführt. Laut der Analyse von SafeDep und dem Incident Report von LiteLLM sammelte die erste SSH-Schlüssel, Cloud- und Kubernetes-Zugangsdaten, CI-Geheimnisse, Browser-Passwörter, Tokens von KI-Coding-Tools und Umgebungsvariablen, die zweite startete einen Daemon, der stündlich neuen Code holte und ausführte. Für ein Gateway ist dieses Detail das schlimmste: War DATABASE_URL gesetzt, las der Stealer auch die Credential- und Modelltabellen des Proxys aus, also jeden Anbieterschlüssel, den das Gateway gespeichert hatte.

Der Ablauf in UTC: Die Wheels gingen um 11:39–11:40 online, kompromittierte Docker-Images folgten um 11:46 (Tags v1.107.0, latest, main-latest, main-stable), PyPI entfernte das Release bis 13:23, die letzten Docker-Tags waren um 14:20 korrigiert. Sauber sind 1.106.2 und die Release Candidates von 1.107.0. Die Ursache ist der unbequeme Teil für jeden Gateway-Betreiber. Der Angreifer besaß GitHub-CLI-Tokens von drei Entwicklern, und LiteLLM geht davon aus, dass sie aus den Logs einer internen LiteLLM-Instanz stammten, die aus dem Internet erreichbar war : Ein Coding-Agent hatte das Token in einen Response Body geschrieben, und das Gateway protokollierte Response Bodies. Mit diesen Tokens richtete der Angreifer den Release-Workflow auf ein Lookalike-Repository, und die offizielle Pipeline baute, signierte und veröffentlichte das Ergebnis. Eine gültige Signatur half also nicht.

Was daraus folgt, egal welches Gateway Sie betreiben:

Per Digest pinnen, bewusst aktualisieren. latest und main-stable gehörten zu den vergifteten Tags; das Benchmark-Repository pinnt jedes Image per sha256. Pinnen heißt nicht “nie aktualisieren”: LiteLLM vermutet als Einstieg in die interne Instanz eine kürzlich gepatchte Schwachstelle. Die Checkliste gegen npm-Lieferkettenangriffe gilt für PyPI fast wörtlich.
Protokollierte Prompts und Antworten sind Geheimnisse. Was durch das Gateway läuft, landet in seinen Logs: von Nutzern eingefügte Tokens, von Agenten zurückgegebene Schlüssel, personenbezogene Daten. Vor dem Speichern schwärzen, kurze Aufbewahrung, wenige Leserechte.
Die Admin-Seite des Gateways ist das Kronjuwel. Keine Admin-Oberfläche oder -API im Internet, SSO davor und ein Alarm bei jedem neuen Nutzer oder Schlüssel.
Anbieterschlüssel möglichst nicht in der Datenbank des Gateways. Zur Laufzeit aus einem Secret Manager lesen und rotieren; ein gestohlener Datenbank-Dump ist dann deutlich weniger wert.
Dem Gateway einen eigenen, engen Netzwerkpfad geben. Es muss die Anbieter erreichen, nicht Ihr ganzes Cloud-Konto oder den Metadatendienst der Instanz.
Wenn Sie 1.107.0 irgendwo installiert hatten, folgen Sie dem Incident Report und rotieren Sie jeden Schlüssel, den diese Maschine lesen konnte, nicht nur die Anbieterschlüssel.

Fazit

Ein AI Gateway oder LLM Gateway ist keine neue Idee. Es ist das Muster des API Gateways, angewandt auf Verkehr, der pro Token abgerechnet wird, minutenlang streamt und zwischen Anbietern ausweicht. Wenn das zweite Team, der zweite Anbieter oder die erste Compliance-Frage kommt, zahlt es sich aus.

Der Benchmark beziffert die Angst vor dem zusätzlichen Hop: Ein Gateway mit ausreichender Kapazität kostet eine oder wenige Millisekunden, weit weniger, als jedes Modell zum Antworten braucht. Was die Optionen trennt, ist, wie viel Verkehr eine Replika trägt, wie sie streamt, wo sie läuft und wer die Schlüssel hält.

Um es auf Ihrer eigenen Hardware zu messen, startet das Benchmark-Repository alles mit Docker in drei Befehlen.

Ursprünglich veröffentlicht auf alekseialeinikov.com

TypeScript 7 vs. TypeScript 6: Was sich ändert, was kaputtgeht und wie das Upgrade gelingt

Aleksei Aleinikov — Wed, 21 Oct 2026 07:00:00 +0000

Über ein Jahrzehnt lang war tsc ein JavaScript-Programm, das JavaScript-Programme prüft, und jedes Team mit einem großen Monorepo kennt die Grenzen: ein Check von 30 Sekunden, ein Editor, der eine Minute zum Aufwachen braucht, ein CI-Job, der 8 GB Heap reserviert. TypeScript 7 ersetzt diese Engine. Compiler und Language Service sind jetzt ein natives Programm in Go, die Sprache bleibt unverändert, und npm i -D typescript installiert es.

„Dieselbe Sprache, nur schneller” ist das Versprechen, und es stimmt größtenteils. Das „größtenteils” ist der interessante Teil. Dieser Leitfaden vergleicht TypeScript 7 und TypeScript 6 direkt, zeigt einen Benchmark mit echten Open-Source-Projekten, darunter einen Fall, in dem beide Compiler nicht übereinstimmen, listet jede Option, die zum harten Fehler wurde, und beschreibt einen Upgrade-Weg, der dein Build nicht an einem Freitag zerlegt.

TypeScript 7 vs. 6 auf einen Blick

	TypeScript 6.0	TypeScript 7.0
Veröffentlicht	23. März 2026 (6.0.3 am 16. April)	8. Juli 2026 (Beta 21. April, RC 18. Juni)
Geschrieben in	TypeScript/JavaScript, läuft auf Node.js	Go, natives Binary
Rolle	Letztes Release auf der JS-Codebasis, die Brücke von 5.9	Der neue Standard-Compiler und Language Service
Parallelität	Ein Thread	Paralleles Parsen, Prüfen und Emittieren (`--checkers`, `--builders`)
Veraltete Optionen	Warnung; `ignoreDeprecations: "6.0"` unterdrückt sie	Harte Fehler
Compiler-API	Ja (`import ts from "typescript"`)	Nicht in 7.0; neue API in 7.1
Language Services für Vue, Svelte, Astro, MDX, Angular	Funktionieren	Noch nicht
Installation	`typescript@6` oder `@typescript/typescript6` (`tsc6`)	`typescript@latest` (zum Zeitpunkt des Schreibens 7.0.2)

Die Namen sorgen für den Großteil der Verwirrung, deshalb genau: TypeScript 6.0 ist nicht „die langsame Version”. Es ist das Release, das den Boden bereitet hat: Es hat Standardwerte geändert, die Altoptionen als veraltet markiert und ein Flag für deterministische Diagnosen ergänzt, damit 7.0 ein geradliniger Port sein konnte. Die ausführlichen Ankündigungen stehen im Blog des TypeScript-Teams für 6.0 und 7.0.

Warum 7 schneller ist: nativer Code und parallele Worker

Ein TypeScript-Build hat vier Stufen: Dateien parsen , Namen an Symbole binden , Typen prüfen und Ausgabe emittieren. In TypeScript 6 läuft alles in einem JavaScript-Thread unter dem Speicherlimit des V8-Heaps. Das Prüfen ist der teure Teil, und zugleich der, der sich am schwersten aufteilen ließ.

TypeScript 7 ändert zwei Dinge gleichzeitig. Der Code ist nativ: kein JIT-Warmup und kein garbage-collecteter Heap aus JavaScript-Objekten. Und die Stufen teilen sich den Speicher, sodass die Arbeit auf Threads verteilt werden kann:

Die Geschwindigkeit kommt aus nativem Code plus Parallelität. Beides lässt sich einstellen, und beides kostet Speicher, wenn man aufdreht.

Drei Flags steuern die Parallelität (die Release-Notes führen --checkers und --builders als experimentell):

--checkers N legt die Zahl der Type-Checking-Worker fest (Standard 4). Mehr Worker brauchen mehr Kerne und mehr Speicher, weil jeder seine eigene Sicht auf das Programm hat.
--builders N baut Projekt-Referenzen parallel, unter tsc --build. Es multipliziert sich mit --checkers: 4 Builder mit 4 Checkern können 16 Worker bedeuten.
--singleThreaded schaltet alles ab, nützlich auf kleinen CI-Runnern und für den Benchmark unten.

Wenn dich interessiert, wie eine native Laufzeit solche Arbeit auf OS-Threads verteilt: Die Go-Seite davon behandelt Wie viele Threads nutzt Go wirklich?.

Der Watch-Modus wurde auf einem nativen File-Watcher neu gebaut, und der Language Service hat dieselbe Behandlung bekommen. Die von Microsoft gemeldeten Zahlen aus dem Release-Post sind gut zu kennen, mit dem Vorbehalt, dass sie von Microsoft und von großen Codebasen stammen: „typischerweise 8- bis 12-mal” bei Full Builds, die Zeit bis zum ersten Fehler in VS Code von 17,5 s auf unter 1,3 s, Slacks CI-Type-Check von 7,5 auf 1,25 Minuten, und bei Canva die Zeit bis zum ersten Fehler im Editor von 58 auf 4,8 Sekunden.

Der Benchmark: drei echte Projekte, drei Compiler

In den Release-Notes steht „10-mal schneller”. Ich wollte das an Code sehen, den ich nicht selbst geschrieben habe, also habe ich drei beliebte Open-Source-Projekte genommen, jedes mit TypeScript 6.0.3, TypeScript 7.0.2 (Standard und --singleThreaded) und der 7.1.0-Beta vom 20. Oktober geprüft und jeden Lauf gestoppt. Der gesamte Aufbau ist Open Source, du kannst ihn also auf deiner eigenen Maschine wiederholen: typescript-7-vs-6-benchmark auf GitHub. Jeder Lauf war tsc -p <tsconfig> --noEmit: nur Type-Checking, ohne Emit.

Die Testkandidaten, zuerst der Stresstest:

type-fest , eine Sammlung von Typ-Utilities, die fast ihre gesamte Zeit mit Typ-Berechnung verbringt. Rekursive bedingte Typen bis zum Anschlag.
kysely , ein typsicherer SQL-Query-Builder. Eine typische Bibliothek mit vielen Generics.
hono , ein Web-Framework, zweimal geprüft: nur der Quellcode und Quellcode plus Tests. Bei den Tests beginnen die beiden Compiler, sich zu widersprechen, wie du unten siehst.

Jede Konfiguration lief mehrfach in getrennten Prozessen mit Node.js 24. Der erste Lauf wurde als Warm-up verworfen, die Tabelle zeigt den Median der übrigen. Alle Compiler bekamen denselben großzügigen Node-Heap. Die 7.1-Beta hatte bei type-fest ein paar Dateien mehr im Programm, lies ihre Spalte also als nahen, nicht als exakten Vergleich.

Projekt	TS 6.0.3	TS 7.0.2 `--singleThreaded`	TS 7.0.2 Standard	TS 7.1.0-beta	Speedup 7.0.2 vs. 6.0.3
type-fest	23,9 s	16,4 s	8,1 s	4,6 s	2,9×
kysely	1,37 s	0,48 s	0,27 s	0,22 s	5,1×
hono (Quellcode + Tests)	0,82 s	0,34 s	0,16 s	0,15 s	5,0×
hono (nur Quellcode)	0,46 s	0,17 s	0,10 s	0,10 s	4,4×

Der native Code allein bringt das 1,5- bis 2,9-Fache. Vier parallele Checker legen noch einmal das 1,6- bis 2,1-Fache obendrauf.

Was die Zahlen sagen, ohne sie schönzurechnen:

3- bis 5-mal, nicht 10-mal. Das liegt unter den 8–12 aus der Ankündigung, und ich würde die Tabelle nicht passend biegen. Microsofts Zahlen gelten für Full Builds großer Repositories, die Projekte hier sind kleiner. type-fest ist der Extremfall: ein Haufen rekursiver bedingter Typen, die Zeit geht fast nur in die Typ-Berechnung, und trotzdem war es fast dreimal so schnell. Eine faire Zusammenfassung lautet „je nach Codebasis grob 3- bis 12-mal”, und verlässlich einordnen kannst du deine nur durch Messen.
Der native Code allein ist die größere Hälfte. --singleThreaded war 1,5- bis 2,9-mal schneller als TypeScript 6. Die vier Standard-Checker halbierten die Zeit dann ungefähr noch einmal (1,6- bis 2,1-mal).
TypeScript 6 kommt mit dem Standard-Node-Heap bei type-fest gar nicht durch. Es lief bei etwa 4 GB Heap voll und brauchte ein erhöhtes --max-old-space-size, die JavaScript-Obergrenze, die ein natives Binary nicht hat.
7.1 ist noch einmal schneller. Die Beta senkte type-fest von 8,1 s auf 4,6 s, also 5,1-mal schneller als 6.0.3, und war bei den anderen 4,7- bis 6,4-mal schneller als TypeScript 6.

Beim Speicher ist das Bild gemischter. Maximaler Resident Memory in Megabyte:

Projekt	TS 6.0.3	TS 7.0.2 Standard	TS 7.1.0-beta
type-fest	6.196	7.141	5.838
kysely	460	307	222
hono (Quellcode + Tests)	440	207	165
hono (nur Quellcode)	327	117	97

Bei den kleinen und mittleren Projekten brauchte TypeScript 7 ein Drittel bis zwei Drittel weniger Speicher. Bei type-fest, mit der meisten Typ-Arbeit, brauchten vier Checker etwa 15 % mehr als der einzelne JavaScript-Thread, und die 7.1-Beta weniger als beide. Wenn deine CI-Runner speicherbegrenzt sind, ist --checkers 2 oder --singleThreaded der erste Regler zum Ausprobieren.

Achtung

Schnell heißt nicht identische Ergebnisse. Bei hono’s Testsuite meldete tsc 6.0.3 0 Fehler und tsc 7.0.2 4: zwei ungenutzte @ts-expect-error-Direktiven (TS2578) und zwei „No overload matches this call”-Fehler (TS2769, string nicht zuweisbar an string[]), alle in einer Testdatei. Die 7.1-Beta meldete 6, und bei hono’s reiner Quellcode-Konfiguration kamen mit der Beta 2 noImplicitAny-Fehler hinzu, die 6.0 und 7.0 nicht meldeten. Jeder davon kann eine berechtigte Korrektur oder eine Regression sein, und in beiden Fällen willst du es in einem Branch herausfinden, nicht im Release.

Hinweis

Nachstellen in drei Befehlen: git clone https://github.com/LF3551/typescript-7-vs-6-benchmark, dann npm run setup und npm run bench. Das Repository pinnt die drei Projekte an exakten Commits, installiert TypeScript 6.0.3, 7.0.2 und 7.1.0-beta in getrennten Ordnern, damit die Binaries sich nicht vermischen, und nutzt für alle Compiler dasselbe NODE_OPTIONS=--max-old-space-size. Eigene Projekte trägst du in config.json ein. Zahlen von einer einzelnen Maschine sind ein Plausibilitätscheck, keine Bestenliste; vergleiche Verhältnisse, nicht Sekunden.

Was TypeScript 6 für dich geändert hat

Der Großteil der Upgrade-Arbeit passiert in 6.0, denn dort haben sich die Standardwerte verschoben. Wenn deine tsconfig.json kurz ist und sich auf Defaults verlässt, sind das die, die beißen:

Einstellung	Standard vor 6.0	Standard in 6.0 und 7.0
`strict`	`false`	`true`
`module`	`commonjs`	`esnext`
`target`	`es5`	die neueste stabile ECMAScript-Version
`types`	alle `@types/*`	`[]` (nichts wird automatisch eingebunden)
`rootDir`	aus den Eingabedateien abgeleitet	der Ordner mit der `tsconfig.json`
`noUncheckedSideEffectImports`	`false`	`true`
`libReplacement`	`true`	`false`
Typ-Reihenfolge (`stableTypeOrdering`)	nicht deterministisch	in 6.0 optionales Flag, in 7.0 immer an

Zwei davon verdienen Aufmerksamkeit. types: [] heißt: process, describe und jedes andere globale Symbol aus @types/node oder @types/jest verschwindet, bis du es auflistest, der häufigste erste Fehler in einem hochgezogenen Projekt. Der Vorteil ist real: Die 6.0-Ankündigung nennt, dass viele Projekte 20–50 % Build-Zeit gewannen, nur weil sie types explizit setzten. Und stableTypeOrdering macht die Reihenfolge deterministisch, in der der Checker Typen entdeckt; in 6.0 kannst du es per Flag einschalten (es kostet bis zu 25 % Check-Zeit, ist also zur Diagnose deiner Migration da, nicht für den Alltag). In 7.0 ist es immer an und lässt sich nicht abschalten, es ist also eine der Stellen, an denen Ergebnisse von dem abweichen können, was du auf 6.0 gesehen hast.

Eine tsconfig, die auf beiden Versionen läuft, sieht so aus:

tsconfig.json

{

  "compilerOptions": {

    "target": "es2022",

    "module": "esnext",

    "moduleResolution": "bundler",

    "types": ["node"],

    "strict": true,

    "noEmit": true

  },

  "include": ["src"]

}

6.0 brachte außerdem Features, die man kennen sollte und die alle auch auf 7 verfügbar sind: #/-Subpath-Imports, bundler-Resolution zusammen mit commonjs, das Target und die Bibliothek es2025, Temporal-Typen, Map.getOrInsert und RegExp.escape.

Was in TypeScript 7 kaputtgeht

In 6.0 wurde eine Reihe langjähriger Optionen als veraltet markiert und konnte mit "ignoreDeprecations": "6.0" stummgeschaltet werden. In 7.0 gibt es diesen Schalter nicht mehr, und die Optionen sind harte Fehler :

Option oder Syntax	Warum sie geht	Stattdessen
`target: "es5"`	Veraltetes Ausgabeziel	`es2015` oder neuer als Target, und einen Bundler herunterkompilieren lassen, falls du wirklich alte Browser brauchst
`downlevelIteration`	Nur für Targets unter ES2015 nötig	Entfernen
`moduleResolution: "node10"` (`node`) und `"classic"`	Auflösung aus der Zeit vor ESM	`bundler`, `node16` oder `nodenext`
`module: "amd"`, `"umd"`, `"systemjs"`, `"none"`	Überholte Modulformate	`esnext` oder `preserve` mit Bundler, oder `commonjs`
`baseUrl`	Löst bloße Imports ab der Projektwurzel auf	`paths` mit expliziten Zuordnungen oder `#/`-Subpath-Imports
`outFile`	In 6.0 entfernt	Ein Bundler
`esModuleInterop: false`, `allowSyntheticDefaultImports: false`	Interop ist jetzt immer an	Einstellung entfernen
`alwaysStrict: false`	Strict Mode ist immer an	Einstellung entfernen
`module Foo {}` für Namespaces	Mehrdeutiges Schlüsselwort	`namespace Foo {}`
`import x from "y" assert { type: "json" }`	Durch `with` ersetzt	`with { type: "json" }`
`tsc datei.ts`, obwohl eine `tsconfig.json` existiert	Man vergisst leicht, dass die Config ignoriert wird	`tsc --ignoreConfig datei.ts`

Die meisten davon sind Ein-Zeilen-Löschungen. baseUrl ist die Option, die Imports anfasst, und ein kleines Tool, ts5to6, schreibt baseUrl und rootDir für dich um.

Jenseits der Konfiguration haben sich ein paar Verhalten bewusst geändert: Die Inferenz von Template-Literal-Typen behandelt Strings jetzt nach Codepoints, und die JavaScript-Unterstützung hat etwas alte JSDoc- und Closure-Syntax verloren (@enum, @class, Postfix-!, Closure-Funktionstypen). Beides trifft den meisten TypeScript-Code nicht, aber es sind die Stellen, an denen du suchst, wenn nach der Umstellung ein Test ohne Config-Fehler fehlschlägt.

Räum die Deprecations auf 6.0 auf, stelle dann die CI auf den nativen Compiler um und lass Tools, die die Compiler-API brauchen, auf 7.1 warten.

Tooling: Was heute mit 7 funktioniert

Hier trifft „dieselbe Sprache” auf die Realität. TypeScript 7.0 wird ohne programmatische API ausgeliefert, weil der Compiler keine JavaScript-Bibliothek mehr ist, die man per require laden kann. Die Folge ist klar:

Was	Funktioniert auf 7.0?
`tsc` im Terminal und in der CI	Ja
Type-Checking im Editor für reines TS und TSX	Ja, über den TypeScript-7-Language-Server (eine VS-Code-Erweiterung; Visual Studio aktiviert ihn pro Workspace)
Tools, die `import "typescript"` nutzen (typescript-eslint, Codemods, Doku-Generatoren)	Nicht direkt; nutze den 6.0-Alias
Language Services für Vue-, MDX-, Astro-, Svelte-, Angular-Templates	Noch nicht
`--watch`	Ja, auf einem nativen Watcher neu gebaut

Der Workaround ist, beide zu betreiben. Das Paket @typescript/typescript6 liefert den 6.0-Compiler mit einem tsc6-Binary, und mit npm-Aliassen bekommt alles, was typescript importiert, weiter 6.0, während der native Compiler unter eigenem Namen liegt:

package.json

{

  "devDependencies": {

    "typescript": "npm:@typescript/typescript6@^6.0.2",

    "@typescript/native": "npm:typescript@^7.0.2"

  }

}

Beide parallel betreiben, solange du migrierst


npm i -D typescript@7 @typescript/typescript6

npx tsc --noEmit # natives TypeScript 7

npx tsc6 --noEmit # TypeScript 6.0 zum Vergleich

Das installiert beide Kommandozeilen-Tools. Nutze stattdessen die Alias-Form von oben, wenn Tools wie typescript-eslint brauchen, dass import "typescript" zu 6.0 auflöst. In VS Code schaltet der Befehl „Disable TypeScript 7 Language Server” den Editor zurück auf 6.0, falls dir der Language Server mal im Weg steht.

Tipp

Lass tsc6 einige Wochen in der CI mitlaufen und vergleiche die Ausgaben. Jede Datei, in der die beiden abweichen, ist entweder ein Fehler, den du jetzt kennen willst, oder einer, den du melden willst; das hono-Ergebnis oben ist genau der Fall, den das findet.

Dieselbe Disziplin „alt und neu parallel laufen lassen” macht auch andere Toolchain-Wechsel schmerzfrei. So würde ich den Ersatz von ESLint und Prettier durch Biome angehen, und sie hat die Migration von Jest zu Vitest berechenbar gemacht.

Ein sicherer Upgrade-Weg

Auf TypeScript 6.0.3 upgraden und pinnen. Behebe die auftretenden Fehler, meist fehlende types-Einträge und strict-Folgen, und committe.
Jede Deprecation-Warnung aufräumen. Führe tsc aus und behandle jede Deprecation wie einen Fehler; nutze ts5to6 für baseUrl und rootDir. Greif nicht zu ignoreDeprecations als Endlösung, denn auf 7 bewirkt es nichts.
types und rootDir explizit setzen. Das ist der billigste Speedup der ganzen Migration und beseitigt die beiden Standardwerte, die sich am stärksten geändert haben.
Optional 6.0 mit --stableTypeOrdering laufen lassen. Es macht die 6.0-Diagnosen auf dieselbe Weise deterministisch wie 7.0, sodass jeder spätere Unterschied vom Port kommt und nicht von der Reihenfolge.
TypeScript 7 neben 6 in die CI nehmen. Lass tsc und tsc6 laufen, lass den Build an tsc6 scheitern und melde tsc als nicht blockierenden Job. Lies jede Abweichung.
Den blockierenden Check auf 7 umstellen. Behalte den 6.0-Alias für Editoren und jedes Tool, das typescript importiert.
Die Parallelität abstimmen. Beginne mit den vier Standard-Checkern; nutze --checkers 2 oder --singleThreaded auf speicherbegrenzten Runnern und --builders bei Monorepos mit Projekt-Referenzen. Lege denselben --checkers-Wert auf jeder Maschine und in der CI fest, denn die Release-Notes warnen, dass eine Änderung in seltenen Fällen reihenfolgeabhängige Ergebnisse sichtbar machen kann.

Wenn du eine Bibliothek pflegst, die die Compiler-API anbietet, oder ein Projekt mit Vue-, Svelte-, Astro- oder Angular-Templates, bleib vorerst bei Schritt 5 stehen. Das ist eine Entscheidung, kein Scheitern.

Was TypeScript 7.1 bringt

TypeScript 7.1 erreichte am 20. Oktober 2026 die Beta, installierbar als typescript@beta, ein Release Candidate wird etwa einen Monat später erwartet. Es ist das Release, das die meisten der obigen Lücken schließt:

Eine neue Compiler-API mit Einstiegspunkten wie typescript/sync, typescript/ast und typescript/fs, Snapshots, Dateisystem-Schichten und Unterstützung für using.
Content Mapper , konfiguriert mit contentMappers in der tsconfig.json, für Nicht-TypeScript-Dateien wie Vue, Astro, Svelte und MDX, mit tsc --runExternalCode zum Ausführen.
Import Attributes in Ambient Modules , die Syntax import source, das Target es2026 und neue Bibliotheksmethoden.
Weitere Optimierungen , im Benchmark oben sichtbar, und strengeres Prüfen distributiver Typparameter, das in typlastigem Code neue Fehler sichtbar machen kann. Die zusätzlichen hono-Diagnosen habe ich keiner konkreten Änderung zugeordnet, ihre Ursache ist also offen.

Welche Version solltest du nutzen?

Deine Situation	Nutze
Reine TypeScript- oder React-App, CI-Type-Check ist langsam	7.0 für die CI jetzt, nach einem Parallel-Lauf
Großes Monorepo mit Projekt-Referenzen	7.0 , mit `--builders` und `--checkers` passend zu deinen Runnern
Vue-, Svelte-, Astro-, MDX- oder Angular-Templates	6.0 für den Editor , 7.0 für CLI-Checks, auf 7.1 warten
Bibliothek oder Tool, das `typescript` importiert	6.0 , bis die 7.1-API stabil ist
Noch auf `target es5`, `baseUrl`, `node10`-Resolution oder AMD/UMD	Zuerst 6.0 , Deprecations aufräumen, dann 7.0
Speicherbegrenzte CI-Runner	7.0 mit `--checkers 2` oder `--singleThreaded`

Fazit

TypeScript 7 ist dieselbe Sprache mit einer neuen Engine, und die Engine ist das, was du bemerkst: In diesem Test waren Type-Checks 2,9- bis 5,1-mal schneller als auf TypeScript 6, laut Microsofts eigenen Zahlen mit größerem Gewinn bei größeren Codebasen, und die 7.1-Beta ist noch schneller. Der Preis ist eine Migration mit Kanten. Jede Option, die 6.0 als veraltet markierte, ist jetzt ein Fehler, die Compiler-API und die Template-Language-Services müssen auf 7.1 warten, und bei mindestens einem bekannten Projekt sind sich die beiden Compiler über denselben Code uneins. Also: über 6.0 gehen, beide Compiler parallel laufen lassen, zuerst die CI umstellen und den Rest der Toolchain, wenn ihre Unterstützung da ist. Dann dauert das Upgrade einen Nachmittag Konfigurationsarbeit, und du bekommst deine Build-Minuten zurück.

Ursprünglich veröffentlicht auf alekseialeinikov.com

TypeScript 7 vs TypeScript 6: What Changed, What Breaks and How to Upgrade

Aleksei Aleinikov — Wed, 21 Oct 2026 07:00:00 +0000

For over a decade tsc has been a JavaScript program type-checking JavaScript programs, and every team with a big monorepo has learned its limits: a 30-second check, an editor that needs a minute to wake up, a CI job that reserves 8 GB of heap. TypeScript 7 replaces that engine. The compiler and the language service are now a native program written in Go, the language is unchanged, and npm i -D typescript installs it.

“Same language, faster” is the pitch, and it is mostly true. Mostly is the interesting part. This guide compares TypeScript 7 and TypeScript 6 side by side, shows a benchmark on real open-source projects including a case where the two compilers disagree, lists every option that turned into a hard error, and gives an upgrade path that does not break your build on a Friday.

TypeScript 7 vs 6 at a glance

	TypeScript 6.0	TypeScript 7.0
Released	23 March 2026 (6.0.3 on 16 April)	8 July 2026 (beta 21 April, RC 18 June)
Written in	TypeScript/JavaScript, runs on Node.js	Go, native binary
Role	Last JS-codebase release, the bridge from 5.9	The new default compiler and language service
Parallelism	One thread	Parallel parse, check and emit (`--checkers`, `--builders`)
Deprecated options	Warn; `ignoreDeprecations: "6.0"` silences them	Hard errors
Compiler API	Yes (`import ts from "typescript"`)	Not in 7.0; new API in 7.1
Vue, Svelte, Astro, MDX, Angular language services	Work	Not yet
Install	`typescript@6` or `@typescript/typescript6` (`tsc6`)	`typescript@latest` (7.0.2 at time of writing)

The names are the source of most confusion, so it helps to be precise. TypeScript 6.0 is not “the slow one”. It is the release that prepared the ground: it changed defaults, deprecated the legacy options and added a flag to make diagnostics deterministic, so that 7.0 could be a straight port. The detailed announcements are on the TypeScript team’s blog for 6.0 and 7.0.

Why 7 is faster: native code and parallel workers

A TypeScript build has four stages: parse the files, bind names to symbols, check types, and emit output. In TypeScript 6 all of it runs in one JavaScript thread, under the memory limit of the V8 heap. Type-checking is the expensive part, and it is also the part that was hardest to split up.

TypeScript 7 changes two things at once. The code is native, so no JIT warm-up and no garbage-collected heap of JavaScript objects. And the stages share memory, so work can be split across threads:

The speed comes from native code plus parallelism. Both are tunable, and both cost memory when you turn them up.

Three flags control the parallelism (the release notes mark --checkers and --builders as experimental):

--checkers N sets the number of type-checking workers (default 4). More workers use more cores and more memory, because each has its own view of the program.
--builders N builds project references in parallel under tsc --build. It multiplies with --checkers: 4 builders with 4 checkers can mean 16 workers.
--singleThreaded turns it all off, which is useful on small CI runners and for the benchmark below.

If you are curious how a native runtime schedules this kind of work onto OS threads, the Go side of it is covered in How Many Threads Does Go Really Use?.

The watch mode was rebuilt on a native file watcher, and the language service got the same treatment. Microsoft’s reported numbers from the release post are worth knowing, with the caveat that they are Microsoft’s and from large codebases: “typically 8× to 12×” on full builds, VS Code’s time to the first error down from 17.5 s to under 1.3 s, Slack’s CI type-check from 7.5 to 1.25 minutes, and Canva’s time to the first error in the editor from 58 to 4.8 seconds.

The benchmark: three real projects, three compilers

Release notes promise “10x faster”. I wanted to see it on code I did not write, so I took three popular open-source projects, type-checked each one with TypeScript 6.0.3, TypeScript 7.0.2 (default and --singleThreaded) and the 7.1.0-beta from 20 October, and timed every run. The whole setup is open source, so you can repeat it on your own machine: typescript-7-vs-6-benchmark on GitHub. Every run was tsc -p <tsconfig> --noEmit: type-checking only, no emit.

The test subjects, starting with the stress test:

type-fest , a collection of type utilities that spends nearly all of its time in type-level computation. Recursive conditional types all the way down.
kysely , a type-safe SQL query builder. A typical generics-heavy library.
hono , a web framework, checked twice: on the source only, and on source plus tests. The tests are where the two compilers start to disagree, as you will see below.

Each configuration ran several times in separate processes on Node.js 24. The first run was thrown away as a warm-up, and the table shows the median of the rest. All compilers got the same generous Node heap. The 7.1 beta pulled a handful more files into the program on type-fest, so read its column as a close comparison rather than an exact one.

Project	TS 6.0.3	TS 7.0.2 `--singleThreaded`	TS 7.0.2 default	TS 7.1.0-beta	Speedup 7.0.2 vs 6.0.3
type-fest	23.9 s	16.4 s	8.1 s	4.6 s	2.9×
kysely	1.37 s	0.48 s	0.27 s	0.22 s	5.1×
hono (src + tests)	0.82 s	0.34 s	0.16 s	0.15 s	5.0×
hono (src only)	0.46 s	0.17 s	0.10 s	0.10 s	4.4×

Native code alone is worth 1.5–2.9×. Four parallel checkers add another 1.6–2.1× on top.

What the numbers say, without rounding in my favour:

3× to 5×, not 10×. That is lower than the headline 8–12×, and I would not stretch the table to fit. Microsoft’s figures are for full builds of large repositories, and the projects here are smaller. type-fest is the extreme case: it is a pile of recursive conditional types, so the time is dominated by the type-level work itself, and it still came out nearly three times faster. A fair summary is “between about 3× and 12×, depending on the codebase”, and the only reliable way to place yours is to measure it.
Native code alone is the bigger half. --singleThreaded was 1.5–2.9× faster than TypeScript 6. The four default checkers then roughly halved the time again (1.6–2.1×).
TypeScript 6 cannot even finish type-fest on a default Node heap. It ran out of memory at about 4 GB of heap and needed --max-old-space-size raised to complete, which is the JavaScript ceiling that a native binary does not have.
7.1 is faster again. The beta cut type-fest from 8.1 s to 4.6 s, 5.1× faster than 6.0.3, and was 4.7–6.4× faster than TypeScript 6 on the others.

Memory is a more mixed story. Peak resident memory, in megabytes:

Project	TS 6.0.3	TS 7.0.2 default	TS 7.1.0-beta
type-fest	6,196	7,141	5,838
kysely	460	307	222
hono (src + tests)	440	207	165
hono (src only)	327	117	97

On the small and medium projects TypeScript 7 used a third to two thirds less memory. On type-fest, with the most type-level work, four checkers used about 15% more than the single JavaScript thread, and the 7.1 beta used less than both. If your CI runners are memory-bound, --checkers 2 or --singleThreaded is the first knob to try.

Warning

Speed is not the same as identical results. On hono’s test suite, tsc 6.0.3 reported 0 errors and tsc 7.0.2 reported 4: two unused @ts-expect-error directives (TS2578) and two “No overload matches this call” errors (TS2769, string not assignable to string[]), all in one test file. The 7.1 beta reported 6, and on hono’s source-only configuration the beta added 2 noImplicitAny errors that 6.0 and 7.0 did not report. Each of these may be a legitimate correction or a regression, and either way you want to find out in a branch, not in a release.

Note

Reproduce it in three commands: git clone https://github.com/LF3551/typescript-7-vs-6-benchmark, then npm run setup and npm run bench. The repository pins the three projects at exact commits, installs TypeScript 6.0.3, 7.0.2 and 7.1.0-beta in separate folders so the binaries stay apart, and uses the same NODE_OPTIONS=--max-old-space-size for every compiler. Add your own project in config.json. Single-machine numbers are a sanity check, not a leaderboard; compare ratios, not seconds.

What TypeScript 6 changed for you

Most of the upgrade work happens in 6.0, because that is where the defaults moved. If your tsconfig.json is short and relies on defaults, these are the ones that bite:

Setting	Default before 6.0	Default in 6.0 and 7.0
`strict`	`false`	`true`
`module`	`commonjs`	`esnext`
`target`	`es5`	the latest stable ECMAScript version
`types`	all of `@types/*`	`[]` (nothing is included automatically)
`rootDir`	inferred from the input files	the folder containing the `tsconfig.json`
`noUncheckedSideEffectImports`	`false`	`true`
`libReplacement`	`true`	`false`
Type ordering (`stableTypeOrdering`)	not deterministic	opt-in flag in 6.0, always on in 7.0

Two of these deserve attention. types: [] means process, describe and every other global from @types/node or @types/jest disappears until you list them, which is the most common first error in an upgraded project. The upside is real: the 6.0 announcement notes that many projects gained 20–50% in build time simply by setting types explicitly. And stableTypeOrdering makes the order in which the checker discovers types deterministic, which in 6.0 you can opt into with a flag (it costs up to 25% in check time, so it is for diagnosing your migration, not for everyday use). In 7.0 it is always on and cannot be turned off, so it is one of the places where results can differ from what you saw on 6.0.

A tsconfig that works on both versions looks like this:

tsconfig.json

{

  "compilerOptions": {

    "target": "es2022",

    "module": "esnext",

    "moduleResolution": "bundler",

    "types": ["node"],

    "strict": true,

    "noEmit": true

  },

  "include": ["src"]

}

6.0 also added features that are worth knowing, all available on 7: #/ subpath imports, bundler resolution together with commonjs, the es2025 target and library, Temporal types, Map.getOrInsert and RegExp.escape.

What breaks in TypeScript 7

In 6.0, a set of long-standing options became deprecated and could be silenced with "ignoreDeprecations": "6.0". In 7.0 that switch is gone, and the options are hard errors :

Option or syntax	Why it goes	Do instead
`target: "es5"`	Legacy output target	Target `es2015` or newer and let a bundler down-level if you really need old browsers
`downlevelIteration`	Only needed for targets below ES2015	Remove it
`moduleResolution: "node10"` (`node`) and `"classic"`	Pre-ESM resolution	`bundler`, `node16` or `nodenext`
`module: "amd"`, `"umd"`, `"systemjs"`, `"none"`	Obsolete module formats	`esnext` or `preserve` with a bundler, or `commonjs`
`baseUrl`	Resolves bare imports to the project root	`paths` with explicit mappings, or `#/` subpath imports
`outFile`	Removed in 6.0	A bundler
`esModuleInterop: false`, `allowSyntheticDefaultImports: false`	Interop is always on now	Remove the setting
`alwaysStrict: false`	Strict mode is always on	Remove the setting
`module Foo {}` for namespaces	Ambiguous keyword	`namespace Foo {}`
`import x from "y" assert { type: "json" }`	Replaced by `with`	`with { type: "json" }`
`tsc file.ts` while a `tsconfig.json` exists	Easy to forget the config is ignored	`tsc --ignoreConfig file.ts`

Most of these are one-line deletions. baseUrl is the one that touches imports, and a small tool, ts5to6, rewrites baseUrl and rootDir for you.

Beyond configuration, a few behaviours changed deliberately: template-literal type inference now treats strings by code points, and JavaScript support lost some old JSDoc and Closure-style syntax (@enum, @class, postfix !, Closure function types). Neither will touch most TypeScript code, but they are the places to look if a test fails after the switch with no config error.

Clear the deprecations on 6.0, then switch CI to the native compiler, and let the tools that need the compiler API wait for 7.1.

Tooling: what works with 7 today

This is where “same language” meets reality. TypeScript 7.0 ships without a programmatic API , because the compiler is no longer a JavaScript library you can require. That has a clear consequence:

What	Works on 7.0?
`tsc` in the terminal and in CI	Yes
Editor type-checking for plain TS and TSX	Yes, through the TypeScript 7 language server (a VS Code extension; Visual Studio enables it per workspace)
Tools that `import "typescript"` (typescript-eslint, codemods, doc generators)	Not directly; use the 6.0 alias
Language services for Vue, MDX, Astro, Svelte, Angular templates	Not yet
`--watch`	Yes, rebuilt on a native watcher

The workaround is to run both. The @typescript/typescript6 package ships the 6.0 compiler with a tsc6 binary, and npm aliases let anything that imports typescript keep getting 6.0 while the native compiler lives under its own name:

package.json

{

  "devDependencies": {

    "typescript": "npm:@typescript/typescript6@^6.0.2",

    "@typescript/native": "npm:typescript@^7.0.2"

  }

}

Run both while you migrate


npm i -D typescript@7 @typescript/typescript6

npx tsc --noEmit # native TypeScript 7

npx tsc6 --noEmit # TypeScript 6.0 for comparison

This installs both command-line tools. Use the alias form above instead when tools such as typescript-eslint need import "typescript" to resolve to 6.0. In VS Code, the “Disable TypeScript 7 Language Server” command switches the editor back to 6.0 if the language server ever gets in your way.

Tip

Keep tsc6 in CI for a few weeks and diff the outputs. Any file where the two disagree is either a bug you want to know about now or a bug you want to report; the hono result above is exactly the kind of case this catches.

The same “run old and new side by side” discipline is what makes other toolchain swaps painless. It is how I would approach replacing ESLint and Prettier with Biome and what made the Jest to Vitest migration predictable.

A safe upgrade path

Upgrade to TypeScript 6.0.3 and pin it. Fix the errors that appear, mostly missing types entries and strict fallout, and commit.
Clear every deprecation warning. Run tsc and treat each deprecation as an error; use ts5to6 for baseUrl and rootDir. Do not reach for ignoreDeprecations as the final answer, because it does nothing on 7.
Set types and rootDir explicitly. It is the cheapest speedup in the whole migration and removes the two defaults that changed most.
Optionally run 6.0 with --stableTypeOrdering. It makes 6.0 diagnostics deterministic in the same way as 7.0, so any difference you see afterwards is from the port, not from ordering.
Add TypeScript 7 next to 6 in CI. Run both tsc and tsc6, fail the build on tsc6, and report tsc as a non-blocking job. Read every disagreement.
Switch the blocking check to 7. Keep the 6.0 alias for editors and any tool that imports typescript.
Tune the parallelism. Start with the default four checkers; use --checkers 2 or --singleThreaded on memory-limited runners; use --builders on monorepos with project references. Pin the same --checkers value on every machine and in CI, because the release notes warn that changing it can, in rare cases, surface order-dependent results.

If you maintain a library that exposes the compiler API, or a project with Vue, Svelte, Astro or Angular templates, stop at step 5 for now. That is a decision, not a failure.

What TypeScript 7.1 adds

TypeScript 7.1 reached beta on 20 October 2026, installable as typescript@beta, with a release candidate expected about a month later. It is the release that closes most of the gaps above:

A new compiler API , with entry points such as typescript/sync, typescript/ast and typescript/fs, snapshots, file-system layers and support for using.
Content mappers , configured with contentMappers in tsconfig.json, for non-TypeScript files such as Vue, Astro, Svelte and MDX, with tsc --runExternalCode to run them.
Import attributes in ambient modules , import source syntax, the es2026 target and new library methods.
More optimizations , visible in the benchmark above, and stricter checking of distributive type parameters, which can surface new errors in type-heavy code. I did not trace the extra hono diagnostics to a specific change, so treat their cause as unknown.

Which version should you run?

Your situation	Use
Plain TypeScript or React app, CI type-check is slow	7.0 for CI now, after a side-by-side run
Large monorepo with project references	7.0 , with `--builders` and `--checkers` tuned to your runners
Vue, Svelte, Astro, MDX or Angular templates	6.0 for the editor , 7.0 for CLI checks, wait for 7.1
Library or tool that imports `typescript`	6.0 until the 7.1 API is stable
Still on `target es5`, `baseUrl`, `node10` resolution or AMD/UMD	6.0 first , clear the deprecations, then 7.0
Memory-limited CI runners	7.0 with `--checkers 2` or `--singleThreaded`

The Bottom Line

TypeScript 7 is the same language with a new engine, and the engine is what you will notice: in this test, type-checks were 2.9–5.1× faster than on TypeScript 6, with a larger win on bigger codebases according to Microsoft’s own numbers, and the 7.1 beta is faster still. The price is a migration with edges. Every option 6.0 deprecated is now an error, the compiler API and the template-language services have to wait for 7.1, and on at least one popular project the two compilers disagree about the same code. So go through 6.0, run both compilers side by side, switch CI first and the rest of the toolchain when its support lands. If you do that, the upgrade takes an afternoon of configuration, and you get your build minutes back.

Originally published at alekseialeinikov.com

DuckDB Explained: When a Database on Your Laptop Beats SQLite, Polars and BigQuery

Aleksei Aleinikov — Tue, 20 Oct 2026 07:00:00 +0000

For a decade the rule was simple: small data goes in pandas, big data goes in a warehouse, and anything in between gets a Spark cluster nobody wants to maintain. DuckDB quietly broke that rule. It is a full analytical SQL database that installs with pip, runs inside your Python process, and reads a folder of Parquet files faster than most teams’ warehouse returns a dashboard tile.

That makes it easy to overhype. DuckDB is not a BigQuery killer, and it is not a faster SQLite for your app. It is something more specific, and once you see where its edges are, it becomes one of the most useful tools in a data stack. This guide explains what DuckDB is, shows a benchmark you can rerun yourself, and draws the line between “use DuckDB” and “you still need the warehouse”.

What DuckDB actually is

DuckDB is an in-process OLAP database. Each of those words matters:

In-process. There is no server. DuckDB is a library linked into your program: Python, R, Node.js, Java, Go, Rust, the CLI, even the browser through WebAssembly. A database is a single file, or just memory. Nothing to deploy, no port, no connection pool.
OLAP. It is built for analytical queries: scan millions of rows, filter, join, group, aggregate. Data is stored by column , so a query that touches five columns of a hundred reads only those five.
Vectorised. Instead of processing one row at a time, the engine works on batches of values per column, which keeps CPU caches busy and uses every core.

It came out of the database research group at CWI in Amsterdam, created by Mark Raasveldt and Hannes Mühleisen and first released in 2019. It is MIT-licensed and governed by the non-profit DuckDB Foundation. In August 2026 the project passed 40,000 GitHub stars, and the same month DuckLabs, the company behind its development, announced it would join AWS with an explicit promise that DuckDB, DuckLake and Quack stay MIT-licensed under the Foundation.

The best one-line description is still the old one: DuckDB is SQLite for analytics.

No server and no network hop: the query engine lives in your process and reads files where they are.

Five minutes from zero to a query

The fastest way to understand DuckDB is to point it at a file you already have.

Terminal window


pip install duckdb

taxi.py


import duckdb

# Query Parquet files directly: no CREATE TABLE, no load step.

duckdb.sql("""

    SELECT payment_type, count(*) AS trips, avg(total_amount) AS avg_total

    FROM 'yellow_tripdata_2025-0*.parquet'

    GROUP BY payment_type

    ORDER BY trips DESC

""").show()

A few things that surprise people the first time:

Files are tables. FROM 'data/*.parquet', FROM 'export.csv' and FROM 'events.json' all work, with globbing and automatic schema detection.
DataFrames are tables too. If a pandas or Polars DataFrame called df is in scope, duckdb.sql("SELECT ... FROM df") queries it in place, and .df() or .pl() turns the result back into one.
Remote storage is a path. With the httpfs extension, FROM 's3://bucket/events/*.parquet' or a GCS or HTTPS URL works the same way, and DuckDB reads only the columns and row groups it needs.
It speaks lakehouse. Extensions read and write Iceberg and Delta tables and attach PostgreSQL, MySQL and SQLite databases, so one SQL statement can join a Postgres table with Parquet on S3.

If you prefer a terminal, the duckdb CLI does the same, and duckdb -ui opens a local notebook-style web UI.

The benchmark: 11.2 million taxi trips on a laptop

Claims like “100× faster” are cheap, so here is a test you can rerun. The data is the public NYC TLC yellow-taxi record for January to March 2025: three Parquet files, 189 MB, 11,198,026 trips. Three questions any analyst would ask:

Q1: trips and average fare by payment type (one group-by).
Q2: trips and average distance per hour of day, ignoring zero-distance trips (filter, timestamp function, group-by).
Q3: top 10 pickup zones by revenue (join with the 265-row zone lookup, group-by, sort).

Each engine ran in its own process on the same laptop. Every query ran four times; the table shows the median of the last three. All engines returned identical answers (7,484,734 card trips averaging $28.47; JFK Airport first with $31.4 million).

Engine	Load step	Q1	Q2	Q3	Peak memory
DuckDB 1.5.6 (SQL on Parquet)	none	16 ms	36 ms	44 ms	237 MB
Polars 1.36 (lazy, `scan_parquet`)	none	19 ms	128 ms	305 ms	not measured
Polars 1.36 (eager, data in RAM)	0.07 s	10 ms	127 ms	351 ms	3.3 GB
pandas 2.3 (data in RAM)	1.5 s	126 ms	347 ms	661 ms	3.4 GB
SQLite 3.53 (table on disk)	19.8 s	1,800 ms	3,584 ms	4,529 ms	52 MB

Same three questions, same answers. DuckDB is fastest on every query with a join or a timestamp, and the only fast engine that does not need the data in RAM.

What the numbers say, honestly:

DuckDB vs SQLite: about 100× faster. Not because SQLite is bad, but because it is a row store built for transactions. Every analytical query reads every column of every row. SQLite used little memory because it streamed from disk, and it needed a 20-second load into a 529 MB file first.
DuckDB vs pandas: 8–15× faster, a fifteenth of the memory. pandas first has to materialise all 11 million rows in RAM (1.5 s, 3.4 GB). DuckDB streams the Parquet files and never holds the whole dataset.
DuckDB vs Polars: close on simple work, ahead on joins. Polars tied on Q1 and is a superb DataFrame library. On Q2 and Q3 DuckDB was 3.5–7× faster in this setup. Your queries may differ; the honest takeaway is that both are in a different league from pandas.

The memory column is the one to remember. A laptop with 16 GB cannot load 50 GB into pandas, but DuckDB will query it: it streams what fits and spills to disk for what does not. In March 2026 the DuckDB team ran all 99 TPC-DS queries at scale factor 300 on the cheapest MacBook, with 8 GB of RAM, in 79 minutes.

Note

Reproduce it: download the three yellow_tripdata_2025-0{1,2,3}.parquet files and taxi_zone_lookup.csv from the NYC TLC site, then run the three queries above in each engine. The SQLite file was built with DuckDB’s own sqlite extension (ATTACH 'taxi.sqlite' (TYPE sqlite)). Single-run numbers on one machine are a sanity check, not a leaderboard.

DuckDB vs SQLite, Polars, pandas, ClickHouse, Spark and BigQuery

Most “DuckDB vs X” questions are really “which shape of problem is this”. Here is the whole family on one page:

	DuckDB	SQLite	Polars	pandas	ClickHouse	Spark	BigQuery / Snowflake
What it is	Embedded analytical SQL DB	Embedded transactional SQL DB	DataFrame library (Rust)	DataFrame library	Columnar database server	Distributed compute engine	Managed cloud warehouse
Runs as	Library in your process	Library in your process	Library in your process	Library in your process	Server or cluster	Cluster	Cloud service
Best at	SQL analytics on files and DataFrames	Many small reads and writes	DataFrame pipelines	Small data, rich ecosystem	Real-time analytics, many users	Terabyte-scale ETL	Shared, governed analytics at any scale
Weak at	Many concurrent writers	Scans and aggregates	SQL-first teams	Memory, speed at scale	Embedding, ops overhead	Small data (overhead)	Latency, cost of frequent scans
Data larger than RAM	Yes, spills to disk	Yes (row-by-row)	Yes, streaming engine	No	Yes	Yes	Yes
Pick when	One person or job, MBs to hundreds of GBs	An app’s own data	You think in DataFrames	Data fits in RAM easily	Dashboards for hundreds of users	Data does not fit on one big machine	A company shares one source of truth

Three distinctions do most of the work:

DuckDB vs SQLite is OLAP vs OLTP. Keep SQLite (or PostgreSQL) for application state; reach for DuckDB to analyse it. DuckDB can even ATTACH the SQLite file and query it in place.
DuckDB vs Polars is mostly SQL vs DataFrame API. Both are fast, both stream, and they interoperate through Arrow with zero copies. Use whichever your team reads more easily.
DuckDB vs ClickHouse is embedded vs server. ClickHouse is built to serve hundreds of concurrent dashboard users from a cluster; DuckDB is built to sit inside one program.

Where DuckDB beats the warehouse, and where it does not

The most useful way to frame DuckDB is not “instead of BigQuery” but “before and beside BigQuery”.

DuckDB wins when:

One person or one job is asking the questions: an analyst in a notebook, a nightly batch job, a CI test.
The data is a file or an extract : Parquet on S3 or GCS, a CSV export, a sample of the warehouse.
Latency matters more than scale : 40 ms in a notebook loop beats a two-second round trip to any cloud service.
You want tests for data code. A dbt project or a SQL transformation can run against a DuckDB file in CI in seconds, with no cloud credentials. dbt v2 (September 2026) ships the DuckDB adapter built in.

The warehouse still wins when:

Many people and services need the same data at the same time, with roles, audit logs, row-level security and sharing.
Data reaches many terabytes , or queries routinely scan more than one large machine can read quickly.
You need managed operations : backups, high availability, governance, and someone else on call.

And the cost argument is subtler than the hype suggests. The five columns used above add up to under half a gigabyte for 11.2 million rows. In BigQuery on-demand, at $6.25 per TiB scanned after the first free TiB each month, a query over all of them costs about a quarter of a cent. At this size DuckDB does not save money; it saves the round trip. The money argument starts when dashboards and scheduled jobs rescan terabytes all day. That is where pulling a stable extract into Parquet and querying it with DuckDB can take a real line off the bill. If you are still choosing the warehouse itself, see BigQuery vs Snowflake: An Honest Comparison.

DuckDB does not replace the warehouse. It replaces the cluster you were about to build for data that fits on one machine, and the hundred small queries you were sending to the cloud just to look at it.

The real boundary is not data size but how many writers and readers share the data.

The real limit is concurrency, not size

People expect DuckDB’s limit to be data volume. In practice it is who else is writing.

In plain in-process mode, one process can open a database file read-write, using as many threads as it likes, or many processes can open it read-only. Two services cannot both write to the same .duckdb file. That is a deliberate trade-off: keeping state in one process’s memory is part of why it is fast.

Two developments in 2026 move that line:

Quack, DuckDB’s own client-server protocol. Released as a preview in May 2026, it lets any DuckDB process serve its databases over HTTP and any other DuckDB ATTACH to it. In the team’s benchmarks, Quack moved 60 million rows in 4.9 seconds where the PostgreSQL protocol took 158, and handled about 5,400 small write transactions per second on eight threads, ahead of PostgreSQL on the same machines. Quack becomes stable with DuckDB 2.0.
DuckLake, a lakehouse format built on SQL. Data lives as Parquet in object storage; the catalog (which files make up which table version) lives in a real database such as PostgreSQL. Many DuckDB instances can then read and write the same tables concurrently. DuckLake 1.0 was declared production-ready in April 2026. It solves the same problem as Iceberg and Delta, with a simpler catalog; the trade-offs between those two are in Iceberg vs Delta Lake: A Plain Guide.

If you would rather not run any of that, MotherDuck is the managed option: DuckDB in the cloud with storage, per-user compute, sharing and access control. Its pricing has a free Lite plan (10 GB storage, 10 hours of compute a month) and a Business plan at $250 per organisation per month plus usage, with EU regions in Frankfurt and Dublin, which matters for GDPR-minded teams in Germany.

What is new in DuckDB 2.0

DuckDB 2.0, codenamed “Cyanoptera”, is on the release calendar for 21 October 2026, with a 2.0.1 bugfix release planned for November. The preview lists more than 10,000 commits since 1.5. The highlights that change how you use it:

DuckDB as a server. Quack graduates to stable, and a new CONNECT statement points your session at a remote DuckDB, or at PostgreSQL or MySQL, and pushes the SQL down to run there.
VARIANT as a first-class type. Semi-structured data (think JSON logs) is shredded into columns automatically, so it compresses and queries like typed data without declaring a schema.
Triggers , BEFORE and AFTER, per row or per statement: audit tables without application code.
Asynchronous I/O throughout the engine, with the biggest gains on S3 and other network storage.
NEAREST joins for top-k similarity search over embeddings, useful if you are weighing whether you need a dedicated vector database at all.
A new storage format and a new PEG-based SQL parser , plus a small set of breaking changes. Files written by 2.0 use the new format by default, so pin versions before upgrading shared files.

If you need stability over features, the 1.4 line is the long-term-support release, supported until November 2026; from 1.4 on, every other minor version is LTS.

A practical starting point

You do not need a migration plan to get value from DuckDB. Start small:

Replace the slowest pandas step in a notebook with duckdb.sql(...) over the same DataFrame or Parquet file, and keep the rest.
Export a stable warehouse table to Parquet once a day and point exploratory work at the file instead of the warehouse.
Run your SQL transformations against DuckDB in CI , so a broken model fails in a pull request instead of in production.
Only then decide whether you need shared access through MotherDuck, Quack or DuckLake, or whether the warehouse should simply stay the source of truth.

Keep the model in mind: one process, columnar, vectorised, reads files where they are. Everything DuckDB is great at follows from it, and so does everything it is not built for. If you want to place it among the broader database families first, start with SQL vs NoSQL: database types and how to choose.

The Bottom Line

DuckDB earns its hype on a narrow, very common problem: one person or one job asking analytical questions of data that fits on one machine. There it is faster than pandas, far faster than SQLite, at least as fast as Polars on most work, and it needs no infrastructure at all. It is not a shared warehouse, and pretending otherwise ends in file-lock errors. Use it before and beside BigQuery or Snowflake, not instead of them, and watch the concurrency story: with Quack and DuckLake, the line between “laptop database” and “real database” is moving faster than any other part of the data stack.

Originally published at alekseialeinikov.com

DuckDB erklärt: Wann eine Datenbank auf dem Laptop SQLite, Polars und BigQuery schlägt

Aleksei Aleinikov — Tue, 20 Oct 2026 07:00:00 +0000

Ein Jahrzehnt lang galt eine einfache Regel: Kleine Daten kommen in pandas, große in ein Data Warehouse, und alles dazwischen bekommt einen Spark-Cluster, den niemand pflegen will. DuckDB hat diese Regel leise gebrochen. Es ist eine vollwertige analytische SQL-Datenbank, die sich per pip installiert, in deinem Python-Prozess läuft und einen Ordner voller Parquet-Dateien schneller abfragt, als das Warehouse der meisten Teams eine Dashboard-Kachel liefert.

Genau deshalb wird DuckDB leicht überschätzt. Es ist kein BigQuery-Killer und auch kein schnelleres SQLite für deine App. Es ist etwas Spezifischeres, und sobald du seine Grenzen kennst, wird es zu einem der nützlichsten Werkzeuge im Datenstack. Dieser Leitfaden erklärt, was DuckDB ist, zeigt einen Benchmark, den du selbst wiederholen kannst, und zieht die Linie zwischen „nimm DuckDB“ und „du brauchst weiterhin das Warehouse“.

Was DuckDB eigentlich ist

DuckDB ist eine In-Process-OLAP-Datenbank. Jedes dieser Wörter zählt:

In-Process. Es gibt keinen Server. DuckDB ist eine Bibliothek, die in dein Programm eingebunden wird: Python, R, Node.js, Java, Go, Rust, die CLI, per WebAssembly sogar der Browser. Eine Datenbank ist eine einzige Datei oder liegt nur im Speicher. Nichts zu deployen, kein Port, kein Connection-Pool.
OLAP. DuckDB ist für analytische Abfragen gebaut: Millionen Zeilen scannen, filtern, joinen, gruppieren, aggregieren. Daten werden spaltenweise gespeichert. Eine Abfrage, die fünf von hundert Spalten braucht, liest nur diese fünf.
Vektorisiert. Statt Zeile für Zeile arbeitet die Engine auf Blöcken von Werten pro Spalte. Das hält die CPU-Caches gefüllt und nutzt alle Kerne.

DuckDB stammt aus der Datenbankforschung am CWI in Amsterdam, entwickelt von Mark Raasveldt und Hannes Mühleisen, erstmals 2019 veröffentlicht. Es steht unter der MIT-Lizenz und wird von der gemeinnützigen DuckDB Foundation verwaltet. Im August 2026 überschritt das Projekt 40.000 GitHub-Sterne, und im selben Monat kündigte DuckLabs, die Firma hinter der Entwicklung, an, zu AWS zu wechseln, mit dem ausdrücklichen Versprechen, dass DuckDB, DuckLake und Quack unter der Foundation MIT-lizenziert bleiben.

Die beste Kurzbeschreibung ist immer noch die alte: DuckDB ist SQLite für Analysen.

Kein Server, kein Netzwerk-Hop: Die Query-Engine lebt in deinem Prozess und liest Dateien dort, wo sie liegen.

In fünf Minuten zur ersten Abfrage

Am schnellsten verstehst du DuckDB, wenn du es auf eine Datei richtest, die du ohnehin hast.

Terminal window


pip install duckdb

taxi.py


import duckdb

# Parquet-Dateien direkt abfragen: kein CREATE TABLE, kein Ladeschritt.

duckdb.sql("""

    SELECT payment_type, count(*) AS trips, avg(total_amount) AS avg_total

    FROM 'yellow_tripdata_2025-0*.parquet'

    GROUP BY payment_type

    ORDER BY trips DESC

""").show()

Was beim ersten Mal überrascht:

Dateien sind Tabellen. FROM 'data/*.parquet', FROM 'export.csv' und FROM 'events.json' funktionieren, mit Globbing und automatischer Schema-Erkennung.
DataFrames sind auch Tabellen. Liegt ein pandas- oder Polars-DataFrame namens df im Scope, fragt duckdb.sql("SELECT ... FROM df") ihn direkt ab, und .df() oder .pl() macht aus dem Ergebnis wieder einen.
Remote-Speicher ist nur ein Pfad. Mit der Erweiterung httpfs funktioniert FROM 's3://bucket/events/*.parquet' oder eine GCS- bzw. HTTPS-URL genauso, und DuckDB liest nur die Spalten und Row-Groups, die es braucht.
Es spricht Lakehouse. Erweiterungen lesen und schreiben Iceberg- und Delta-Tabellen und binden PostgreSQL-, MySQL- und SQLite-Datenbanken ein. Eine einzige SQL-Abfrage kann so eine Postgres-Tabelle mit Parquet auf S3 joinen.

Im Terminal macht die duckdb-CLI dasselbe, und duckdb -ui öffnet eine lokale Web-Oberfläche im Notebook-Stil.

Der Benchmark: 11,2 Millionen Taxifahrten auf dem Laptop

Aussagen wie „100-mal schneller“ sind billig, deshalb hier ein Test zum Nachmachen. Die Daten sind die öffentlichen Yellow-Taxi-Fahrten der New Yorker TLC von Januar bis März 2025: drei Parquet-Dateien, 189 MB, 11.198.026 Fahrten. Drei Fragen, die jede Analystin stellen würde:

Q1: Fahrten und durchschnittlicher Betrag pro Zahlungsart (ein Group-by).
Q2: Fahrten und durchschnittliche Strecke pro Tagesstunde, ohne Fahrten mit Strecke null (Filter, Zeitstempel-Funktion, Group-by).
Q3: Die 10 umsatzstärksten Abholzonen (Join mit der Zonentabelle mit 265 Zeilen, Group-by, Sortierung).

Jede Engine lief in einem eigenen Prozess auf demselben Laptop. Jede Abfrage lief viermal; die Tabelle zeigt den Median der letzten drei Läufe. Alle Engines lieferten identische Ergebnisse (7.484.734 Kartenzahlungen mit durchschnittlich 28,47 $; JFK Airport vorn mit 31,4 Millionen $).

Engine	Ladeschritt	Q1	Q2	Q3	Speicher (Spitze)
DuckDB 1.5.6 (SQL auf Parquet)	keiner	16 ms	36 ms	44 ms	237 MB
Polars 1.36 (lazy, `scan_parquet`)	keiner	19 ms	128 ms	305 ms	nicht gemessen
Polars 1.36 (eager, Daten im RAM)	0,07 s	10 ms	127 ms	351 ms	3,3 GB
pandas 2.3 (Daten im RAM)	1,5 s	126 ms	347 ms	661 ms	3,4 GB
SQLite 3.53 (Tabelle auf Disk)	19,8 s	1.800 ms	3.584 ms	4.529 ms	52 MB

Dieselben drei Fragen, dieselben Antworten. DuckDB ist bei jeder Abfrage mit Join oder Zeitstempel am schnellsten und die einzige schnelle Engine, die die Daten nicht im RAM braucht.

Was die Zahlen ehrlich sagen:

DuckDB vs. SQLite: etwa 100-mal schneller. Nicht weil SQLite schlecht ist, sondern weil es ein Zeilenspeicher für Transaktionen ist. Jede analytische Abfrage liest jede Spalte jeder Zeile. SQLite brauchte wenig Speicher, weil es von der Platte streamte, musste die Daten aber erst 20 Sekunden lang in eine 529-MB-Datei laden.
DuckDB vs. pandas: 8- bis 15-mal schneller, ein Fünfzehntel des Speichers. pandas muss erst alle 11 Millionen Zeilen in den RAM holen (1,5 s, 3,4 GB). DuckDB streamt die Parquet-Dateien und hält nie den ganzen Datensatz.
DuckDB vs. Polars: gleichauf bei Einfachem, vorn bei Joins. Polars lag bei Q1 gleichauf und ist eine hervorragende DataFrame-Bibliothek. Bei Q2 und Q3 war DuckDB in diesem Setup 3,5- bis 7-mal schneller. Deine Abfragen können anders aussehen; die ehrliche Erkenntnis ist, dass beide in einer anderen Liga spielen als pandas.

Die Speicherspalte ist die wichtigste. Ein Laptop mit 16 GB kann keine 50 GB in pandas laden, aber DuckDB fragt sie trotzdem ab: Es streamt, was passt, und lagert auf die Platte aus , was nicht passt. Im März 2026 ließ das DuckDB-Team alle 99 TPC-DS-Abfragen mit Skalierungsfaktor 300 auf dem günstigsten MacBook mit 8 GB RAM laufen: fertig in 79 Minuten.

Hinweis

Zum Nachmachen: Lade die drei Dateien yellow_tripdata_2025-0{1,2,3}.parquet und taxi_zone_lookup.csv von der NYC-TLC-Website und führe die drei Abfragen oben in jeder Engine aus. Die SQLite-Datei wurde mit DuckDBs eigener sqlite-Erweiterung erzeugt (ATTACH 'taxi.sqlite' (TYPE sqlite)). Einzelmessungen auf einer Maschine sind ein Plausibilitätscheck, keine Rangliste.

DuckDB vs. SQLite, Polars, pandas, ClickHouse, Spark und BigQuery

Die meisten „DuckDB vs. X“-Fragen sind eigentlich die Frage: Welche Art von Problem liegt vor? Hier die ganze Familie auf einer Seite:

	DuckDB	SQLite	Polars	pandas	ClickHouse	Spark	BigQuery / Snowflake
Was es ist	Eingebettete Analyse-SQL-DB	Eingebettete Transaktions-SQL-DB	DataFrame-Bibliothek (Rust)	DataFrame-Bibliothek	Spaltenorientierter DB-Server	Verteilte Compute-Engine	Verwaltetes Cloud-Warehouse
Läuft als	Bibliothek im Prozess	Bibliothek im Prozess	Bibliothek im Prozess	Bibliothek im Prozess	Server oder Cluster	Cluster	Cloud-Dienst
Stark bei	SQL-Analysen auf Dateien und DataFrames	Vielen kleinen Lese- und Schreibzugriffen	DataFrame-Pipelines	Kleinen Daten, großem Ökosystem	Echtzeit-Analysen, vielen Nutzern	ETL im Terabyte-Bereich	Gemeinsamen, kontrollierten Analysen in jeder Größe
Schwach bei	Vielen gleichzeitigen Schreibern	Scans und Aggregationen	SQL-orientierten Teams	Speicher, Tempo bei Größe	Einbettung, Betriebsaufwand	Kleinen Daten (Overhead)	Latenz, Kosten häufiger Scans
Daten größer als RAM	Ja, lagert auf Disk aus	Ja (zeilenweise)	Ja, Streaming-Engine	Nein	Ja	Ja	Ja
Wählen, wenn	Eine Person oder ein Job, MB bis Hunderte GB	Die eigenen Daten einer App	Du in DataFrames denkst	Daten locker in den RAM passen	Dashboards für Hunderte Nutzer	Daten nicht auf eine große Maschine passen	Eine Firma eine gemeinsame Wahrheit teilt

Drei Unterscheidungen erledigen den Großteil:

DuckDB vs. SQLite ist OLAP vs. OLTP. Behalte SQLite (oder PostgreSQL) für den Zustand deiner Anwendung, nimm DuckDB, um ihn zu analysieren. DuckDB kann die SQLite-Datei sogar per ATTACH einbinden und direkt abfragen.
DuckDB vs. Polars ist vor allem SQL vs. DataFrame-API. Beide sind schnell, beide streamen, und sie tauschen Daten über Arrow ohne Kopien aus. Nimm das, was dein Team leichter liest.
DuckDB vs. ClickHouse ist eingebettet vs. Server. ClickHouse bedient aus einem Cluster Hunderte gleichzeitige Dashboard-Nutzer; DuckDB sitzt in einem einzigen Programm.

Wo DuckDB das Warehouse schlägt und wo nicht

Der nützlichste Rahmen für DuckDB ist nicht „statt BigQuery“, sondern „vor und neben BigQuery“.

DuckDB gewinnt, wenn:

eine Person oder ein Job die Fragen stellt: eine Analystin im Notebook, ein nächtlicher Batch-Job, ein CI-Test.
die Daten eine Datei oder ein Extrakt sind : Parquet auf S3 oder GCS, ein CSV-Export, ein Ausschnitt des Warehouse.
Latenz wichtiger ist als Skalierung : 40 ms in einer Notebook-Schleife schlagen jeden Zwei-Sekunden-Roundtrip zu einem Cloud-Dienst.
du Tests für Datencode willst. Ein dbt-Projekt oder eine SQL-Transformation läuft in der CI in Sekunden gegen eine DuckDB-Datei, ohne Cloud-Zugangsdaten. dbt v2 (September 2026) bringt den DuckDB-Adapter direkt mit.

Das Warehouse gewinnt weiterhin, wenn:

viele Menschen und Dienste gleichzeitig dieselben Daten brauchen, mit Rollen, Audit-Logs, Row-Level-Security und Freigaben.
die Daten viele Terabyte erreichen oder Abfragen regelmäßig mehr scannen, als eine große Maschine schnell lesen kann.
du verwalteten Betrieb brauchst : Backups, Hochverfügbarkeit, Governance und jemand anderes in Rufbereitschaft.

Und das Kostenargument ist subtiler, als der Hype nahelegt. Die fünf oben genutzten Spalten ergeben für 11,2 Millionen Zeilen weniger als ein halbes Gigabyte. In BigQuery On-Demand kostet eine Abfrage über alle fünf bei 6,25 $ pro gescanntem TiB, nach dem kostenlosen ersten TiB pro Monat, etwa einen Viertelcent. Bei dieser Größe spart DuckDB kein Geld, sondern den Roundtrip. Das Kostenargument beginnt, wenn Dashboards und geplante Jobs den ganzen Tag Terabytes neu scannen. Dann kann ein stabiler Extrakt als Parquet, abgefragt mit DuckDB, eine echte Zeile von der Rechnung streichen. Wenn du noch beim Warehouse selbst schwankst, lies BigQuery vs. Snowflake: Ein ehrlicher Vergleich.

DuckDB ersetzt nicht das Warehouse. Es ersetzt den Cluster, den du gerade für Daten bauen wolltest, die auf eine Maschine passen, und die hundert kleinen Abfragen, die du nur zum Anschauen in die Cloud geschickt hast.

Die echte Grenze ist nicht die Datenmenge, sondern wie viele Schreiber und Leser die Daten teilen.

Die echte Grenze ist Nebenläufigkeit, nicht Größe

Die meisten erwarten, dass DuckDB an der Datenmenge scheitert. In der Praxis ist die Grenze: Wer schreibt sonst noch?

Im reinen In-Process-Modus kann ein Prozess eine Datenbankdatei lesend und schreibend öffnen, mit beliebig vielen Threads, oder viele Prozesse öffnen sie nur lesend. Zwei Dienste können nicht gleichzeitig in dieselbe .duckdb-Datei schreiben. Das ist ein bewusster Kompromiss: Den Zustand im Speicher eines Prozesses zu halten, ist ein Grund für das Tempo.

Zwei Entwicklungen aus 2026 verschieben diese Grenze:

Quack, DuckDBs eigenes Client-Server-Protokoll. Seit Mai 2026 als Vorschau verfügbar, lässt es jeden DuckDB-Prozess seine Datenbanken per HTTP bereitstellen, und jede andere DuckDB bindet sie per ATTACH ein. In den Benchmarks des Teams übertrug Quack 60 Millionen Zeilen in 4,9 Sekunden, das PostgreSQL-Protokoll brauchte 158, und schaffte mit acht Threads rund 5.400 kleine Schreibtransaktionen pro Sekunde, mehr als PostgreSQL auf denselben Maschinen. Mit DuckDB 2.0 wird Quack stabil.
DuckLake, ein Lakehouse-Format auf SQL-Basis. Die Daten liegen als Parquet im Objektspeicher; der Katalog (welche Dateien welche Tabellenversion bilden) liegt in einer echten Datenbank wie PostgreSQL. Viele DuckDB-Instanzen können dann gleichzeitig dieselben Tabellen lesen und schreiben. DuckLake 1.0 wurde im April 2026 für produktionsreif erklärt. Es löst dasselbe Problem wie Iceberg und Delta, mit einem einfacheren Katalog; die Abwägung zwischen diesen beiden steht in Iceberg vs. Delta Lake: Ein verständlicher Leitfaden.

Wer nichts davon selbst betreiben will, nimmt MotherDuck : DuckDB in der Cloud mit Speicher, Rechenleistung pro Nutzer, Freigaben und Zugriffskontrolle. Die Preise umfassen einen kostenlosen Lite-Plan (10 GB Speicher, 10 Stunden Rechenzeit pro Monat) und einen Business-Plan für 250 $ pro Organisation und Monat plus Nutzung. Die EU-Regionen Frankfurt und Dublin sind für DSGVO-bewusste Teams in Deutschland ein wichtiger Punkt.

Was neu ist in DuckDB 2.0

DuckDB 2.0 mit dem Codenamen „Cyanoptera“ steht im Release-Kalender für den 21. Oktober 2026, ein Bugfix-Release 2.0.1 ist für November geplant. Die Vorschau nennt über 10.000 Commits seit Version 1.5. Die Neuerungen, die die Nutzung verändern:

DuckDB als Server. Quack wird stabil, und die neue Anweisung CONNECT richtet deine Sitzung auf eine entfernte DuckDB oder auf PostgreSQL bzw. MySQL aus und schiebt das SQL dorthin, wo es ausgeführt wird.
VARIANT als vollwertiger Typ. Semistrukturierte Daten (etwa JSON-Logs) werden automatisch in Spalten zerlegt. Sie komprimieren und lassen sich abfragen wie typisierte Daten, ohne dass du ein Schema deklarierst.
Trigger , BEFORE und AFTER, pro Zeile oder pro Anweisung: Audit-Tabellen ohne Anwendungscode.
Asynchrones I/O in der ganzen Engine, mit den größten Gewinnen auf S3 und anderem Netzwerkspeicher.
NEAREST-Joins für Top-k-Ähnlichkeitssuche über Embeddings, nützlich, wenn du abwägst, ob du überhaupt eine eigene Vektordatenbank brauchst.
Ein neues Speicherformat und ein neuer PEG-basierter SQL-Parser , dazu wenige Breaking Changes. Von 2.0 geschriebene Dateien nutzen standardmäßig das neue Format; pinne also Versionen, bevor du gemeinsam genutzte Dateien aktualisierst.

Wenn dir Stabilität wichtiger ist als Features: Die Linie 1.4 ist das Long-Term-Support-Release mit Support bis November 2026; ab 1.4 ist jede zweite Minor-Version LTS.

Ein praktischer Einstieg

Du brauchst keinen Migrationsplan, um von DuckDB zu profitieren. Fang klein an:

Ersetze den langsamsten pandas-Schritt in einem Notebook durch duckdb.sql(...) auf demselben DataFrame oder derselben Parquet-Datei und lass den Rest, wie er ist.
Exportiere eine stabile Warehouse-Tabelle einmal täglich als Parquet und richte explorative Arbeit auf die Datei statt aufs Warehouse.
Lass deine SQL-Transformationen in der CI gegen DuckDB laufen , damit ein kaputtes Modell im Pull Request scheitert und nicht in Produktion.
Erst dann entscheide, ob du gemeinsamen Zugriff über MotherDuck, Quack oder DuckLake brauchst oder ob das Warehouse einfach die gemeinsame Wahrheit bleibt.

Behalte das Modell im Kopf: ein Prozess, spaltenorientiert, vektorisiert, liest Dateien dort, wo sie liegen. Alles, worin DuckDB glänzt, folgt daraus, und ebenso alles, wofür es nicht gebaut ist. Wenn du es zuerst in die großen Datenbankfamilien einordnen willst, beginne mit SQL vs. NoSQL: Datenbanktypen richtig wählen.

Fazit

DuckDB verdient seinen Hype bei einem engen, aber sehr häufigen Problem: Eine Person oder ein Job stellt analytische Fragen an Daten, die auf eine Maschine passen. Dort ist es schneller als pandas, weit schneller als SQLite, bei den meisten Aufgaben mindestens so schnell wie Polars, und es braucht keinerlei Infrastruktur. Es ist kein gemeinsames Warehouse, und wer das ignoriert, landet bei Dateisperren-Fehlern. Nutze es vor und neben BigQuery oder Snowflake, nicht statt ihnen, und behalte die Nebenläufigkeit im Blick: Mit Quack und DuckLake verschiebt sich die Grenze zwischen „Laptop-Datenbank“ und „richtiger Datenbank“ schneller als jeder andere Teil des Datenstacks.

Ursprünglich veröffentlicht auf alekseialeinikov.com

Das Outbox Pattern: Zuverlässige Events ohne verteilte Transaktionen

Aleksei Aleinikov — Mon, 19 Oct 2026 07:00:00 +0000

Jeder Service, der Daten besitzt, muss dem Rest des Systems irgendwann mitteilen, dass etwas passiert ist. Eine Bestellung geht ein, also müssen Billing, Versand und E-Mail davon erfahren. Der naheliegende Code sind zwei Zeilen: Bestellung speichern, dann OrderPlaced veröffentlichen.

Diese zwei Zeilen sind die häufigste Quelle für stillen Datenverlust in eventgetriebenen Systemen. Sie schreiben in zwei verschiedene Systeme, und nichts macht das Paar atomar. Das Outbox Pattern (Transactional Outbox) ist die Standardlösung: Schreiben Sie das Event in derselben Transaktion wie die Daten in Ihre eigene Datenbank und liefern Sie es danach aus. Dieser Leitfaden zeigt den Fehler, den es verhindert, das Schema, beide Wege der Auslieferung und die Teile, die die meisten Umsetzungen falsch machen: Duplikate, Reihenfolge und Aufräumen.

Das Dual-Write-Problem

In eine Datenbank speichern und an einen Message Broker senden ist ein Dual Write. Es gibt nur drei mögliche Reihenfolgen, und alle drei scheitern.

Jede Reihenfolge scheitert anders, und Retries reparieren keine davon.

Erst committen, dann senden. Der Prozess stürzt nach dem Commit ab, wird neu deployt oder verliert das Netzwerk. Die Bestellung existiert, das Event nicht. Billing bucht nie ab, der Versand verschickt nie, und nirgends steht ein Fehler im Log, denn genau der Code, der es wiederholt hätte, ist gestorben.
Erst senden, dann committen. Das Event geht raus, dann scheitert die Transaktion an einem Constraint oder Deadlock und rollt zurück. Consumer handeln jetzt auf Basis einer Bestellung, die nie existiert hat: ein Phantom-Event.
Innerhalb der Transaktion senden. Der Broker ist nicht Teil Ihrer Datenbanktransaktion, das wirkt also nur sicherer. Zeilensperren bleiben gehalten, während Sie auf das Netzwerk warten, und bei einem Timeout wissen Sie nicht, ob die Nachricht rausging.

Die Lehrbuchantwort ist eine verteilte Transaktion (Two-Phase Commit, XA) über beide Systeme. In der Praxis nehmen die meisten Broker nicht an XA teil, und 2PC koppelt die Verfügbarkeit beider Systeme aneinander. Kafkas eigene Transaktionen umfassen Schreibvorgänge in Kafka-Topics, nicht in Ihre Datenbank. Kafka hat zwar einen optionalen Weg angenommen, mit dem ein Producer an einem extern koordinierten Two-Phase Commit teilnehmen kann (KIP-939), aber auch das ist kein XA: Ihre Anwendung wird zum Koordinator und muss den Transaktionszustand selbst speichern und wiederherstellen.

Der Ausweg: aufhören, zwei Schreibvorgänge zu haben.

Was das Outbox Pattern ist

Das Outbox Pattern speichert ausgehende Events in einer Outbox-Tabelle, in derselben Datenbanktransaktion wie die fachliche Änderung, und veröffentlicht sie danach über ein separates Relay. So veröffentlichen Microservices Events zuverlässig und mindestens einmal, ohne verteilte Transaktion.

Das Pattern, von Chris Richardson auf microservices.io katalogisiert, macht aus zwei Schreibvorgängen einen:

Das Event als Zeile schreiben. Eine outbox-Tabelle liegt in derselben Datenbank wie Ihre Fachdaten.
Dieselbe Transaktion nutzen. Fachliche Änderung und Outbox-Insert werden gemeinsam committet oder gemeinsam zurückgerollt. Das Event existiert genau dann, wenn die Änderung committet wurde.
Danach weiterreichen. Ein separater Prozess liest committete Outbox-Zeilen und veröffentlicht sie an den Broker, mit Retries, bis der Broker bestätigt.

Das Event teilt das Schicksal der Daten. Die Zustellung wird at-least-once, und Consumer deduplizieren.

Die Datenbanktransaktion, der Sie ohnehin vertrauen, ist jetzt der einzige atomare Schritt. Alles nach dem Commit ist eine Retry-Schleife, und Retry-Schleifen lassen sich leicht zuverlässig machen.

Es ist derselbe Baustein, der am Anfang einer zuverlässigen Webhook-Zustellung steht und hinter dem Versand von einer Million Benachrichtigungen ohne Absturz.

Schritt 1: die Outbox-Tabelle

Verwenden Sie die Spaltennamen, die Debezium standardmäßig erwartet. Sie kosten nichts und halten den Weg zu Change Data Capture offen.

outbox.sql


CREATE TABLE outbox (

  id uuid PRIMARY KEY,

  aggregatetype varchar(255) NOT NULL, -- bestimmt das Topic, z. B. "order"

  aggregateid varchar(255) NOT NULL, -- Nachrichtenschlüssel, hält die Reihenfolge pro Aggregat

  type varchar(255) NOT NULL, -- "OrderPlaced"

  payload jsonb NOT NULL,

  created_at timestamptz NOT NULL DEFAULT now(),

  published_at timestamptz -- nur für ein Polling-Relay

);

-- Das Polling-Relay betrachtet nur unveröffentlichte Zeilen.

CREATE INDEX outbox_unpublished ON outbox (created_at)

  WHERE published_at IS NULL;

Die id ist die Identität des Events für sein ganzes Leben. Consumer erkennen daran Duplikate, also erzeugen Sie sie in der Anwendung, nicht im Relay.

Schritt 2: das Event in derselben Transaktion schreiben

place-order.sql


BEGIN;

INSERT INTO orders (id, customer_id, total) VALUES (42, 7, 99.00);

INSERT INTO outbox (id, aggregatetype, aggregateid, type, payload)

VALUES (gen_random_uuid(), 'order', '42', 'OrderPlaced',

        '{"eventVersion": 1, "orderId": 42, "customerId": 7, "total": 99.00}');

COMMIT;

Zwei Details zählen mehr, als es scheint:

Der Payload ist ein Vertrag, kein Tabellen-Dump. Schreiben Sie das Event, das Consumer brauchen, mit expliziter Version, nicht SELECT * der Bestelltabelle. Ihre Tabelle wird sich ändern; das Event-Schema muss sich kompatibel weiterentwickeln.
Halten Sie die Transaktion kurz. Die Outbox fügt einen Insert hinzu. Sie darf keinen Netzwerkaufruf hinzufügen.

Schritt 3: die Zeilen weiterreichen

Es gibt zwei Wege, committete Zeilen aus der Tabelle zu holen. Richardson nennt sie Polling Publisher und Transaction Log Tailing.

Mit Polling starten. Zu CDC wechseln, wenn Latenz, Last oder Reihenfolge es verlangen.

Variante A: Polling Publisher

Eine Schleife in Ihrem eigenen Service. Einen Batch beanspruchen, veröffentlichen, als erledigt markieren, alles in einer kurzen Transaktion:

relay-batch.sql


BEGIN;

SELECT id, aggregatetype, aggregateid, type, payload

FROM outbox

WHERE published_at IS NULL

ORDER BY created_at

LIMIT 100

FOR UPDATE SKIP LOCKED;

-- jede Zeile an den Broker senden und auf das Ack warten, dann:

UPDATE outbox SET published_at = now() WHERE id = ANY($published_ids);

COMMIT;

FOR UPDATE SKIP LOCKED (PostgreSQL ab 9.5, MySQL ab 8.0) lässt mehrere Relay-Instanzen laufen, ohne dass sie um dieselben Zeilen kämpfen. Damit kommen auch die zwei klassischen Fehler von Polling-Relays:

Achtung

Pollen Sie nie „alles nach der zuletzt gesehenen ID“. IDs und Zeitstempel werden beim Insert vergeben, sichtbar werden Zeilen aber erst beim Commit, und Transaktionen committen in beliebiger Reihenfolge. Eine langsame Transaktion kann Zeile 41 committen, nachdem Sie schon an 42 vorbei sind, und ein Poller mit Hochwassermarke überspringt sie für immer. Selektieren Sie stattdessen auf published_at IS NULL, wie oben.

Der zweite Fehler ist die Reihenfolge. Mit mehreren Relays und SKIP LOCKED können zwei Events derselben Bestellung von verschiedenen Instanzen in beliebiger Reihenfolge veröffentlicht werden. Wenn das für Consumer zählt, und meistens tut es das, geben Sie jedem Aggregat genau einen Besitzer: ein einziges Relay oder Relays, die jeweils einen festen Bereich von hash(aggregateid) beanspruchen.

Polling bringt bis zu ein Intervall Latenz. In PostgreSQL senken Sie sie, ohne häufiger zu pollen: NOTIFY outbox in der schreibenden Transaktion, und das Relay lauscht per LISTEN. Benachrichtigungen werden erst beim Commit zugestellt, das Relay wacht also genau dann auf, wenn es etwas zu lesen gibt, und das Intervall wird zum Sicherheitsnetz.

Variante B: Transaction Log Tailing (CDC)

Statt die Tabelle abzufragen, lesen Sie das Transaktionslog der Datenbank: das WAL in PostgreSQL, das Binlog in MySQL. Inserts kommen in Commit-Reihenfolge an, ganz ohne Polling-Abfragen. Das übliche Werkzeug ist Debezium mit seinem Outbox Event Router :

outbox-connector.properties


connector.class=io.debezium.connector.postgresql.PostgresConnector

plugin.name=pgoutput

table.include.list=public.outbox

transforms=outbox

transforms.outbox.type=io.debezium.transforms.outbox.EventRouter

transforms.outbox.table.expand.json.payload=true

value.converter=org.apache.kafka.connect.json.JsonConverter

Mit den Standardspalten aus Schritt 1 veröffentlicht der Router jede Zeile an das Topic outbox.event.<aggregatetype>, nutzt aggregateid als Nachrichtenschlüssel, sodass alle Events eines Aggregats geordnet in einer Partition landen, und legt die Event-id zur Deduplizierung in einen Nachrichten-Header.

Zwei Dinge machen Log Tailing im großen Maßstab attraktiv:

Die Tabelle kann leer bleiben. Fügen Sie die Outbox-Zeile ein und löschen Sie sie in derselben Transaktion. Der Insert steht trotzdem im Log, Debezium veröffentlicht ihn, und der Router ignoriert Deletes. Kein Aufräumjob, kein Bloat.
Keine Abfragelast. Der Connector liest das Log, das die Datenbank ohnehin schreibt.

Und eine Sache verdient Respekt: In PostgreSQL nutzt CDC einen Replication Slot , und die Datenbank hält WAL dafür vor, bis der Connector es bestätigt. Ein Connector, der ein Wochenende ausfällt, kann die Platte füllen. Alarmieren Sie auf Slot-Lag und begrenzen Sie ihn mit max_slot_wal_keep_size (ab PostgreSQL 13).

Tipp

Wenn die Unterschiede zwischen PostgreSQL und MySQL für Ihre Plattform zählen, zählen sie auch hier: Logical Decoding mit pgoutput auf der einen Seite, zeilenbasiertes Binlog auf der anderen. Debezium unterstützt beide.

At-least-once: Consumer idempotent machen

Die Outbox garantiert, dass ein Event nie verloren geht. Sie garantiert nicht , dass es genau einmal ankommt. Das Relay kann einen Batch veröffentlichen und abstürzen, bevor es published_at setzt. Nach dem Neustart veröffentlicht es dieselben Events erneut. Eine erneute Zustellung durch den Broker oder ein Consumer-Absturz vor dem Ack bewirken dasselbe.

Jeder Consumer muss also deduplizieren, und der robuste Weg ist eine Inbox : Die Event-ID wird in derselben Transaktion gespeichert wie die eigentliche Änderung.

consume-order-placed.sql


BEGIN;

INSERT INTO processed_events (event_id) VALUES ($event_id)

ON CONFLICT (event_id) DO NOTHING;

-- 0 Zeilen eingefügt: Duplikat, committen und bestätigen, ohne etwas zu tun.

INSERT INTO invoices (order_id, amount) VALUES (42, 99.00);

COMMIT;

-- die Nachricht erst nach dem Commit bestätigen

At-least-once-Zustellung plus idempotente Consumer ist das, was in der Praxis mit „exactly-once“ gemeint ist. Dieselbe Technik schützt HTTP-APIs; die Details stehen in Idempotenz in der Praxis.

Reihenfolge: was Sie versprechen können und was nicht

Pro Aggregat: ja. Schlüsseln Sie jede Nachricht nach aggregateid. Kafka hält die Reihenfolge innerhalb einer Partition, Google Pub/Sub hat Ordering Keys für denselben Zweck. Alle Events zu Bestellung 42 kommen in Commit-Reihenfolge an, solange ein einziges Relay diesen Schlüssel besitzt.
Global: nein. Events zu Bestellung 42 und Bestellung 17 können in beliebiger relativer Reihenfolge ankommen. Bauen Sie Consumer so, dass das in Ordnung ist.
Trotzdem absichern. Legen Sie eine Version oder Sequenznummer pro Aggregat in den Payload. Ein Consumer, der Version 5 nach Version 6 sieht, kann sie ignorieren, statt neueren Zustand zu überschreiben.

Die Outbox betreiben

Aufräumen. Ein Polling-Relay hinterlässt veröffentlichte Zeilen. Löschen Sie sie nach einem kurzen Audit-Fenster in Batches, oder partitionieren Sie die Tabelle bei hohem Volumen nach Tag und verwerfen alte Partitionen, was im Vergleich zu großen DELETE-Anweisungen und der Vacuum-Arbeit, die sie auslösen, nichts kostet. Mit CDC löschen Sie in derselben Transaktion, wie oben beschrieben.

Monitoring. Eine Metrik sagt fast alles: das Alter des ältesten unveröffentlichten Events. Mit Polling ist das now() - min(created_at) WHERE published_at IS NULL, mit CDC der Replikations-Lag. Alarmieren Sie, wenn es einige Minuten überschreitet; dieselbe Regel fängt ein totes Relay, einen Broker-Ausfall und ein Poison Event.

Poison Events. Ein Event, das der Broker ablehnt (zu groß, ungültiges Schema), blockiert die Warteschlange für seinen Schlüssel. Zählen Sie Versuche pro Zeile und verschieben Sie sie nach einem Limit in eine Dead-Letter-Tabelle mit Alarm, statt endlos zu wiederholen.

Tracing. Speichern Sie den Trace-Kontext in der Outbox-Zeile und stellen Sie ihn im Relay wieder her, damit ein Trace dem Request vom API-Aufruf über den Broker bis in jeden Consumer folgt. Debeziums Router unterstützt das über eine Tracing-Spalte.

Outbox-Implementierungen in Java, .NET, Go und MongoDB

Das Relay müssen Sie selten selbst schreiben. Das Pattern steckt in den Frameworks, die die meisten Teams ohnehin nutzen:

Stack	Fertige Outbox	Hinweis
Java, Spring	Spring Modulith Event Publication Registry	Laut eigener Doku fehlen der nativen Externalisierung fortgeschrittene Outbox-Funktionen; 2.1 bringt Namastack Outbox und JobRunr als Backends
Java	Eventuate Tram	Von Chris Richardson, dem Autor des Pattern-Katalogs
.NET (C#)	MassTransit Transactional Outbox, NServiceBus Outbox, Wolverine, CAP	MassTransit und NServiceBus deduplizieren auch auf Consumer-Seite
Go	Watermill Forwarder	Veröffentlicht in Ihrer Transaktion in eine SQL-Tabelle und leitet an den echten Broker weiter
Jede Sprache	Debezium (Kafka Connect oder Debezium Server)	Debezium Server sendet ohne Kafka an Google Pub/Sub, Amazon Kinesis und andere

MongoDB unterstützt Multi-Document-Transaktionen auf Replica Sets, die Outbox funktioniert also genauso: Bestellung und Outbox-Dokument in einer Session-Transaktion schreiben. Debezium hat einen eigenen MongoDB Outbox Event Router, weil der relationale nicht mit dem MongoDB-Connector funktioniert.

Cloud-Datenbanken haben oft ein Log, das Sie statt Polling lesen können: DynamoDB Streams nach einem TransactWriteItems, das Item und Event gemeinsam schreibt, oder Spanner Change Streams auf einer Outbox-Tabelle.

Outbox oder etwas anderes?

Ansatz	Atomar mit Ihren Daten	Zusätzliche Infrastruktur	Trade-off
Erst committen, dann senden	Nein	Keine	Verliert Events bei Absturz
Two-Phase Commit (XA)	Ja	XA-fähiger Broker	Die meisten Broker unterstützen es nicht; koppelt Verfügbarkeit
Transactional Outbox	Ja	Ein Relay	At-least-once, Consumer müssen deduplizieren
CDC auf Fachtabellen	Ja	CDC-Pipeline	Ihr internes Schema wird zum öffentlichen Vertrag
Event Sourcing	Ja, das Event ist der Zustand	Event Store	Ändert Ihr gesamtes Persistenzmodell

Die Outbox ist die Variante, die einen bewussten Event-Vertrag behält und nichts Exotischeres braucht als eine lokale Transaktion.

Wann Sie keine Outbox brauchen

Niemand außerhalb der Datenbank muss davon erfahren. Ist die Folgearbeit ein Job in einer Queue-Tabelle in derselben Datenbank, wird die Job-Zeile bereits atomar mit Ihren Daten committet. Sie haben eine Outbox ohne den Namen.
Sie nutzen bereits Event Sourcing. Das Anhängen an den Event Store ist die Zustandsänderung; veröffentlichen Sie aus dem Store.
Ein verlorenes Event ist wirklich egal. Analytics-Pings und Best-Effort-Cache-Warming vertragen den seltenen Verlust. Fachliche Fakten wie Bestellungen, Zahlungen und Berechtigungen nicht.

Das Pattern passt auch direkt dazu, wie eine Microservices-Architektur funktioniert: Services besitzen ihre Daten, und asynchrone Events sind der Weg, über den der Rest des Systems von Änderungen erfährt, ohne die Datenbank eines anderen Service zu lesen.

Das Fazit

Der Fehler, den die Outbox behebt, ist im Test unsichtbar und in Produktion unvermeidlich: ein Absturz zwischen „gespeichert“ und „veröffentlicht“. Die Lösung ist, das Event nicht mehr als zweiten Schreibvorgang zu behandeln. Committen Sie es mit den Daten, in der Transaktion, der Sie ohnehin vertrauen, und lassen Sie ein Relay es mit Retries zustellen.

Fangen Sie einfach an: eine Outbox-Tabelle mit Debezium-kompatiblen Spalten, ein Polling-Relay mit SKIP LOCKED, das unveröffentlichte Zeilen selektiert statt an der letzten ID vorbeizulesen, Consumer, die anhand der Event-ID deduplizieren, und ein Alarm auf das Alter des ältesten unveröffentlichten Events. Wechseln Sie zu Log Tailing, wenn Latenz oder Last es verlangen. Ihr Schema ist schon bereit.

Weiterlesen: Webhooks erklärt: Signatur, Retries und Idempotenz · Eine Million Benachrichtigungen versenden, ohne abzustürzen

Ursprünglich veröffentlicht auf alekseialeinikov.com

The Outbox Pattern: Reliable Events Without Distributed Transactions

Aleksei Aleinikov — Mon, 19 Oct 2026 07:00:00 +0000

Every service that owns data eventually has to tell the rest of the system that something happened. An order is placed, so billing, shipping and email need to know. The obvious code is two lines: save the order, then publish OrderPlaced.

Those two lines are the most common source of silent data loss in event-driven systems. They write to two different systems, and nothing makes the pair atomic. The transactional outbox pattern is the standard fix: write the event into your own database in the same transaction as the data, and ship it afterwards. This guide covers the failure it prevents, the schema, both ways to relay events, and the parts most implementations get wrong: duplicates, ordering and cleanup.

The dual-write problem

Saving to a database and publishing to a message broker is a dual write. There are only three ways to order it, and all three break.

Each ordering fails differently, and retries cannot fix any of them.

Commit, then publish. The process crashes, is redeployed or loses the network after the commit. The order exists; the event does not. Billing never charges, shipping never ships, and no error is logged anywhere, because the code that would have retried is the code that died.
Publish, then commit. The event goes out, then the transaction fails on a constraint or a deadlock and rolls back. Consumers now act on an order that never existed: a phantom event.
Publish inside the transaction. The broker is not part of your database transaction, so this only looks safer. Row locks stay held while you wait on the network, and when the call times out you cannot tell whether the message went out.

The textbook answer is a distributed transaction (two-phase commit, XA) spanning both systems. In practice most brokers do not take part in XA, and 2PC couples the availability of both systems to each other. Kafka’s own transactions cover writes to Kafka topics, not to your database. Kafka has accepted an opt-in way for a producer to join an externally coordinated two-phase commit (KIP-939), but it is not XA either: your application becomes the coordinator and has to store and recover transaction state itself.

The way out is to stop having two writes.

What the transactional outbox pattern is

The transactional outbox pattern stores outgoing events in an outbox table, in the same database transaction as the business change, and publishes them afterwards with a separate relay. You get reliable, at-least-once event publishing between microservices without a distributed transaction.

The pattern, catalogued by Chris Richardson on microservices.io, turns two writes into one:

Write the event as a row. An outbox table lives in the same database as your business data.
Use the same transaction. The business change and the outbox insert commit or roll back together. The event exists if and only if the change committed.
Relay it afterwards. A separate process reads committed outbox rows and publishes them to the broker, retrying until the broker acknowledges.

The event shares the fate of the data. Delivery becomes at-least-once, and consumers deduplicate.

The database transaction you already trust is now the only atomic step. Everything after the commit is a retry loop, and retry loops are easy to make reliable.

It is the same building block that sits at the start of a reliable webhook delivery pipeline and behind sending a million notifications without falling over.

Step 1: the outbox table

Use the column names Debezium expects by default. They cost nothing and keep the door open to change data capture later.

outbox.sql


CREATE TABLE outbox (

  id uuid PRIMARY KEY,

  aggregatetype varchar(255) NOT NULL, -- routes to a topic, e.g. "order"

  aggregateid varchar(255) NOT NULL, -- message key, keeps per-aggregate order

  type varchar(255) NOT NULL, -- "OrderPlaced"

  payload jsonb NOT NULL,

  created_at timestamptz NOT NULL DEFAULT now(),

  published_at timestamptz -- only used by a polling relay

);

-- The polling relay only ever looks at unpublished rows.

CREATE INDEX outbox_unpublished ON outbox (created_at)

  WHERE published_at IS NULL;

The id is the event’s identity for its whole life. Consumers use it to detect duplicates, so generate it in the application, not in the relay.

Step 2: write the event in the same transaction

place-order.sql


BEGIN;

INSERT INTO orders (id, customer_id, total) VALUES (42, 7, 99.00);

INSERT INTO outbox (id, aggregatetype, aggregateid, type, payload)

VALUES (gen_random_uuid(), 'order', '42', 'OrderPlaced',

        '{"eventVersion": 1, "orderId": 42, "customerId": 7, "total": 99.00}');

COMMIT;

Two details matter more than they look:

The payload is a contract, not a row dump. Write the event consumers need, with an explicit version, not SELECT * of the orders table. Your table will change; the event schema has to evolve compatibly.
Keep the transaction short. The outbox adds one insert. It must not add a network call.

Step 3: relay the rows

There are two ways to get committed rows out of the table. Richardson names them polling publisher and transaction log tailing.

Start with polling. Move to CDC when latency, load or ordering demands it.

Option A: polling publisher

A loop in your own service. Claim a batch, publish it, mark it done, all in a short transaction:

relay-batch.sql


BEGIN;

SELECT id, aggregatetype, aggregateid, type, payload

FROM outbox

WHERE published_at IS NULL

ORDER BY created_at

LIMIT 100

FOR UPDATE SKIP LOCKED;

-- publish each row to the broker and wait for the ack, then:

UPDATE outbox SET published_at = now() WHERE id = ANY($published_ids);

COMMIT;

FOR UPDATE SKIP LOCKED (PostgreSQL 9.5+, MySQL 8.0+) lets several relay instances run without fighting over the same rows. It also introduces the two classic bugs of polling relays:

Warning

Never poll “everything after the last ID I saw”. IDs and timestamps are assigned when a row is inserted, but rows become visible when they commit, and transactions commit out of order. A slow transaction can commit row 41 after you already moved past 42, and a high-water-mark poller skips it forever. Select on published_at IS NULL instead, as above.

The second bug is ordering. With several relays and SKIP LOCKED, two events for the same order can be published by different instances in either order. If consumers care, and they usually do, give each aggregate a single owner: one relay, or relays that each claim a fixed range of hash(aggregateid).

Polling adds latency of up to one interval. In PostgreSQL you can cut it without polling harder: issue NOTIFY outbox in the writing transaction and have the relay LISTEN. Notifications are only delivered when the transaction commits, so the relay wakes up exactly when there is something to read, and the interval becomes a safety net.

Option B: transaction log tailing (CDC)

Instead of querying the table, read the database’s own transaction log: the WAL in PostgreSQL, the binlog in MySQL. Inserts arrive in commit order, with no polling queries at all. The common tool is Debezium with its Outbox Event Router :

outbox-connector.properties


connector.class=io.debezium.connector.postgresql.PostgresConnector

plugin.name=pgoutput

table.include.list=public.outbox

transforms=outbox

transforms.outbox.type=io.debezium.transforms.outbox.EventRouter

transforms.outbox.table.expand.json.payload=true

value.converter=org.apache.kafka.connect.json.JsonConverter

With the default columns from Step 1, the router publishes each row to the topic outbox.event.<aggregatetype>, uses aggregateid as the message key, so all events of one aggregate land in one partition in order, and puts the event id into a message header for deduplication.

Two things make log tailing attractive at scale:

The table can stay empty. Insert the outbox row and delete it in the same transaction. The insert is still in the log, so Debezium publishes it, and the router ignores deletes. No cleanup job, no bloat.
No query load. The connector reads the log the database writes anyway.

And one thing to respect: in PostgreSQL, CDC uses a replication slot , and the database keeps WAL for it until the connector confirms it. A connector that is down for a weekend can fill the disk. Alert on slot lag, and cap it with max_slot_wal_keep_size (PostgreSQL 13+).

Tip

If the differences between PostgreSQL and MySQL matter for your platform, they matter here too: logical decoding with pgoutput on one side, row-based binlog on the other. Debezium supports both.

At-least-once: make consumers idempotent

The outbox guarantees that an event is never lost. It does not guarantee that it arrives once. The relay can publish a batch and crash before it records published_at. After a restart it publishes the same events again. A broker redelivery or a consumer crash before its ack does the same.

So every consumer must deduplicate, and the robust way is an inbox : record the event ID in the same transaction as the side effect.

consume-order-placed.sql


BEGIN;

INSERT INTO processed_events (event_id) VALUES ($event_id)

ON CONFLICT (event_id) DO NOTHING;

-- 0 rows inserted: duplicate, commit and acknowledge without doing anything.

INSERT INTO invoices (order_id, amount) VALUES (42, 99.00);

COMMIT;

-- acknowledge the message only after the commit

At-least-once delivery plus idempotent consumers is what people mean by “exactly-once” in practice. The same technique protects HTTP APIs; the details are in idempotency in practice.

Ordering: what you can and cannot promise

Per aggregate: yes. Key every message by aggregateid. Kafka keeps order within a partition, and Google Pub/Sub has ordering keys for the same purpose. All events for order 42 arrive in the order they were committed, as long as a single relay owns that key.
Globally: no. Events for order 42 and order 17 can arrive in any relative order. Design consumers so that is fine.
Defend anyway. Put a version or sequence number per aggregate in the payload. A consumer that sees version 5 after version 6 can ignore it instead of overwriting newer state.

Operating the outbox

Cleanup. A polling relay leaves published rows behind. Delete them in batches after a short audit window, or for high volume partition the table by day and drop old partitions, which costs nothing compared with large DELETE statements and the vacuum work they cause. With CDC, delete in the same transaction as described above.

Monitoring. One metric tells you almost everything: the age of the oldest unpublished event. With polling that is now() - min(created_at) WHERE published_at IS NULL; with CDC it is replication lag. Alert when it exceeds a few minutes; it catches a dead relay, a broker outage and a poison event with the same rule.

Poison events. An event the broker rejects (too large, invalid schema) blocks the queue for its key. Count attempts per row, and after a limit move it to a dead-letter table and alert, instead of retrying forever.

Tracing. Store the trace context in the outbox row and restore it in the relay, so a trace follows the request from the API call through the broker into every consumer. Debezium’s router supports this with a tracing column.

Outbox implementations in Java, .NET, Go and MongoDB

You rarely need to write the relay from scratch. The pattern ships in the frameworks most teams already use:

Stack	Ready-made outbox	Note
Java, Spring	Spring Modulith Event Publication Registry	Its own docs say the native externalization lacks advanced outbox features; 2.1 adds Namastack Outbox and JobRunr as backends
Java	Eventuate Tram	From Chris Richardson, the author of the pattern catalogue
.NET (C#)	MassTransit Transactional Outbox, NServiceBus Outbox, Wolverine, CAP	MassTransit and NServiceBus also deduplicate on the consumer side
Go	Watermill Forwarder	Publishes into an SQL table in your transaction, forwards to the real broker
Any language	Debezium (Kafka Connect or Debezium Server)	Debezium Server sends to Google Pub/Sub, Amazon Kinesis and others without Kafka

MongoDB supports multi-document transactions on replica sets, so the outbox works the same way: write the order and the outbox document in one session transaction. Debezium has a dedicated MongoDB outbox event router, because the relational one does not work with the MongoDB connector.

Cloud databases often have a log you can tail instead of polling: DynamoDB Streams after a TransactWriteItems that writes the item and the event together, or Spanner change streams on an outbox table.

Outbox or something else?

Approach	Atomic with your data	Extra infrastructure	Trade-off
Commit, then publish	No	None	Loses events on crash
Two-phase commit (XA)	Yes	XA-capable broker	Most brokers don’t support it; couples availability
Transactional outbox	Yes	A relay	At-least-once, consumers must dedupe
CDC on business tables	Yes	CDC pipeline	Your internal schema becomes the public contract
Event sourcing	Yes, the event is the data	Event store	Changes your whole persistence model

The outbox is the option that keeps a deliberate event contract while needing nothing more exotic than a local transaction.

When you don’t need an outbox

Nobody outside the database needs to know. If the follow-up work is a job in a queue table in the same database, the job row already commits atomically with your data. You have an outbox without the name.
You already do event sourcing. The append to the event store is the state change; publish from the store.
Losing an event is genuinely fine. Analytics pings and best-effort cache warming can tolerate the rare loss. Business facts like orders, payments and permissions cannot.

The pattern also fits naturally into how a microservices architecture works: services own their data, and asynchronous events are how the rest of the system learns about changes without reading another service’s database.

The bottom line

The bug the outbox fixes is invisible in testing and inevitable in production: a crash between “saved” and “published”. The fix is to stop treating the event as a second write. Commit it with the data, in the transaction you already trust, and let a relay deliver it with retries.

Start simple: an outbox table with Debezium-compatible columns, a polling relay with SKIP LOCKED that selects unpublished rows rather than reading past the last ID, consumers that deduplicate by event ID, and one alert on the age of the oldest unpublished event. Move to log tailing when latency or load asks for it. Your schema is already ready.

Read next: Webhooks explained: signatures, retries and idempotency · Send a million notifications without falling over

Originally published at alekseialeinikov.com

DEV Community: Aleksei Aleinikov

JWT Explained: What a JSON Web Token Is and How It Breaks

What is a JWT? A JSON Web Token example

Anatomy of a JSON Web Token

The header

The payload: claims

The signature

Signed is not encrypted

How to verify a JWT correctly

HS256 vs RS256 vs ES256: which algorithm?

Six JWT attacks that still work

1. alg: none

2. Algorithm confusion (RS256 to HS256)

3. Weak HMAC secrets

4. Key injection through the header

5. Missing audience and issuer checks

6. Tokens that live forever

JWT decoder: read a token without leaking it

JWT vs session cookies: when to use a JWT

JWT vs OAuth

The Bottom Line

JWT erklärt: Was ein JSON Web Token ist und wie es bricht

Was ist ein JWT? Ein JSON Web Token als Beispiel

Aufbau eines JSON Web Tokens

Der Header

Die Payload: Claims

Die Signatur

Signiert ist nicht verschlüsselt

Wie man ein JWT richtig prüft

HS256 vs. RS256 vs. ES256: welcher Algorithmus?

Sechs JWT-Angriffe, die heute noch funktionieren

1. alg: none

2. Algorithm Confusion (RS256 zu HS256)

3. Schwache HMAC-Secrets

4. Schlüssel-Injection über den Header

5. Fehlende Prüfung von Audience und Issuer

6. Tokens, die ewig leben

JWT-Decoder: ein Token lesen, ohne es preiszugeben

JWT oder Session-Cookie: wann ein JWT passt

JWT vs. OAuth

Fazit

PostgreSQL-Indizes: Welcher Typ wann? (10-Mio-Zeilen-Benchmark)

Welcher PostgreSQL-Index-Typ passt: die kurze Antwort

Wie ein Index eine Zeile findet und was ein Scan kostet

Der Benchmark: eine Tabelle, 10 Millionen Zeilen, und was jeder Index kostet

B-tree: der Standard aus gutem Grund

Hash-Index: nicht besser als B-tree

BRIN: ein 72-KiB-Index für zeitlich geordnete Daten

Partielle Indizes: nur die Zeilen indizieren, die zählen

Abdeckende Indizes: schneller, aber nur auf einer sauberen Tabelle

Mehrspaltige Indizes und Skip Scan in PostgreSQL 18

GIN: wenn eine Zeile viele Werte enthält

GiST und SP-GiST: für Formen und Bereiche

Wenn der Planer deinen Index ignoriert

Die Schreibsteuer: Jeder Index kostet bei jedem Insert

Zufällige UUID-Schlüssel: versteckte Indexkosten

So findest du ungenutzte und fehlende Indizes

Was sich bei Indizes in PostgreSQL 18 und 19 ändert

Eine praktische Checkliste

Das Fazit

PostgreSQL Indexes: Which Type to Use (10M-Row Benchmark)

Which PostgreSQL index type to use: the short answer

How an index finds a row, and what a scan costs

The benchmark: one table, 10 million rows, and what each index costs

B-tree: the default for a reason

Hash index: no better than B-tree

BRIN: a 72 KiB index for time-ordered data

Partial indexes: index only the rows that matter

Covering indexes: faster, but only on a clean table

Multicolumn indexes and skip scan in PostgreSQL 18

GIN: when a row contains many values

GiST and SP-GiST: for shapes and ranges

When the planner ignores your index

The write tax: every index costs on every insert

Random UUID keys: a hidden index cost

How to find unused and missing indexes

What changed in PostgreSQL 18 and 19 for indexes

A practical checklist

The Bottom Line

AI Gateway (LLM Gateway) Explained: What It Does, When You Need One and What It Costs

1. `alg: none`

1. `alg: none`