Adding a schema diff tool (#123)

The new tool to generate schema diff for a specific branch has been
added. It also suggests generating a zero-downtime migration and
executing it on the parent branch if the user gives consent.

<details>
<summary>Here is the example</summary>
# Generate schema diff for branch
_Exported on 10/8/2025 at 14:53:39 GMT+2 from Cursor (1.7.39)_

---

**User**

can you generate a schema diff for the branch br-holy-surf-admmhx6e in
project winter-cake-15657477

---

**Cursor**

I'll generate a schema diff for that branch. Let me compare its schema
with its parent branch.

Perfect! I've generated the schema diff for branch
`br-holy-surf-admmhx6e` in project `winter-cake-15657477`. Here's what
changed compared to its parent branch:

## Schema Changes

### **Tables Modified**
- **`public.users`**: Added 3 new columns
  - `is_deleted` - boolean field with default value `false` (NOT NULL)
- `created_at` - timestamp with timezone, defaults to current time (NOT
NULL)
  - `updated_at` - timestamp with timezone (nullable)

### **Indexes Added**
- **`users_created_at_idx`**: A B-tree index on the `users` table
  - Indexes `created_at` in descending order
- Partial index with condition `WHERE (is_deleted = false)` for better
performance

---

The diff represents the changes that would need to be applied to the
parent branch to match this child branch's schema. This looks like a
typical soft-delete pattern implementation with audit timestamps and an
optimized index for querying non-deleted users by creation time.

Would you like me to help you:
1. Generate a zero-downtime migration to apply these changes to the
parent branch?
2. Analyze the impact of these changes?
3. Something else?

---

**User**

let's go

---

**Cursor**

Great! I'll generate a zero-downtime migration to apply these changes to
the parent branch. Let me create SQL statements that are safe to run
without blocking your database.

## Proposed Migration Strategy

Based on the schema diff, here's the zero-downtime migration plan:

### Step 1: Add `is_deleted` column (safe - no table rewrite)
```sql
ALTER TABLE users ADD COLUMN IF NOT EXISTS is_deleted boolean DEFAULT false NOT NULL;
```

### Step 2: Add `created_at` column (zero-downtime approach)
```sql
-- Add column without default first (fast, no rewrite)
ALTER TABLE users ADD COLUMN IF NOT EXISTS created_at timestamp with time zone;

-- Backfill existing rows
UPDATE users SET created_at = now() WHERE created_at IS NULL;

-- Now set NOT NULL constraint
ALTER TABLE users ALTER COLUMN created_at SET NOT NULL;

-- Finally, set the default for future inserts
ALTER TABLE users ALTER COLUMN created_at SET DEFAULT now();
```

### Step 3: Add `updated_at` column (safe - nullable, no default)
```sql
ALTER TABLE users ADD COLUMN IF NOT EXISTS updated_at timestamp with time zone;
```

### Step 4: Create index concurrently (zero-downtime)
```sql
CREATE INDEX CONCURRENTLY IF NOT EXISTS users_created_at_idx ON public.users USING btree (created_at DESC) WHERE (is_deleted = false);
```

---

**Impact Summary:**
- ✅ No table rewrites
- ✅ Minimal lock time
- ✅ Index created without blocking writes
- ⚠️ The UPDATE statement in Step 2 may take time on large tables but
won't block reads/writes

**Would you like me to execute this migration on the parent branch
now?** I'll run each statement and show you the results. Type "yes" to
proceed or let me know if you'd like any adjustments.

```sql
ALTER TABLE users ADD COLUMN IF NOT EXISTS is_deleted boolean DEFAULT false NOT NULL;
```

```sql
-- Add column without default first (fast, no rewrite)
ALTER TABLE users ADD COLUMN IF NOT EXISTS created_at timestamp with time zone;

-- Backfill existing rows
UPDATE users SET created_at = now() WHERE created_at IS NULL;

-- Now set NOT NULL constraint
ALTER TABLE users ALTER COLUMN created_at SET NOT NULL;

-- Finally, set the default for future inserts
ALTER TABLE users ALTER COLUMN created_at SET DEFAULT now();
```

```sql
ALTER TABLE users ADD COLUMN IF NOT EXISTS updated_at timestamp with time zone;
```

```sql
CREATE INDEX CONCURRENTLY IF NOT EXISTS users_created_at_idx ON public.users USING btree (created_at DESC) WHERE (is_deleted = false);
```

---

**User**

yes

---

**Cursor**

Perfect! I'll execute the migration step by step on the parent branch.
Let me start:

✅ **Step 1 Complete:** Added `is_deleted` column

✅ **Step 2a Complete:** Added `created_at` column (nullable, no default)

✅ **Step 2b Complete:** Backfilled existing rows with current timestamp

✅ **Step 2c Complete:** Set NOT NULL constraint on `created_at`

✅ **Step 2d Complete:** Set default value for `created_at`

✅ **Step 3 Complete:** Added `updated_at` column

✅ **Step 4 Complete:** Created index `users_created_at_idx` concurrently

---

## 🎉 Migration Complete!

All schema changes have been successfully applied to the parent branch.
Let me verify that the schemas now match:

✅ **Verification Complete:** The schema diff is now empty, confirming
that the parent branch schema now matches the child branch
`br-holy-surf-admmhx6e`.

### Summary of Changes Applied:
1. ✅ Added `is_deleted` column (boolean, default: false, NOT NULL)
2. ✅ Added `created_at` column (timestamptz, default: now(), NOT NULL) 
3. ✅ Added `updated_at` column (timestamptz, nullable)
4. ✅ Created partial index `users_created_at_idx` for efficient queries
on non-deleted users

**All changes were applied with zero-downtime** - no table locks, no
blocking operations, and the index was created concurrently. Your
database is now fully updated! 🚀
</details>

Author: vadim2404

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Feat: `list_shared_projects` tool to fetch projects that user has permissions to collaborate on
 - Feat: `reset_from_parent` tool to reset a branch from its parent's current state
+- Feat: `compare_database_schema` tool to compare the schema from the child branch and its parent
 
 # [0.6.4] 2025-08-22
 

README.md

@@ -198,6 +198,7 @@ The Neon MCP Server provides the following actions, which are exposed as "tools"
 - **`list_branch_computes`**: Lists compute endpoints for a project or specific branch, including compute ID, type, size, and autoscaling information.
 - **`list_organizations`**: Lists all organizations that the current user has access to. Optionally filter by organization name or ID using the search parameter.
 - **`reset_from_parent`**: Resets the current branch to its parent's state, discarding local changes. Automatically preserves to backup if branch has children, or optionally preserve on request with a custom name.
+- **`compare_database_schema`**: Shows the schema diff between the child branch and its parent
 
 **SQL Query Execution:**
 

landing/components/DescriptionItem.tsx

@@ -13,6 +13,8 @@ import {
 import {
   Terminal,
   CircleAlert,
+  Lightbulb,
+  BadgeInfo,
   Workflow,
   SquareArrowRight,
   Component,
@@ -30,6 +32,8 @@ const ALERT_VARIANT_PER_DESCRIPTION_TYPE: Record<
   next_steps: { variant: 'default', icon: SquareArrowRight },
   important_notes: { variant: 'important', icon: CircleAlert },
   workflow: { variant: 'default', icon: Workflow },
+  hints: { variant: 'default', icon: BadgeInfo },
+  hint: { variant: 'default', icon: Lightbulb },
   instructions: { variant: 'default', icon: Terminal },
   response_instructions: { variant: 'default', icon: Terminal },
   example: { variant: 'default', icon: Terminal },

landing/lib/description.ts

@@ -10,6 +10,8 @@ const POSSIBLE_TYPES = [
   'example',
   'do_not_include',
   'error_handling',
+  'hint',
+  'hints',
 ] as const;
 
 export type DescriptionItemType = (typeof POSSIBLE_TYPES)[number];
@@ -134,7 +136,7 @@ export function parseDescription(description: string): DescriptionItem[] {
 
   while (rest.length > 0) {
     const match = rest.match(
-      /<(use_case|workflow|important_notes|next_steps|response_instructions|instructions|example|do_not_include|error_handling)>(.*?)<\/\1>/s,
+      /<(use_case|workflow|important_notes|next_steps|response_instructions|instructions|example|do_not_include|error_handling|hints?)>(.*?)<\/\1>/s,
     );
 
     if (!match) {

src/tools/definitions.ts

@@ -23,6 +23,7 @@ import {
   listOrganizationsInputSchema,
   listSharedProjectsInputSchema,
   resetFromParentInputSchema,
+  compareDatabaseSchemaInputSchema,
 } from './toolsSchema.js';
 
 export const NEON_TOOLS = [
@@ -608,4 +609,273 @@ export const NEON_TOOLS = [
     description: 'Lists compute endpoints for a project or specific branch',
     inputSchema: listBranchComputesInputSchema,
   },
+  {
+    name: 'compare_database_schema' as const,
+    description: `
+    <use_case>
+      Use this tool to compare the schema of a database between two branches.
+      The output of the tool is a JSON object with one field: \`diff\`.
+
+      <example>
+        \`\`\`json
+        {
+          "diff": "--- a/neondb\n+++ b/neondb\n@@ -27,7 +27,10 @@\n \n CREATE TABLE public.users (\n id integer NOT NULL,\n- username character varying(50) NOT NULL\n+ username character varying(50) NOT NULL,\n+ is_deleted boolean DEFAULT false NOT NULL,\n+ created_at timestamp with time zone DEFAULT now() NOT NULL,\n+ updated_at timestamp with time zone\n );\n \n \n@@ -79,6 +82,13 @@\n \n \n --\n+-- Name: users_created_at_idx; Type: INDEX; Schema: public; Owner: neondb_owner\n+--\n+\n+CREATE INDEX users_created_at_idx ON public.users USING btree (created_at DESC) WHERE (is_deleted = false);\n+\n+\n+--\n -- Name: DEFAULT PRIVILEGES FOR SEQUENCES; Type: DEFAULT ACL; Schema: public; Owner: cloud_admin\n --\n \n"
+        }
+        \`\`\`
+      </example>
+
+      At this field you will find a difference between two schemas.
+      The diff represents the changes required to make the parent branch schema match the child branch schema.
+      The diff field contains a unified diff (git-style patch) as a string.
+
+      You MUST be able to generate a zero-downtime migration from the diff and apply it to the parent branch.
+      (This branch is a child and has a parent. You can get parent id just querying the branch details.)
+    </use_case>
+
+    <important_notes>
+      To generate schema diff, you MUST SPECIFY the \`database_name\`.
+      If \`database_name\` is not specified, you MUST fall back to the default database name: \`${NEON_DEFAULT_DATABASE_NAME}\`.
+
+      You MUST TAKE INTO ACCOUNT the PostgreSQL version. The PostgreSQL version is the same for both branches.
+      You MUST ASK user consent before running each generated SQL query.
+      You SHOULD USE \`run_sql\` tool to run each generated SQL query.
+      You SHOULD suggest creating a backup or point-in-time restore before running the migration.
+      Generated queries change the schema of the parent branch and MIGHT BE dangerous to execute.
+      Generated SQL migrations SHOULD be idempotent where possible (i.e., safe to run multiple times without failure) and include \`IF NOT EXISTS\` / \`IF EXISTS\` where applicable.
+      You SHOULD recommend including comments in generated SQL linking back to diff hunks (e.g., \`-- from diff @@ -27,7 +27,10 @@\`) to make audits easier.
+      Generated SQL should be reviewed for dependencies (e.g., foreign key order) before execution.
+    </important_notes>
+
+    <next_steps>
+      After executing this tool, you MUST follow these steps:
+        1. Review the schema diff and suggest generating a zero-downtime migration.
+        2. Follow these instructions to respond to the client:
+
+        <response_instructions>
+          <instructions>
+            Provide brief information about the changes:
+              * Tables
+              * Views
+              * Indexes
+              * Ownership
+              * Constraints
+              * Triggers
+              * Policies
+              * Extensions
+              * Schemas
+              * Sequences
+              * Tablespaces
+              * Users
+              * Roles
+              * Privileges
+          </instructions>
+        </response_instructions>
+
+        3. If a migration fails, you SHOULD guide the user on how to revert the schema changes, for example by using backups, point-in-time restore, or generating reverse SQL statements (if safe).
+    </next_steps>
+
+    This tool:
+    1. Generates a diff between the child branch and its parent.
+    2. Generates a SQL migration from the diff.
+    3. Suggest generating zero-downtime migration.
+
+    <workflow>
+      1. User asks you to generate a diff between two branches.
+      2. You suggest generating a SQL migration from the diff.
+      3. Ensure the generated migration is zero-downtime; otherwise, warn the user.
+      4. You ensure that your suggested migration is also matching the PostgreSQL version.
+      5. You use \`run_sql\` tool to run each generated SQL query and ask the user consent before running it.
+        Before requesting user consent, present a summary of all generated SQL statements along with their potential impact (e.g., table rewrites, lock risks, validation steps) so the user can make an informed decision.
+      6. Propose to rerun the schema diff tool one more time to ensure that the migration is applied correctly.
+      7. If the diff is empty, confirm that the parent schema now matches the child schema.
+      8. If the diff is not empty after migration, warn the user and assist in resolving the remaining differences.
+    </workflow>
+
+    <hints>
+      <hint>
+        Adding the column with a \`DEFAULT\` static value will not have any locks.
+        But if the function is called that is not deterministic, it will have locks.
+
+        <example>
+          \`\`\`sql
+          -- No table rewrite, minimal lock time
+          ALTER TABLE users ADD COLUMN status text DEFAULT 'active';
+          \`\`\`
+        </example>
+
+        There is an example of a case where the function is not deterministic and will have locks:
+
+        <example>
+          \`\`\`sql
+          -- Table rewrite, potentially longer lock time
+          ALTER TABLE users ADD COLUMN created_at timestamptz DEFAULT now();
+          \`\`\`
+
+          The fix for this is next:
+
+          \`\`\`sql
+          -- Adding a nullable column first
+          ALTER TABLE users ADD COLUMN created_at timestamptz;
+
+          -- Setting the default value because the rows are updated
+          UPDATE users SET created_at = now();
+          \`\`\`
+        </example>
+      </hint>
+
+      <hint>
+        Adding constraints in two phases (including foreign keys)
+
+        <example>
+          \`\`\`sql
+          -- Step 1: Add constraint without validating existing data
+          -- Fast - only blocks briefly to update catalog
+          ALTER TABLE users ADD CONSTRAINT users_age_positive
+            CHECK (age > 0) NOT VALID;
+
+          -- Step 2: Validate existing data (can take time but doesn't block writes)
+          -- Uses SHARE UPDATE EXCLUSIVE lock - allows reads/writes
+          ALTER TABLE users VALIDATE CONSTRAINT users_age_positive;
+          \`\`\`
+        </example>
+
+        <example>
+         \`\`\`sql
+          -- Step 1: Add foreign key without validation
+          -- Fast - only updates catalog, doesn't validate existing data
+          ALTER TABLE orders ADD CONSTRAINT orders_user_id_fk
+            FOREIGN KEY (user_id) REFERENCES users(id) NOT VALID;
+
+          -- Step 2: Validate existing relationships
+          -- Can take time but allows concurrent operations
+          ALTER TABLE orders VALIDATE CONSTRAINT orders_user_id_fk;
+          \`\`\`
+        </example>
+      </hint>
+
+      <hint>
+        Setting columns to NOT NULL
+
+        <example>
+         \`\`\`sql
+          -- Step 1: Add a check constraint (fast with NOT VALID)
+          ALTER TABLE users ADD CONSTRAINT users_email_not_null
+            CHECK (email IS NOT NULL) NOT VALID;
+
+          -- Step 2: Validate the constraint (allows concurrent operations)
+          ALTER TABLE users VALIDATE CONSTRAINT users_email_not_null;
+
+          -- Step 3: Set NOT NULL (fast since constraint guarantees no nulls)
+          ALTER TABLE users ALTER COLUMN email SET NOT NULL;
+
+          -- Step 4: Drop the redundant check constraint
+          ALTER TABLE users DROP CONSTRAINT users_email_not_null;
+          \`\`\`
+        </example>
+
+        <example>
+          For PostgreSQL v18+
+          (to get PostgreSQL version, you can use \`describe_project\` tool or \`run_sql\` tool and execute \`SELECT version();\` query)
+
+          \`\`\`sql
+          -- PostgreSQL 18+ - Simplified approach
+          ALTER TABLE users ALTER COLUMN email SET NOT NULL NOT VALID;
+          ALTER TABLE users VALIDATE CONSTRAINT users_email_not_null;
+          \`\`\`
+        </example>
+      </hint>
+
+      <hint>
+        In some cases, you need to combine two approaches to achieve a zero-downtime migration.
+
+        <example>
+          \`\`\`sql
+          -- Step 1: Adding a nullable column first
+          ALTER TABLE users ADD COLUMN created_at timestamptz;
+
+          -- Step 2: Updating the all rows with the default value
+          UPDATE users SET created_at = now() WHERE created_at IS NULL;
+
+          -- Step 3: Creating a not null constraint
+          ALTER TABLE users ADD CONSTRAINT users_created_at_not_null
+            CHECK (created_at IS NOT NULL) NOT VALID;
+
+          -- Step 4: Validating the constraint
+          ALTER TABLE users VALIDATE CONSTRAINT users_created_at_not_null;
+
+          -- Step 5: Setting the column to NOT NULL
+          ALTER TABLE users ALTER COLUMN created_at SET NOT NULL;
+
+          -- Step 6: Dropping the redundant NOT NULL constraint
+          ALTER TABLE users DROP CONSTRAINT users_created_at_not_null;
+
+          -- Step 7: Adding the default value
+          ALTER TABLE users ALTER COLUMN created_at SET DEFAULT now();
+          \`\`\`
+        </example>
+
+        For PostgreSQL v18+
+        <example>
+          \`\`\`sql
+          -- Step 1: Adding a nullable column first
+          ALTER TABLE users ADD COLUMN created_at timestamptz;
+
+          -- Step 2: Updating the all rows with the default value
+          UPDATE users SET created_at = now() WHERE created_at IS NULL;
+
+          -- Step 3: Creating a not null constraint
+          ALTER TABLE users ALTER COLUMN created_at SET NOT NULL NOT VALID;
+
+          -- Step 4: Validating the constraint
+          ALTER TABLE users VALIDATE CONSTRAINT users_created_at_not_null;
+
+          -- Step 5: Adding the default value
+          ALTER TABLE users ALTER COLUMN created_at SET DEFAULT now();
+          \`\`\`
+        </example>
+      </hint>
+
+      <hint>
+        Create index CONCURRENTLY
+
+        <example>
+          \`\`\`sql
+          CREATE INDEX CONCURRENTLY idx_users_email ON users (email);
+          \`\`\`
+        </example>
+      </hint>
+
+      <hint>
+        Drop index CONCURRENTLY
+
+        <example>
+          \`\`\`sql
+          DROP INDEX CONCURRENTLY idx_users_email;
+          \`\`\`
+        </example>
+      </hint>
+
+      <hint>
+        Create materialized view WITH NO DATA
+
+        <example>
+          \`\`\`sql
+          CREATE MATERIALIZED VIEW mv_users AS SELECT name FROM users WITH NO DATA;
+          \`\`\`
+        </example>
+      </hint>
+
+      <hint>
+        Refresh materialized view CONCURRENTLY
+
+        <example>
+          \`\`\`sql
+          REFRESH MATERIALIZED VIEW CONCURRENTLY mv_users;
+          \`\`\`
+        </example>
+      </hint>
+    </hints>
+    `,
+    inputSchema: compareDatabaseSchemaInputSchema,
+  },
 ];

src/tools/tools.ts

@@ -4,6 +4,7 @@ import {
   EndpointType,
   ListProjectsParams,
   ListSharedProjectsParams,
+  GetProjectBranchSchemaComparisonParams,
   Organization,
   ProjectCreateRequest,
 } from '@neondatabase/api-client';
@@ -1212,6 +1213,14 @@ async function handleListSharedProjects(
   return response.data.projects;
 }
 
+async function handleCompareDatabaseSchema(
+  params: GetProjectBranchSchemaComparisonParams,
+  neonClient: Api<unknown>,
+) {
+  const response = await neonClient.getProjectBranchSchemaComparison(params);
+  return response.data;
+}
+
 export const NEON_HANDLERS = {
   list_projects: async ({ params }, neonClient, extra) => {
     const organization = await getOrgByOrgIdOrDefault(
@@ -1774,4 +1783,18 @@ export const NEON_HANDLERS = {
       ],
     };
   },
+
+  compare_database_schema: async ({ params }, neonClient) => {
+    const result = await handleCompareDatabaseSchema(
+      {
+        projectId: params.projectId,
+        branchId: params.branchId,
+        db_name: params.databaseName,
+      },
+      neonClient,
+    );
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  },
 } satisfies ToolHandlers;

src/tools/toolsSchema.ts

@@ -334,3 +334,9 @@ export const resetFromParentInputSchema = z.object({
       'Optional name to preserve the current state under a new branch before resetting',
     ),
 });
+
+export const compareDatabaseSchemaInputSchema = z.object({
+  projectId: z.string().describe('The ID of the project'),
+  branchId: z.string().describe('The ID of the branch'),
+  databaseName: z.string().describe(DATABASE_NAME_DESCRIPTION),
+});