Schema diff

Neon's Schema Diff tool lets you compare an SQL script of the schemas for two selected branches in a side-by-side view (or line-by-line on mobile devices).

How Schema Diff works

Schema Diff is available in the Neon Console for use in two ways:

• Compare a branch's schema to its parent
• Compare selected branches during a branch restore operation

You can also use the branches schema-diff command in the Neon CLI or compare-schema endpoint in the Neon API to effect a variety of comparisons.

Compare to parent

In the detailed view for any child branch, you can check the schema differences between the selected branch and its parent. Use this view to verify the state of these schemas before you Reset from parent.

Compare to another branch's history

Built into the Time Travel assist editor, you can use Schema Diff to help when restoring branches, letting you compare states of your branch against its own or another branch's history before you complete a branch restore operation.

Comparisons using the CLI or API

You can use the Neon CLI to compare a branch to any point in its own or any other branch's history. The branches schema-diff command offers full flexibility for any type of schema comparison: between a branch and its parent, a branch and its earlier state, or a branch to the head or prior state of another branch. The Neon API provides a compare-schema endpoint that lets you compare schemas between Neon branches programmatically, supporting CI/CD automation and AI agent use cases.

Practical Applications

• Pre-Migration Reviews: Before migrating schemas from a development branch into main, use Schema Diff to ensure only intended schema changes are applied.
• Audit Changes: Historically compare schema changes to understand the evolution of your database structure.
• Consistency Checks: Ensure environment consistency by comparing schemas across development, staging, and production branches.
• Automation: Integrate schema-diff into CI/CD pipelines to automatically compare schemas during deployments.
• AI Agents: Enable AI agents to retrieve schema differences programmatically to support agent-driven database migrations.

How to Use Schema Diff

You can launch the Schema Diff viewer from the Branches and Restore pages in the Neon Console.

From the Branches page

Open the detailed view for the branch whose schema you want to inspect. In the row of details for the parent branch, under the COMPARE TO PARENT block, click Open schema diff.

From the Restore page

Just like with Time Travel Assist, your first step is to choose the branch you want to restore, then choose where you want to restore from: From history (its own history) or ** From another branch** (from another branch's history).

Click the Schema Diff button, verify that your selections are correct, then click Compare.

The two-pane view shows the schema for both your target and your selected branches.

Using the Neon CLI

You can use the Neon CLI to:

• Compare the latest schemas of any two branches
• Compare against a specific point in its own or another branch’s history

Use the schema-diff subcommand from the branches command:

neon branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]]

The operation will compare a selected branch ([compare-source]) against the latest (head) of your base branch ([base-branch]). For example, if you want to compare recent changes you made to your development branch dev/alex against your production branch main, identify main as your base branch and dev/alex as your compare-source.

neon branches schema-diff main dev/alex

You have a few options here:

• Append a timestamp or LSN to compare to a specific point in dev/alex branch's history.
• If you are regularly comparing development branches against main, include main in your set-context file. You can then leave out the [base-branch] from the command.
• Use aliases to shorten the command.
• Include --database to reduce the diff to a single database. If you don't specify a database, the diff will include all databases on the branch.

Here is the same command using aliases, with main included in set-context, pointing to an LSN from dev/alex branch's history, and limiting the diff to the database people:

neon branch sd dev/alex@0/123456 --db people

To find out what other comparisons you can make, see Neon CLI commands — branches for full documentation of the command.

Using the Neon API

The compare_schema endpoint lets you compare schemas between Neon branches programmatically and track schema changes. The endpoint response highlights differences in a diff format, making it useful for automating schema migrations and integrating schema checks into CI/CD workflows.

Another use case for schema diff via the Neon API is AI agent-driven workflows, such as environment setup and schema migrations. The compare_schema endpoint allows AI agents to programmatically retrieve schema differences by comparing two branches.

To compare schemas between two branches, use a cURL command similar to the following:

url -X GET \
  "https://console.neon.tech/api/v2/projects/wispy-butterfly-25042691/branches/br-rough-boat-a54bs9yb/compare_schema" \
  -G \
  --data-urlencode "base_branch_id=br-royal-star-a54kykl2" \
  --data-urlencode "db_name=neondb" \
  -H "accept: application/json" \
  -H "Authorization: Bearer $NEON_API_KEY" | jq -r '.diff'

Here’s an example of the compare_schema diff output for the neondb database after comparing br-rough-boat-a54bs9yb with the base branch br-royal-star-a54kykl2, where a new column was added to the target branch.

--- a/neondb
+++ b/neondb
@@ -27,7 +27,8 @@
 CREATE TABLE public.playing_with_neon (
     id integer NOT NULL,
     name text NOT NULL,
-    value real
+    value real,
+    created_at timestamp without time zone DEFAULT CURRENT_TIMESTAMP
 );

Output explanation:

• - (minus): Lines that were removed from the base branch schema.
• + (plus): Lines that were added in the target branch schema.

In the example above, the created_at column was added to the public.playing_with_neon table.

Schema Diff GitHub Action

Neon supports a Schema Diff GitHub Action that performs a database schema diff on specified Neon branches for each pull request and writes a comment to the pull request highlighting the schema differences.

This action supports workflows where schema changes are made on a branch. When you create or update a pull request containing schema changes, the action automatically generates a comment within the pull request. By including the schema diff as part of the comment, reviewers can easily assess the changes directly within the pull request.

To learn more, see the Schema Diff GitHub Action.

Tutorial

For a step-by-step guide showing you how to compare two development branches using Schema Diff, see Schema diff tutorial.