Starting With Neon Branching

Technical Content Writer / Developer Advocate. When everything is considered, structure + order equals enjoyment. Learn more about Paul ↬

Front-end & UX tips delivered weekly. Trusted by over 200,000 individuals.

This piece is generously sponsored by our good friends at Neon Tech, who are dedicated to developing a cloud-native database service for every developer. We appreciate your support!

Branching for code modifications is a proven method in software development, but shouldn't database development follow the same principle? With Neon, you can alter your database without impacting the production environment. If you're accustomed to Git, you'll find this process familiar.

To illustrate how branching operates, I'll use a standard "contact us" form and implement a "hypothetical" modification.

The form currently submits the following fields.

The form operates by transmitting the form data via a client-side request to a Vercel Edge Function, which then securely links to a Neon Serverless Postgres database.

Here's a sample of the client-side fetch request.

And here's a code sample of the Edge Function that extracts the form values from the request body and INSERTs them into a table named contact_us.

The modification I plan to make will occur "behind the scenes". In addition to the user's input, I also aim to record and store the geographical location of the form submission.

To achieve this, I'll utilize Vercel’s geolocation helper function from the @vercel/edge package. The modifications I'll implement will impact both the Edge Function and the database table schema.

I don't want to alter the table schema on the live production database until I've confirmed everything functions as expected. Thankfully, branching allows me to do this.

Here's how I would implement a change of this nature.

Neon features an impressive browser console (just look at it! 😍), and all database modifications can be executed and tested in the browser, eliminating the need for a dull terminal window!

Selecting “Create branch” will navigate you to the next screen where I'll set up the new branch.

These are the branch configuration options. For this demonstration, I'll be branching using the Head option. There are several reasons why branching from a specific Time or LSN might be more appropriate. For instance, when performing a backup or troubleshooting an issue and wanting to identify "when things went wrong".

To verify the changes I'll be implementing in the Edge Function (which I'll explain shortly), I'll need to ensure I'm inserting data correctly. By creating a compute endpoint with the branch, I can do this without risking damage to the production database!

A button that will generate the new branch

Selecting “Create the branch” will navigate you to the next screen.

This is where things become incredibly exciting!

Using the convenient "copy" button, I can duplicate the new connection string and add it to my .env file.

I've found this extremely useful when managing multiple branches simultaneously. That single comment above the connection string helps me identify which branch it corresponds to in the Neon console.

Before proceeding further, I like to confirm I'm viewing the correct branch in the Neon console. If you've followed the steps above, you should be able to see your new branch when selecting “Branches” from the navigation.

Selecting the branch name will navigate you to the next screen.

Before making any code modifications, I prepare the database and test everything by running SQL commands directly in Neon’s SQL Editor.

To determine the current schema for the contact_us table ...