neondatabase/neon-postgres-branches

Zuerst: Nutze das übergeordnete neon-Skill für eine Neon-Übersicht, Einstiegshilfe, Best Practices und mehr.

Falls das neon-Skill nicht installiert ist, hole es von https://neon.com/docs/ai/skills/neon/SKILL.md oder installiere es mit:

npx skills add neondatabase/agent-skills --skill neon

Lakebase Postgres Branching

Ergebnis: Ein erstellter Neon-Branch – oder ein klarer, umsetzbarer nächster Schritt, falls die Erstellung nicht möglich ist. Wähle den korrekten Branch-Typ und führe die Branch-Erstellung mit der CLI (oder MCP, wenn die CLI nicht nutzbar ist) aus.

• Normaler Branch für realistische Migrationstests und Query-Tests mit echten Daten.
• Schema-only Branch (Beta) für Workflows mit sensiblen Daten, bei denen die Struktur ohne Zeilenkopien benötigt wird.

Entscheidung Branch-Typ

Wende diese Entscheidungsregel zuerst an:

1. Wenn der Benutzer komplexe Migrationen, Performance oder Verhalten mit produktionsähnlichen Daten testen möchte, wähle einen normalen Branch.
2. Wenn der Benutzer das Kopieren sensibler Daten vermeiden muss, wähle einen Schema-only Branch.

Wenn die Anfrage mehrdeutig ist, stelle eine klärende Frage: „Benötigst du realistische Daten zum Testen oder nur die Schema-Struktur, weil die Daten sensibel sind?“

Tool-Auswahl: CLI oder MCP

Unterstütze sowohl die Neon-CLI als auch den Neon-MCP-Server, standardmäßig jedoch die CLI. Verwende MCP nur, wenn die CLI nicht verfügbar oder blockiert ist, nicht authentifiziert werden kann, oder der Benutzer explizit nach MCP fragt.

• CLI-Link: https://neon.com/docs/cli/quickstart.md
• MCP-Link: https://neon.com/docs/ai/neon-mcp-server.md

Auswahlreihenfolge

1. Prüfe zuerst die CLI:
   • Führe neon --version aus, um zu bestätigen, dass die CLI installiert ist.
   • Führe neon projects list aus, um Authentifizierung/Kontext zu bestätigen.
2. Wenn die CLI fehlt, leite die Installation via Quickstart an.
3. Wenn die CLI installiert, aber nicht authentifiziert ist, führe den Benutzer durch neon auth (oder API-Key-Auth) und fahre dann fort.
4. Wechsle zu MCP, wenn die CLI nicht verwendet werden kann – kein CLI-Zugriff in der Umgebung, Ausführung blockiert oder Authentifizierung nicht möglich – oder wenn der Benutzer explizit nach MCP fragt. Bestätige, dass die Neon-MCP-Tools verfügbar und authentifiziert sind (z. B. durch Auflisten von Projekten), und folge dann dem MCP-Branch-Ablauf unten.
5. Wenn keiner der Wege erfolgreich ist, verwende die Neon REST API:
   • https://neon.com/docs/guides/branching-neon-api.md

MCP-Branch-Ablauf

1. Wähle normal vs. schema-only basierend auf Datensensibilität und Migrations-Testzielen.
2. Verwende Branch-Tools (z. B. create_branch), um den Branch zu erstellen.
3. Validiere mit Lese-Tools (z. B. describe_branch).
4. Für Migrations-Workflows bevorzuge Branch-basierte Migrationsabläufe, bevor du auf main übernimmst.

Erstelle einen Normalen Branch (Bevorzugt für Echt-Daten-Migrationstests)

Verwende dies, wenn der Benutzer realistische Testbedingungen benötigt. Echte produktionsähnliche Daten können Randfälle aufdecken, die deine Seed- oder Datenmigrationsskripte übersehen, und helfen, Migrationsprobleme vor dem Live-Gang zu erkennen.

