GraphQL Schema Registry mit Apollo Studio oder Hive betreiben

1. Warum ein GraphQL Schema Registry überhaupt nötig wird

Solange ein einzelnes Team ein einzelnes GraphQL-Schema pflegt, reicht ein Blick in den Pull Request, um eine Breaking Change zu erkennen. Sobald mehrere Teams über Federation eigene Subgraphs beisteuern, funktioniert diese informelle Kontrolle nicht mehr. Ein GraphQL Schema Registry ist die zentrale Stelle, an der jede Version jedes Subgraphs registriert, komponiert und gegen die tatsächliche Nutzung im Feld geprüft wird, bevor sie live geht. Ohne diese zentrale Instanz entdeckt man Breaking Changes erst, wenn Kundinnen und Kunden Fehler melden.

Das Kernproblem ist Sichtbarkeit über Team-Grenzen hinweg. Ein Team entfernt ein scheinbar ungenutztes Feld aus seinem Subgraph, weiß aber nicht, dass ein mobiles Client-Team dieses Feld seit Monaten in einer selten aufgerufenen Ansicht verwendet. Ein GraphQL Schema Registry löst das, indem es echte Operationsdaten aus der Produktion sammelt und jede geplante Änderung gegen diese Daten validiert, nicht nur gegen den statischen Schema-Text. Das verschiebt die Fehlerfindung von der Laufzeit in die Pull-Request-Phase, wo sie günstig und ohne Kundenkontakt behoben werden kann.

Für Teams, die von einem einzelnen monolithischen Schema zu Federation wechseln, ist das Schema Registry meist der erste Baustein, der eingeführt wird, noch vor der eigentlichen Aufteilung in Subgraphs. Der Grund: Ohne zentrale Registry-Instanz gibt es keine verlässliche Quelle für den aktuellen Composition-Status, und jede Komposition müsste manuell und lokal nachvollzogen werden.

2. Composition: aus vielen Subgraphs ein Supergraph

Composition ist der Prozess, bei dem ein Composition-Tool mehrere Subgraph-Schemas zu einem einzigen Supergraph-Schema zusammenführt, das der Federation-Gateway ausliefert. Ein GraphQL Schema Registry übernimmt genau diesen Schritt zentral: Jeder Subgraph publiziert seine aktuelle SDL an die Registry, die Registry führt die Komposition durch und markiert Konflikte, bevor der Gateway die neue Version überhaupt lädt. Typ-Konflikte zwischen Subgraphs, doppelt definierte Felder ohne @shareable-Direktive oder fehlende Schlüssel für @key-Referenzen werden so schon vor dem Deployment sichtbar.

Die Komposition selbst folgt klaren Regeln der Federation-Spezifikation: Felder, die in mehreren Subgraphs auftauchen, müssen entweder identisch typisiert oder explizit als teilbar markiert sein. Ein GraphQL Schema Registry führt diese Prüfung bei jedem Publish-Vorgang automatisch durch und verweigert die Veröffentlichung einer inkompatiblen Version, statt den fehlerhaften Supergraph erst im Gateway scheitern zu lassen.

# subgraph-products/schema.graphql
# Type Product is owned here, key field "id" enables entity resolution
type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Money!
  description: String
}

type Money {
  amount: Float!
  currency: String!
}

extend type Query {
  product(id: ID!): Product
  products(first: Int = 20): [Product!]!
}

3. Apollo Studio: Publishing, Variants und Graph-Struktur

Apollo Studio organisiert jedes registrierte Schema als "Graph" mit mehreren "Variants", typischerweise staging, production und projektspezifische Feature-Branches. Jeder Subgraph wird an eine bestimmte Variant publiziert, Apollo Studio führt die Komposition automatisch aus und macht das Ergebnis im Studio-Dashboard sichtbar, inklusive einer visuellen Diff-Ansicht gegenüber der vorherigen Version. Diese Struktur macht ein GraphQL Schema Registry für mehrere parallele Umgebungen praktikabel, ohne dass Teams manuell verschiedene Composition-Ergebnisse verwalten müssen.

Zugriffsrechte werden pro Graph vergeben, sodass unterschiedliche Teams nur ihre eigenen Subgraphs publizieren dürfen, während die Composition-Übersicht für alle sichtbar bleibt. Apollo Studio speichert außerdem die vollständige Publish-Historie, sodass sich jede Schema-Version bis zum verantwortlichen Commit zurückverfolgen lässt, ein entscheidender Vorteil beim Debugging von Produktionsproblemen, die erst nach mehreren Deployments auftreten.

