Adding a schema diff tool

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),
+});