Branches for Database Changes Without the Risk

Developers have long used version-control branching to isolate code changes, but database schema changes are often handled differently — usually with direct alterations to a live database and a prayer that nothing breaks. Neon brings the same branching model that Git popularized to Postgres, letting you create an isolated copy of your database, test schema changes and queries against real data, and only promote those changes to production when you're confident they work.

The workflow feels familiar if you've used Git: create a branch from main, make your changes, verify everything works, then apply those changes back to the production branch. Here's how that plays out with a practical example involving a "contact us" form and the addition of geolocation data.

The Scenario

Consider a form that submits the following fields to a Vercel Edge Function, which then inserts the data into a Neon Serverless Postgres database table named contact_us:

  • name
  • email_address
  • company_website
  • company_size
  • message

The change requires capturing the geographical location of where the form was submitted — information available via Vercel's geolocation helper function from the @vercel/edge package. This means two things need to change: the Edge Function code and the contact_us table schema. The schema change is where branching becomes invaluable, because altering the production table before testing would be risky.

Creating a Branch in Neon

In the Neon console, creating a branch starts from the project dashboard. For a project named branching-sample with a primary branch called main, you click the "Create branch" button and configure the new branch with these options:

  1. Branch name: Match it to your Git branch name for easy cross-referencing.
  2. Parent branch: Usually main, but you can branch off any existing branch.
  3. Data source: Three options determine what data the branch starts with:
    • Head: Data up to the current point in time.
    • Time: Data up to a specified date and time.
    • LSN: Data up to a specified Log Sequence Number.
    The Head option is typical for daily development. Branching from a specific point in time or LSN is useful for debugging or when you need a snapshot from a particular moment.
  4. Compute endpoint: Create one with the branch so you can test inserts and queries without touching production.

Once created, the console presents a new connection string for an entirely separate database that contains real data — identical to the production database at the point you branched from. Any data you push to this branch will never appear in production.

Point Your Local Environment at the Branch

Copy the branch connection string and add it to your .env file. A practical approach is to comment out the production DATABASE_URL and add a new variable with the same name, annotated with a comment identifying which branch it belongs to:

This convention helps when juggling multiple branches simultaneously — one glance at the comment tells you which Neon branch and Git branch the connection string corresponds to.

Verifying You're on the Right Branch

In the Neon console, the "Branches" navigation section shows all branches. Selecting your newly created branch focuses the console on it. The SQL Editor also lets you switch between branches, which is handy for running queries against different databases without leaving the browser.

Altering the Table Schema on the Branch

Schema changes can be prepared and tested entirely in Neon's browser-based SQL Editor before any code changes are made.

Check the Current Schema

The "Tables" section shows the existing schema for the contact_us table, including which branch you're currently viewing.

Run the ALTER Command

To add the two new geolocation columns — country_code and city — execute an ALTER TABLE statement:

ALTER TABLE contact_us ADD COLUMN country_code VARCHAR, ADD COLUMN city VARCHAR;

Return to "Tables" to confirm both columns appear in the schema for the contact_us table.

Test With Sample Data

Back in the SQL Editor, run a quick INSERT statement that includes values for the new columns. The result confirms the schema is valid. Follow up with SELECT * FROM contact_us to see the inserted row with the new data intact.

The test data lives only on the branch — it never pollutes the production environment. Run as many trial inserts as you need without consequence.

Applying Changes to Production

Once the schema change is verified, switch back to the main branch in the console and run the same ALTER TABLE command there. This applies the change to the production database.

Double-check the production schema via the "Tables" view. When everything looks correct, you can safely delete the development branch (feat/geolocation-data in this example) and move on to updating the application code.

Updating the Edge Function

The geolocation values come from the incoming request to the Edge Function. To access them, install the @vercel/edge package first:

npm install @vercel/edge

The Edge Function code then imports the geolocation helper and extracts country and city from the request. One caveat: when testing locally, both values will be null because Vercel's geolocation function only returns real values once the Edge Function is deployed.

The branching workflow means the entire database portion of this change — schema alteration and data verification — happened in a safe, isolated environment. Whether you run one test insert or a hundred, the production database remains untouched until you explicitly run the ALTER command on the main branch. That separation between experimentation and production is what makes Neon branching a practical tool for database development.