4. Der Rover-CLI-Workflow im Detail

Rover ist Apollos Kommandozeilenwerkzeug für die Interaktion mit dem GraphQL Schema Registry. Der typische Workflow besteht aus drei Schritten: rover subgraph check validiert eine geplante Änderung gegen die registrierte Composition und die Usage-Daten, rover subgraph publish veröffentlicht das Schema final, und rover graph fetch lädt den aktuellen Supergraph für lokale Tests herunter. Dieser Dreischritt wird in den meisten Teams direkt in die CI-Pipeline integriert, sodass kein Entwickler manuell an Rover denken muss.

# Validate a subgraph change against the registered composition
rover subgraph check my-graph@production \
  --schema ./products/schema.graphql \
  --name products

# Only publish after the check step passed in CI
rover subgraph publish my-graph@production \
  --schema ./products/schema.graphql \
  --name products \
  --routing-url https://products.internal.mironsoft.de/graphql

# Fetch the fully composed supergraph for local gateway testing
rover graph fetch my-graph@production > supergraph.graphql

Der entscheidende Unterschied zwischen check und publish ist, dass check keinerlei Zustand verändert. Ein fehlgeschlagener Check blockiert lediglich den Merge, während ein erfolgreicher Publish die neue Schema-Version tatsächlich in das GraphQL Schema Registry einträgt und für die nächste Gateway-Komposition verfügbar macht. Diese Trennung erlaubt beliebig viele Checks während der Entwicklung eines Pull Requests, ohne die Registry mit unfertigen Zwischenständen zu verunreinigen.

5. GraphQL Hive: selbst gehostete Alternative

GraphQL Hive verfolgt denselben Grundgedanken wie Apollo Studio, ist aber vollständig Open Source und lässt sich vollständig selbst hosten, ein wichtiger Punkt für Teams, die aus Compliance- oder Kostengründen keine Schema-Daten an einen externen SaaS-Dienst senden dürfen. Die Hive-CLI übernimmt dieselbe Rolle wie Rover, mit äquivalenten Befehlen für Check, Publish und Composition-Abruf.

# Hive CLI equivalent workflow, self-hosted registry
hive schema:check \
  --registry.accessToken "$HIVE_TOKEN" \
  --service products \
  ./products/schema.graphql

hive schema:publish \
  --registry.accessToken "$HIVE_TOKEN" \
  --service products \
  --url https://products.internal.mironsoft.de/graphql \
  ./products/schema.graphql

Weil Hive selbst gehostet wird, liegt die Betriebsverantwortung beim eigenen Team: PostgreSQL-Datenbank, Redis für Caching und der Hive-Server selbst müssen bereitgestellt und überwacht werden. Im Gegenzug entfällt jede Abhängigkeit von externer SaaS-Verfügbarkeit, und die Kostenstruktur bleibt bei hohem Traffic-Volumen deutlich planbarer als bei nutzungsbasierten Apollo-Studio-Tarifen.

6. Schema Checks als Pflichtschritt in der CI-Pipeline

Ein GraphQL Schema Registry entfaltet seinen Wert erst, wenn Schema Checks als verpflichtender Status Check im Pull-Request-Workflow konfiguriert sind, nicht als optionaler manueller Schritt. Ein Merge muss technisch blockiert sein, solange der Check fehlschlägt. Das folgende Beispiel zeigt eine GitHub-Actions-Pipeline, die genau das umsetzt.

# .github/workflows/schema-check.yml
name: GraphQL Schema Check
on:
  pull_request:
    paths:
      - "services/products/schema.graphql"

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Rover CLI
        run: curl -sSL https://rover.apollo.dev/nix/latest | sh
      - name: Run schema check against registry
        env:
          APOLLO_KEY: ${{ secrets.APOLLO_KEY }}
        run: |
          rover subgraph check my-graph@production \
            --schema services/products/schema.graphql \
            --name products
      # Merge is blocked automatically because this job is a required status check

Wichtig ist, den Check-Job in den Branch-Protection-Regeln als "required" zu markieren. Ohne diese Konfiguration läuft der Check zwar durch, aber ein Merge ist trotzdem möglich, sobald der Reviewer die rote Statusmeldung übersieht. Ein GraphQL Schema Registry ist nur so verlässlich wie die Durchsetzung seiner Checks im Merge-Prozess.

7. Usage-basierte Breaking-Change-Erkennung

