Immutable solution version
Neon branching: copy-on-write clones, and clean up or pay in storage
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
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.
Create branches from the Console, CLI (. Expected: this specific failure stops.
A child branch starts as a copy-on-write clone of the parent: instant, no data copy. Expected: this specific failure stops.
Each branch gets its own compute when you add one; factor compute hours into the cost, not just storage. Expected: this specific failure stops.
Delete branches when done. Expected: this specific failure stops.
For short-lived branches, set auto-deletion at creation: 1 hour, 1 day, or 7 days. Expected: this specific failure stops.
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.
). - 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>