The NeonDB Approach: Copy-on-Write Branching

NeonDB's branching creates a new branch in seconds, regardless of database size. When you create a branch, NeonDB doesn't immediately copy all data. Instead, it creates a new branch that shares the same underlying data blocks as the parent branch. Only when you modify data in the new branch does NeonDB create a copy of the modified blocks.

This is similar to how Git handles branches: when you create a new Git branch, it doesn't copy all files—it just creates a new pointer. Only when you modify files does Git track the differences.

How NeonDB Branching Works: The Technical Foundation

To understand how NeonDB branching works, we need to dive into PostgreSQL's Write-Ahead Log (WAL) and how NeonDB leverages it.

PostgreSQL's Write-Ahead Log (WAL)

PostgreSQL uses a Write-Ahead Log to ensure data durability and enable point-in-time recovery. Every transaction that modifies data writes its changes to the WAL before those changes are applied to the actual data files. The WAL is an append-only log that records all changes in the order they occurred.

Each entry in the WAL has a Log Sequence Number (LSN), which is a unique identifier that represents the position in the WAL stream. LSNs are monotonically increasing and allow PostgreSQL to track the exact state of the database at any point in time.

Log Sequence Numbers (LSN) and Branch Points

When you create a NeonDB branch, NeonDB records the current LSN of the parent branch. This LSN becomes the "branch point"—the exact moment in time from which the branch diverges. The branch initially shares all data blocks with the parent, but it has its own WAL stream starting from that LSN.

Here's what happens when you create a branch:

1. Capture LSN: NeonDB records the current LSN of the parent branch
2. Create Branch Metadata: A new branch record is created with the parent's LSN as the starting point
3. Share Data Blocks: The new branch initially references the same data blocks as the parent
4. Independent WAL: The branch gets its own WAL stream starting from the branch point LSN

Copy-on-Write: The Magic Behind Instant Branches

The copy-on-write mechanism is what makes branching instant. When you create a branch, no data is actually copied. Instead, both branches share the same underlying storage. Only when you modify data in the branch does NeonDB:

1. Identify Modified Blocks: Determine which data blocks need to be changed
2. Copy the Block: Create a new copy of the modified block
3. Update References: Point the branch to the new block instead of the shared one
4. Write to Branch WAL: Record the change in the branch's own WAL stream

This means if you have a 1TB database and create a branch, you don't need 1TB of additional storage immediately. You only need storage for the blocks you actually modify in the branch.

Example: Branching in Action

Let's say you have a production database with a users table containing 10 million rows. You create a branch to test a new feature:

Initial State:

• Production branch: LSN 1000000, 10M users
• Test branch: Created at LSN 1000000, shares all data blocks

After Modifying 1000 Rows in Test Branch:

• Production branch: Still at LSN 1000000, unchanged
• Test branch: Now at LSN 1001000, has its own copies of the 1000 modified rows

The test branch only uses additional storage for those 1000 modified rows, not for the entire 10 million rows.

How Branching Relates to PostgreSQL Transactions

Understanding how NeonDB branching relates to PostgreSQL transactions is crucial for effective database management. While both concepts deal with isolation and data consistency, they operate at different levels and serve different purposes.

Transactions: Short-Lived Atomic Operations

PostgreSQL transactions are the fundamental unit of work in a database. A transaction groups multiple SQL statements into a single atomic operation that either:

• Succeeds completely (COMMIT): All changes are permanently applied
• Fails completely (ROLLBACK): All changes are discarded

Transactions provide ACID guarantees:

• Atomicity: All operations in a transaction succeed or fail together
• Consistency: The database remains in a valid state
• Isolation: Concurrent transactions don't interfere with each other
• Durability: Committed changes survive system failures

Branches: Long-Lived Isolated Environments

Branches, on the other hand, are long-lived isolated copies of the entire database. They provide isolation at the database level rather than the transaction level. Changes made in a branch don't affect the parent branch, and vice versa.

The Relationship: Branches Contain Transactions

The key relationship is that branches contain transactions. When you work in a branch, you're still using PostgreSQL's transaction model. Each transaction within a branch follows the same ACID guarantees as transactions in the parent branch. The difference is that transactions in a branch only affect that branch's data.

Transaction Isolation Levels Still Apply