Der entscheidende Mehrwert eines GraphQL Schema Registry gegenüber einem einfachen statischen Schema-Diff ist die usage-basierte Prüfung. Beide, Apollo Studio und Hive, sammeln über eingebettete Reporting-Agenten kontinuierlich Daten darüber, welche Operationen, Felder und Argumente tatsächlich von Clients verwendet werden. Ein Schema Check vergleicht eine geplante Änderung nicht nur mit dem alten Schema-Text, sondern mit diesen realen Nutzungsdaten der letzten Tage oder Wochen.

Das bedeutet konkret: Ein Feld, das laut Schema als optional gilt, aber seit Monaten von keinem einzigen Client abgefragt wird, kann gefahrlos entfernt werden, der Check meldet keinen Fehler. Ein Feld hingegen, das täglich tausendfach abgefragt wird, löst bei geplanter Entfernung einen harten Fehler aus, selbst wenn es im Schema formal als @deprecated markiert war. Diese Unterscheidung zwischen theoretischer und tatsächlicher Nutzung ist der Grund, warum ein GraphQL Schema Registry Breaking Changes zuverlässiger erkennt als reines Code-Review.

{
  "checkResult": "FAILED",
  "changes": [
    {
      "type": "FIELD_REMOVED",
      "field": "Product.legacySku",
      "severity": "BREAKING",
      "affectedOperations": 3,
      "affectedClients": ["mobile-ios@2.4", "mobile-android@2.4"],
      "requestsLast7Days": 184320
    }
  ]
}

8. Versionierung und kontrollierte Deprecation

Weil GraphQL keine URL-Versionierung wie REST kennt, läuft die Evolution eines Schemas über die @deprecated-Direktive und eine geordnete Übergangsfrist. Ein GraphQL Schema Registry unterstützt diesen Prozess, indem es die Deprecation-Nutzung über die Zeit sichtbar macht: Sinkt die Anzahl der Requests auf ein deprecated Feld gegen null, ist der sichere Zeitpunkt für die endgültige Entfernung erreicht.

type Product @key(fields: "id") {
  id: ID!
  name: String!
  # Old field kept for backward compatibility during migration window
  legacySku: String @deprecated(reason: "Use `sku` instead, removal planned Q4 2026")
  sku: String!
}

In der Praxis empfiehlt sich eine feste Deprecation-Frist, etwa zwei bis drei Release-Zyklen, kombiniert mit automatisierten Reports aus dem GraphQL Schema Registry, die verantwortliche Client-Teams proaktiv informieren, sobald sie ein bald zu entfernendes Feld noch aktiv verwenden. Ohne dieses aktive Monitoring bleiben deprecated Felder häufig jahrelang im Schema, weil niemand den Überblick über die tatsächliche Restnutzung hat.

9. Apollo Studio und Hive im direkten Vergleich

Die Entscheidung zwischen Apollo Studio und Hive als GraphQL Schema Registry hängt weniger von der Funktionstiefe ab, beide decken Composition, Checks und Usage-Reporting vollständig ab, sondern von Betriebsmodell, Kostenstruktur und Datenschutz-Anforderungen des Teams.

Für Teams ohne strenge Compliance-Vorgaben ist Apollo Studio meist die schnellere Wahl, weil kein eigener Betrieb notwendig ist und das Onboarding in wenigen Minuten abgeschlossen ist. Für Teams mit Datenschutz-Anforderungen, etwa im regulierten E-Commerce-Umfeld, oder mit sehr hohem Request-Volumen, bei dem nutzungsbasierte SaaS-Kosten unwirtschaftlich werden, ist Hive als selbst gehostetes GraphQL Schema Registry die konsequentere Lösung.

10. Zusammenfassung

Ein GraphQL Schema Registry verschiebt die Verantwortung für Schema-Konsistenz von individuellem Code-Review zu einer automatisierten, zentralen Kontrollstelle. Composition-Fehler zwischen Subgraphs, Breaking Changes gegenüber echter Produktionsnutzung und schleichende Deprecation-Reste werden sichtbar, bevor sie Kunden erreichen. Apollo Studio bietet dafür den schnellsten Einstieg als verwalteter Dienst, Hive die volle Kontrolle über Daten und Infrastruktur als selbst gehostete Open-Source-Lösung.

Entscheidend ist in beiden Fällen dieselbe Disziplin: Schema Checks müssen als verpflichtender Status Check im Pull-Request-Workflow verankert sein, nicht als optionales Werkzeug für interessierte Entwickler. Erst diese Durchsetzung macht aus einem GraphQL Schema Registry einen echten Schutzmechanismus statt einer weiteren Dashboard-Ansicht, die niemand konsultiert, bevor der Fehler bereits live ist.

11. FAQ: GraphQL Schema Registry