Link: https://neon.com/docs/introduction/branching.md

Schritte

1. Kläre zuerst den Tool-Pfad (siehe Auswahlreihenfolge): Überprüfe die CLI mit neon --version und falle nur auf MCP zurück, wenn die CLI nicht nutzbar ist.

2. Stelle sicher, dass der Projektkontext gesetzt ist (neon set-context --project-id <your-project-id>) oder füge --project-id an Befehle an.

3. Erstelle den Branch:

   neon branches create \
     --name <branch-name> \
     --parent <parent-branch-id-or-name> \
     --expires-at 2026-12-15T18:02:16Z
   

4. Optional: Rufe einen Verbindungsstring für den neuen Branch ab:

   neon connection-string <branch-name>
   

Erstelle einen Schema-Only Branch (Beta, Sensible Daten)

Verwende dies, wenn Benutzer keine Produktionszeilen in den Testbranch kopieren dürfen.

Link: https://neon.com/docs/guides/branching-schema-only.md

Schritte

1. Kläre zuerst den Tool-Pfad (siehe Auswahlreihenfolge): Überprüfe die CLI mit neon --version und falle nur auf MCP zurück, wenn die CLI nicht nutzbar ist.

2. Erstelle den Schema-only Branch:

   neon branches create \
     --name <schema-only-branch-name> \
     --parent <parent-branch-id-or-name> \
     --schema-only \
     --expires-at 2026-12-15T18:02:16Z
   

   Falls mehrere Projekte existieren, füge --project-id hinzu:

   neon branches create \
     --name <schema-only-branch-name> \
     --parent <parent-branch-id-or-name> \
     --schema-only \
     --project-id <your-project-id> \
     --expires-at 2026-12-15T18:02:16Z
   

Beta-Support-Hinweis (Verpflichtend)

Schema-only Branching befindet sich in der Beta-Phase. Wenn Benutzer von unerwartetem Verhalten, Fehlern oder fehlenden Funktionen berichten:

1. Bitte sie, Feedback in der Neon Console zu teilen:
   • https://console.neon.tech/app/projects?modal=feedback
2. Empfehle, ein Support-Gespräch im Neon Discord zu eröffnen:
   • https://discord.gg/92vNTzKDGp

Zurücksetzen vom Parent

Verwende dies, wenn ein Child-Branch abgewichen ist und der Benutzer eine saubere Aktualisierung vom neuesten Schema und Daten des Parent-Branches wünscht.

Link: https://neon.com/docs/guides/reset-from-parent.md

Was es bewirkt

• Ersetzt vollständig das Schema und die Daten des Child-Branches mit dem aktuellen Stand des Parent.
• Führt kein Merge durch; lokale Änderungen auf dem Child-Branch gehen verloren.
• Behält die gleichen Verbindungsdetails, aber aktive Verbindungen werden während des Resets kurz unterbrochen.

Wann es zu empfehlen ist

• Entwicklungs- oder Staging-Branch liegt zu weit hinter der Produktion zurück.
• Benutzer möchte ein neues Feature von einem sauberen, mit dem Parent synchronen Stand beginnen.
• Team möchte Staging von der Produktion aktualisieren, um konsistente Testbaselines zu erhalten.

Harte Einschränkungen und Blocker

• Nur Child-Branches können zurückgesetzt werden (Root-Branches und Schema-only Root-Branches können nicht vom Parent zurückgesetzt werden).
• Wenn der Ziel-Branch eigene Child-Branches hat, ist das Zurücksetzen blockiert, bis diese entfernt werden.
• Nachdem ein Parent-Branch aus einem Snapshot wiederhergestellt wurde, kann das Zurücksetzen vom Parent bis zu 24 Stunden lang nicht verfügbar sein.
• Das Zurücksetzen vom Parent verwendet immer den aktuellen Parent-Zustand; für Point-in-Time Recovery verwende die Instant-Restore-Funktion.

CLI-Nutzung

neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name>

