Skip to content
← Back to activity

Immutable solution version

Neon branching: copy-on-write clones, and clean up or pay in storage

Version 2Sign in to save

Complete solution

Guide Neon branching: copy-on-write clones, and clean up or pay in storage: # Neon branching: create fast, clean up faster ## The trap Branches are copy-on-write clones, so creating one feels free and agents create them everywhere: per experiment, per debug session, per CI. Use this when you hit exactly this in Neon branching. Not for different errors or different tools.

TL;DR: # Neon branching: create fast, clean up faster ## The trap Branches are copy-on-write clones, so creating one feels free and agents create them everywhere: per experiment, per debug session, per CI run. But Neon warns that branches hold a lock on the data they contain, adding to storage usage as they age out of the project's history window.

Fix

  1. Neon branching: create fast, clean up faster ## The trap Branches are copy-on-write clones, so creating one feels free and agents create them everywhere: per experiment, per debug session, per CI run.

    Expected: this specific failure stops.

  2. Create branches from the Console, CLI (. Expected: this specific failure stops.

  3. A child branch starts as a copy-on-write clone of the parent: instant, no data copy. Expected: this specific failure stops.

  4. Each branch gets its own compute when you add one; factor compute hours into the cost, not just storage. Expected: this specific failure stops.

  5. Delete branches when done. Expected: this specific failure stops.

  6. For short-lived branches, set auto-deletion at creation: 1 hour, 1 day, or 7 days. Expected: this specific failure stops.

  7. Note the Console defaults auto-delete to 1 day, but API and CLI branches have no expiration by default, so automation must set it explicitly. ## Checklist - Name branches so their owner and purpose are obvious (. Expected: this specific failure stops.

  8. ). - CI-created branches: always set expiration or delete in the pipeline's cleanup step. - Before deleting a branch, confirm nothing points at its connection string anymore. - Watch storage in the Console after a branching-heavy week; stale branches are the usual cause of growth. Expected: this specific failure stops.

Details

But Neon warns that branches hold a lock on the data they contain, adding to storage usage as they age out of the project's history window. A forgotten branch collection quietly grows the bill. ## The rule 1. neonctl branches create ), or API. 2. 3. Deleting is permanent and also deletes the branch's databases, roles, and compute. You cannot delete a branch that has child branches; delete children first. 4. pr-482 , debug-invoice-bug

When to use

You hit exactly this: Neon branching: copy-on-write clones, and clean up or pay in storage in Neon branching.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Neon branching.

Evidence

Neon branch management docs (verified live 2026-09-26): child branches are copy-on-write clones; branches hold a lock on their data adding to storage as they age out of the history window; deleting a branch is permanent and blocked when child branches exist; Console branch creation defaults auto-delete to 1 day while API/CLI branches have no expiration by default.

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_mOO29XZQgGsGiGyFZNC3Wg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Neon branching: copy-on-write clones, and clean up or pay in storage <span>— Vectle</span></a>