PostgreSQL's transaction isolation levels (READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE) work exactly the same within a branch as they do in the parent. The branch itself provides an additional layer of isolation above transaction isolation.

Example: Transactions Within Branches

Consider this scenario:

Production Branch:

BEGIN;
UPDATE users SET status = 'active' WHERE id = 1;
COMMIT;

This transaction updates a user in production. The change is recorded in production's WAL and becomes permanent.

Test Branch (created before the production update):

BEGIN;
UPDATE users SET status = 'inactive' WHERE id = 1;
COMMIT;

This transaction updates the same user in the test branch. The change is recorded in the test branch's WAL and only affects the test branch. The production branch remains unchanged.

Both transactions follow PostgreSQL's ACID guarantees, but they operate in completely isolated environments.

WAL and LSN: The Bridge Between Branches and Transactions

The Write-Ahead Log and Log Sequence Numbers are what make branching possible and connect it to PostgreSQL's transaction model.

How WAL Enables Branching

Every transaction writes to the WAL before modifying data files. When you create a branch, NeonDB:

1. Records the Parent LSN: Captures the exact LSN where the branch diverges
2. Creates Branch WAL: Starts a new WAL stream for the branch from that LSN
3. Tracks Changes: All transactions in the branch write to the branch's WAL

This means NeonDB can reconstruct the exact state of any branch at any point in time by replaying WAL entries from the branch point forward.

LSN as a Branch Point

The LSN serves as a "branch point" similar to a Git commit hash. Just as a Git branch points to a specific commit, a NeonDB branch points to a specific LSN. This allows NeonDB to:

• Track Divergence: Know exactly when branches diverged
• Enable Point-in-Time Recovery: Restore to any LSN within a branch
• Support Branch Merging: Potentially merge changes between branches (though this is complex and not always supported)

Transaction Boundaries and Branch Isolation

When a transaction commits in a branch, it writes a commit record to that branch's WAL. This commit record includes the transaction's final LSN. The branch's LSN advances, but the parent branch's LSN remains unchanged.

This creates a clear separation: transactions in different branches can have the same logical operations but different LSNs, ensuring complete isolation.

Use Cases: When to Use Branching vs. Transactions

Understanding when to use branching versus transactions helps you make better architectural decisions.

Use Transactions For:

• Atomic Operations: Ensuring multiple related changes succeed or fail together
• Data Consistency: Maintaining referential integrity across related tables
• Concurrency Control: Managing simultaneous access to the same data
• Error Recovery: Rolling back changes when errors occur

Use Branching For:

• Testing Schema Changes: Trying out migrations without affecting production
• Feature Development: Developing features that require database changes
• Data Analysis: Running analytical queries without impacting production performance
• Disaster Recovery Testing: Testing backup and recovery procedures
• Performance Testing: Testing query performance with production-like data volumes

Combining Both: Best Practices

The most effective approach combines both:

1. Create a Branch: For testing a new feature or migration
2. Use Transactions: Within the branch for all data modifications
3. Test Thoroughly: Run your application and tests against the branch
4. Delete or Merge: When done, either delete the branch or merge changes back

Technical Deep Dive: Storage and Performance Implications

Understanding the storage and performance characteristics of branching helps you use it effectively.

Storage Efficiency

Because branches use copy-on-write, storage usage is proportional to the amount of data you modify, not the total database size. This makes branching extremely storage-efficient for most use cases.

Example Storage Calculation:

• Database size: 500GB
• Branch created: 0GB additional storage (shares all blocks)
• After modifying 1GB of data: 1GB additional storage
• After modifying 10GB of data: 10GB additional storage

This is dramatically more efficient than full database copying, which would require 500GB for each copy.

Performance Characteristics

Branching has minimal performance impact on the parent branch:

• Read Operations: Reading from a branch is as fast as reading from the parent (until blocks diverge)
• Write Operations: Writing to a branch only affects that branch's performance
• Parent Impact: Creating or using branches doesn't slow down the parent branch

However, there are some considerations:

• Shared Blocks: Reading shared blocks is fast, but modifying them triggers copy-on-write
• WAL Growth: Each branch maintains its own WAL, so WAL storage grows with branch activity
• Compute Resources: Each branch can have its own compute resources, allowing independent scaling

Branch Limits and Resource Management

