Powering next gen AI apps with Postgres 🚀 Learn More
Guides/Neon features/Branching

Branching — Testing queries

Create a Neon branch to test queries before running them in production

Complex queries that modify data or alter schemas have the potential to be destructive. It is advisable to test these types of queries before running them in production. On other database systems, testing potentially destructive queries can be time and resource intensive. For example, testing may involve setting up a separate database instance and replicating data. With Neon, you can instantly create a database branch with a full copy-on-write clone of your production data in just a few clicks. When you finish testing, you can remove the branch just as easily.

This guide walks you through creating a branch of your production data, testing a potentially destructive query, and deleting the branch when you are finished.

  1. Create a test branch
  2. Test your query
  3. Delete the test branch

For the purpose of this guide, let's assume you have a database in Neon with the following table and data:

Create a test branch

  1. In the Neon Console, select your project.
  2. Select Branches.
  3. Click New Branch to open the branch creation dialog.
  4. Enter a name for the branch. This guide uses the name my_test_branch.
  5. Select a parent branch. Select the branch defined as your primary branch.
  6. Select Head to create a branch with data up to the current point in time (the default).
  7. Leave Create compute endpoint selected. This creates the branch with its own dedicated compute instance.
  8. Click Create Branch to create your branch.

You can also create a test branch using the Neon CLI or Neon API.


Test your query

Navigate to the SQL Editor, select the test branch, and run your query. For example, perhaps you are deleting blog posts from your database for a certain author published before a certain date, and you want to make sure the query only removes the intended records.

Next, inspect the data to ensure the intended records were deleted, while others remained unaffected. This query allows you to quickly see if the number of records matches your expectations:

Before the DELETE query, there were 5 records. If the query ran correctly, this should now show 4.

Delete the test branch

When you finish testing your query, you can delete the test branch:

  1. In the Neon Console, select a project.
  2. Select Branches.
  3. Select the test branch from the table.
  4. On the branch page, click the More drop-down menu and select Delete.
  5. On the confirmation dialog, click Delete.

You can also delete a branch using the Neon CLI or Neon API.

Edit this page
Was this page helpful?