> This page location: Postgres > Branching > Branching workflow primer > Full Neon documentation index: https://neon.com/docs/llms.txt > > Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md > Summary: Neon database branching creates isolated Postgres branches in ~1 second, each with its own connection string and a full copy of the parent's schema and data. Use this page when setting up per-developer, per-PR preview, or CI/CD test database environments via the Neon CLI or GitHub Actions. Available GitHub Actions include create-branch, delete-branch, reset-branch, and schema-diff; schema-only branching and automatic branch expiration are also covered. # Database branching workflow primer An introduction to integrating Postgres branching into your development workflow Last updated: 2026-09-01 With Neon, you can work with your data just like you work with your code. The key is Neon's database [branching](https://neon.com/docs/concepts/branch-your-backend) feature, which lets you instantly create branches of your data that you can include in your workflow, as many branches as you need. Neon branches are: - **Isolated**: changes made to a branch don't affect its parent. - **Fast to create**: creating a branch takes ~1 second, regardless of the size of your database. - **Ready to use**: branches will have the parent branch's schema and all its data (you can also include data up to a certain point in time). If you're working with sensitive data, Neon also supports a [schema-only branching](https://neon.com/docs/guides/branching-schema-only) option. Every Neon branch has a unique Postgres connection string, so they're completely isolated from one another. ```bash # Branch 1 postgresql://database_name_owner:AbC123dEf@ep-shiny-cell-a5y2zuu0.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require # Branch 2 postgresql://database_name_owner:AbC123dEf@ep-hidden-hall-a5x58cuv.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require ``` You can create all of your branches from the default branch, or set up a dedicated branch that you use as a base. The first approach is simpler, while the second provides greater data isolation. ![database workflow A B](https://neon.com/docs/get-started/database_workflow_AB.jpg) ## Create branch methods You can use either the Neon CLI or GitHub actions to incorporate branching into your workflow. ### Neon CLI Using the [Neon CLI](https://neon.com/docs/cli), you can create branches without leaving your editor or automate branch creation in your CI/CD pipeline. And here are the key CLI actions you can use: ```bash # Create branch neon branches create [options] # Get Connection string neon connection-string [branch] [options] # Delete branch neon branches delete [options] ``` For more information, see: - [Branching with the Neon CLI](https://neon.com/docs/guides/branching-neon-cli): Learn about branching with the Neon CLI - [Neon CLI Reference](https://neon.com/docs/cli): Reference for all commands in the Neon CLI ### GitHub Actions If you're using GitHub Actions for your CI workflows, Neon provides GitHub Actions for [creating](https://neon.com/docs/guides/branching-github-actions#create-branch-action), [deleting](https://neon.com/docs/guides/branching-github-actions#delete-branch-action), and [resetting](https://neon.com/docs/guides/branching-github-actions#reset-from-parent-action) branches, and there's also a [schema diff action](https://neon.com/docs/guides/branching-github-actions#schema-diff-action). **Create branch** Here is an example of what a create branch action might look like: ```yaml name: Create Neon Branch with GitHub Actions Demo run-name: Create a Neon Branch 🚀 jobs: Create-Neon-Branch: uses: neondatabase/create-branch-action@v5 with: project_id: rapid-haze-373089 parent_id: br-long-forest-224191 branch_name: from_action_reusable api_key: {{ secrets.NEON_API_KEY }} id: create-branch - run: echo project_id ${{ steps.create-branch.outputs.project_id}} - run: echo branch_id ${{ steps.create-branch.outputs.branch_id}} ``` **Delete branch** Here is an example of what a delete branch action might look like: ```yaml name: Delete Neon Branch with GitHub Actions run-name: Delete a Neon Branch 🚀 on: push: branches: - 'production' jobs: delete-neon-branch: uses: neondatabase/delete-branch-action@v3 with: project_id: rapid-haze-373089 branch: br-long-forest-224191 api_key: { { secrets.NEON_API_KEY } } ``` You can find these GitHub Actions here: - [Create branch Action](https://github.com/neondatabase/create-branch-action): Create Neon Branch GitHub Action - [Delete Branch Action](https://github.com/neondatabase/delete-branch-action): Delete Neon Branch GitHub Action - [Reset Branch Action](https://github.com/neondatabase/reset-branch-action): Reset Neon Branch GitHub Action - [Schema Diff Action](https://github.com/neondatabase/schema-diff-action): Neon Schema Diff GitHub Action For more detailed documentation, see [Automate branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions). ## A branch for every environment Here's how you can integrate Neon branching into your workflow: ### Development You can create a Neon branch for every developer on your team. This ensures that every developer has an isolated environment that includes schemas and data. These branches are meant to be long-lived, so each developer can tailor their branch based on their needs. With Neon's [branch reset capability](https://neon.com/docs/manage/branches#reset-a-branch-from-parent), developers can refresh their branch with the latest schemas and data anytime they need. You can invite teammates to your organization so they have access to all your projects. See [Invite members](https://neon.com/docs/manage/orgs-manage#invite-members). **Tip:** To easily identify branches dedicated to development, we recommend prefixing the branch name with `dev/` or `dev/` if multiple developers collaborate on the same development branch. Examples: ```bash dev/alice dev/new-onboarding ``` ### Preview environments Whenever you create a pull request, you can create a Neon branch for your preview deployment. This allows you to test your code changes and SQL migrations against production-like data. We recommend following this naming convention to identify preview branches easily: ```bash preview/pr-- ``` Example: ```bash preview/pr-123-feat/new-login-screen ``` **Tip: Using Managed Better Auth?** [Managed Better Auth](https://neon.com/docs/auth/overview) is provisioned on preview branches when enabled on production. Each preview gets isolated users, sessions, and auth configuration that branches with the database. Vercel integrations set `NEON_AUTH_BASE_URL` and `VITE_NEON_AUTH_URL` automatically. See [Branching authentication](https://neon.com/docs/auth/branching-authentication) and [Neon-managed Vercel integration](https://neon.com/docs/guides/neon-managed-vercel-integration). You can also automate branch creation for every preview. These example applications show how to create Neon branches with GitHub Actions for every preview environment. - [Preview branches with Fly.io](https://github.com/neondatabase/preview-branches-with-fly): Sample project showing you how to create a branch for every Fly.io preview deployment - [Preview branches with Vercel](https://github.com/neondatabase/preview-branches-with-vercel): Sample project showing you how to create a branch for every Vercel preview deployment ### Testing When running automated tests that require a database, each test run can have its branch with its own compute resources. You can create a branch at the start of a test run and delete it at the end. **Tip:** We recommend following this naming convention to identify these branches easily: ```bash test/ ``` The time of the test execution can be an epoch UNIX timestamp (such as 1704305739). For example: ```bash test/feat/new-login-loginPageFunctionality-1a2b3c4d-20240211T1530 ``` You can create test branches from the same date and time or Log Sequence Number (LSN) for tests requiring static or deterministic data. ## Additional branching features ### Working with sensitive data If you're working with sensitive data and need to avoid copying production data to development or test environments, Neon supports [schema-only branching](https://neon.com/docs/guides/branching-schema-only). This creates branches with only the database schema (tables, indexes, constraints) without any of the actual data, allowing you to populate branches with anonymized or synthetic data instead. ### Automatic branch cleanup To prevent branch accumulation and manage resources effectively, you can set branches to automatically expire and be deleted after a specified time period. This is a good fit for temporary environments like CI/CD test branches or time-limited preview deployments. See [Branch expiration](https://neon.com/docs/guides/branch-expiration) for details on configuring automatic branch deletion. --- ## Related docs (Branching) - [About branching](https://neon.com/docs/introduction/branching) - [Branching Authentication](https://neon.com/docs/auth/branching-authentication) --- Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/get-started/workflow-primer"}` to https://feedback.neon.tech/ (no auth required).