NeonDB has branch limits based on your plan:

• Free/Launch Plan: 10 branches per project
• Scale Plan: 25 branches per project

These limits exist because each branch consumes some resources (metadata, WAL storage, compute when active). It's important to clean up unused branches to stay within limits.

Practical Workflow: Branching in Development

Here's a practical workflow for using branching in your development process:

Step 1: Create a Branch from Production

# Using Neon CLI
neon branches create --name test-migration-v2 --parent main

# Or using the API/scripts
./scripts/pg/test/create-test-branch.sh

This creates a branch instantly, regardless of database size.

Step 2: Get the Branch Connection String

Each branch has its own unique PostgreSQL connection string. Use this in your application configuration to connect to the branch instead of production.

Step 3: Test Your Changes

Run your migrations, test your application, and verify everything works correctly. All changes are isolated to the branch.

Step 4: Clean Up

When done testing, delete the branch:

neon branches delete test-migration-v2

This frees up resources and keeps you within branch limits.

Advanced Concepts: Branch Merging and Point-in-Time Recovery

While NeonDB primarily supports creating and deleting branches, understanding advanced concepts helps you use branching more effectively.

Point-in-Time Recovery Within Branches

Because branches track LSNs, you can perform point-in-time recovery within a branch. If you make a mistake in a branch, you can restore it to a previous LSN, effectively "undoing" changes.

This is similar to Git's ability to reset to a previous commit, but at the database level.

Branch Lifecycle Management

Effective branch management involves:

1. Naming Conventions: Use descriptive names like test-feature-x or migration-v2-test
2. Regular Cleanup: Delete branches when no longer needed
3. Documentation: Document what each branch is for
4. Monitoring: Track branch count and storage usage

Comparison: Branching vs. Other Isolation Mechanisms

Understanding how branching compares to other PostgreSQL isolation features helps you choose the right tool for each situation.

Branching vs. Transaction Isolation

Branching vs. Database Replication

Replication creates a continuously synchronized copy of a database. Branching creates a point-in-time snapshot that diverges independently.

• Replication: Changes in primary automatically propagate to replica
• Branching: Changes in parent don't affect branch (and vice versa)

Branching vs. Database Snapshots

Traditional database snapshots are similar to branches but typically:

• Take longer to create (full copy required)
• Consume full database size in storage
• Can't be easily deleted or managed
• Don't support independent WAL streams

NeonDB branching is essentially "smart snapshots" that leverage copy-on-write for efficiency.

Best Practices for Database Branching

To get the most out of NeonDB branching, follow these best practices:

1. Use Branches for Testing, Not Production Workloads

Branches are designed for testing and development. Don't use them for production workloads or long-term data storage.

2. Clean Up Regularly

Delete branches when you're done with them. This keeps you within branch limits and reduces storage costs.

3. Use Descriptive Names

Name branches clearly so you know what each one is for:

• ✅ Good: test-user-auth-migration-v2
• ❌ Bad: test1, branch-abc

4. Monitor Storage Usage

While branches are storage-efficient, modifying large amounts of data in a branch will consume storage. Monitor usage to avoid surprises.

5. Combine with Transactions

Always use transactions within branches for data modifications. This ensures data consistency and allows rollback if needed.

6. Test Branch Deletion

Before relying on branches for critical testing, verify that you can create and delete branches quickly. This ensures the workflow fits your needs.

Conclusion: The Future of Database Development

NeonDB's branching feature represents a fundamental shift in how we think about database development and testing. By leveraging PostgreSQL's WAL and LSN system, NeonDB brings Git-like version control to the database layer, making it possible to test production-like data safely and efficiently.

Understanding how branching relates to PostgreSQL transactions—that branches contain transactions, that both provide isolation but at different levels, and that WAL/LSN is the bridge between them—is crucial for effective database management in 2025 and beyond.

As databases continue to grow in size and complexity, features like branching become essential for maintaining development velocity while ensuring data safety. The ability to create instant, isolated database copies for testing enables faster iteration, safer deployments, and more confident development practices.

Whether you're testing a new migration, developing a feature that requires schema changes, or analyzing production data safely, NeonDB branching provides the isolation you need with the efficiency you want. Combined with PostgreSQL's robust transaction model, it creates a powerful foundation for modern database operations.

Book a Discovery Call