Falls der Projektkontext noch nicht gesetzt ist, füge die Projekt-ID hinzu:

neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>

--preserve-under-name behält den Zustand vor dem Reset als Backup-Branch für ein Rollback, fügt aber einen zusätzlichen Branch zur späteren Bereinigung hinzu.

Optionaler Kontext-Setup, um Wiederholungen von --project-id zu vermeiden:

neon set-context --project-id <project-id>

Console- und API-Nutzung

• Console: Öffne den Ziel-Child-Branch und wähle dann Vom Parent zurücksetzen aus Aktionen.
• API: Verwende den Restore-Endpunkt für den Branch und setze source_branch_id auf die Parent-Branch-ID.

Hinweise und Einschränkungen

• Schema-only Branches dienen nur dem Struktur-Klonen und der Kontrolle sensibler/complianter Daten.
• Schema-only Branches sind unabhängige Root-Branches (kein Parent-Branch und keine gemeinsame Historie), daher ist ein Zurücksetzen vom Parent nicht anwendbar.
• Für Migrationstests, die von realen Zeilenformen, -volumen und Randfällen abhängen, bevorzuge normale Branches.
• Root-Branch-Kontingente und Speicherlimits pro Branch können die Anzahl der erstellbaren Schema-only Branches begrenzen.
• Wenn der Benutzer unsicher ist, lautet die Standardempfehlung:
  • Normaler Branch für die Migrationsvalidierung.
  • Schema-only Branch für Compliance- und Datenschutzanforderungen.

Nützliche Workflow-Muster

Wenn der Benutzer nach Prozessempfehlungen fragt (nicht nur nach einem einzelnen Befehl), schlage diese vor:

• Ein Branch pro PR: Branch erstellen, wenn PR geöffnet wird, löschen, wenn er gemergt/geschlossen wird, Migrationstests isoliert halten.
• Ein Branch pro Testlauf: Branch zu Pipeline-Start erstellen, Migrationen/Tests ausführen, am Ende löschen für deterministische CI.
• Ein Branch pro Entwickler: Isolierte Entwicklungsumgebungen mit produktionsähnlicher Struktur; Team-Kollisionen bei gemeinsamen Testdaten vermeiden.
• PII-bewusstes Branching: Wenn die Produktion sensible Daten enthält, leite Entwicklungs-/PR-Branches von einem anonymisierten Branch ab oder verwende Schema-only Branches.
• Ephemere Lebenszyklus-Hygiene: Setze ein Branch-Ablaufdatum und automatisiere die Bereinigung, damit alte Branches keine vermeidbaren Speicher-/Kosten verursachen.

Aufforderung zur Aktualisierung der Umgebung nach der Erstellung

Nach der Branch-Erstellung frage den Benutzer, ob er die lokalen Umgebungsvariablen aktualisieren möchte, um auf den neuen Branch zu verweisen.

• Frage: „Möchtest du, dass ich deine .env DATABASE_URL auf diesen neuen Branch-Verbindungsstring aktualisiere?“
• Falls ja, schreibe den neuen Branch-Verbindungsstring in die angeforderte Env-Datei/den Env-Key.
• Falls nein, lasse die Anmeldedaten unverändert und teile den Verbindungsstring zur manuellen Nutzung mit.
• Überschreibe niemals einen vorhandenen Env-Key ohne explizite Bestätigung.

Neon Infrastructure as Code (neon.ts)

Über die imperative Branch-Erstellung (CLI / MCP / API oben) hinaus kannst du programmgesteuert festlegen, welche Konfiguration neue Branches erhalten – deklarativ in neon.ts, Neons Datei für Infrastructure as Code (siehe das neon-Skill für die vollständige Referenz). Die branch-Eigenschaft ist eine Funktion des ausgewerteten Branches, die dessen Einstellungen zurückgibt, sodass jeder aus deinem Projekt erstellte Branch einen konsistenten Lebenszyklus und ein konsistentes Compute-Profil ohne pro-Branch-Flags erhält.

npm i @neon/config

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  branch: (branch) => {
    if (branch.exists) return {}; // bestehende Branches niemals angleichen
    if (branch.isDefault) return { protected: true };
    if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
      return {
        parent: "main",
        ttl: "7d", // ephemer: automatisch 7 Tage nach Erstellung ablaufen (max. 30d)
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // auf Null skalieren
            autoscalingLimitMaxCu: 1, // Wegwerf-Branches günstig halten
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

Der Closure erhält einen schreibgeschützten Deskriptor des Ziel-Branches – name, exists, isDefault, parentId und mehr – und gibt die anzuwendende Abstimmung zurück: parent, ttl (Auto-Ablauf), protected und postgres.computeSettings. Dies ist das deklarative Gegenstück zu den Mustern Ephemere Lebenszyklus-Hygiene und pro-PR / pro-Test oben: Statt sich bei jedem neon branches create an --expires-at zu erinnern, leben TTL und Compute-Profil im Versionskontrollsystem und werden auf jeden passenden Branch angewendet.

Da neon checkout diese Richtlinie anwendet, wenn es einen Branch erstellt, kommt ein neuer preview/*- oder dev-*-Branch bereits mit Ablauf und Null-Skalierung hoch. Das Auschecken eines bestehenden Branches gleicht ihn nicht an – führe neon deploy (Alias für neon config apply) aus, um Änderungen auf einen bereits existierenden Branch anzuwenden.

Branching in CI/CD

Häufige CI/CD-Anwendungsfälle für Neon-Branches:

• Per-PR Preview Deployments: Branch bei PR-Öffnung erstellen, Preview dagegen deployen, bei Schließung löschen. Jeder PR erhält einen isolierten Datenbank-Branch. Das Einfügen des Branch-DATABASE_URL in die bereitgestellte App ist hosting-anbieterspezifisch – siehe preview-branches-with-cloudflare, preview-branches-with-vercel oder preview-branches-with-fly für getestete Muster.
• Migrationstests in CI: Führe riskante Schemaänderungen gegen einen Branch mit produktionsähnlichen Daten aus, bevor du mergest.
• Schema-Diff-Sichtbarkeit: Verwende die schema-diff GitHub Action, um automatisch einen DB-Ebenen-Diff als Kommentar auf dem PR zu hinterlegen.

Beispiele

Beispiel 1: Migrationstest mit realistischen Daten

Benutzereingabe: „Ich muss eine riskante Migration gegen produktionsähnliche Daten testen.“

Agent-Ausgabe-Form:

1. Empfehle einen normalen Branch und erkläre warum.
2. Teile den Docs-Link: https://neon.com/docs/introduction/branching
3. Prüfe zuerst den Tool-Pfad (CLI mit neon --version; MCP nur, wenn die CLI nicht nutzbar ist).
4. Stelle Befehle bereit:
   • neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z
   • neon connection-string migration-test

Beispiel 2: Entwicklungsworkflow mit sensiblen Daten

Benutzereingabe: „Wir können aufgrund von Compliance-Anforderungen keine Produktionsdaten kopieren.“

Agent-Ausgabe-Form:

1. Empfehle einen Schema-only Branch und erkläre warum.
2. Teile den Docs-Link: https://neon.com/docs/guides/branching-schema-only
3. Prüfe zuerst den Tool-Pfad (CLI mit neon --version; MCP nur, wenn die CLI nicht nutzbar ist).
4. Stelle den Befehl bereit:
   • neon branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z
5. Erwähne den Beta-Support-Pfad:
   • https://console.neon.tech/app/projects?modal=feedback
   • https://discord.gg/92vNTzKDGp

Weiterführendes

• https://neon.com/docs/guides/branch-expiration.md
• https://neon.com/docs/guides/neon-github-integration.md
• https://neon.com/docs/ai/neon-mcp-server.md
• https://neon.com/branching