🚀 Add to your workflow — copy, paste, done

# .github/workflows/schema-diff.yml
name: Schema Diff
on: [pull_request]
jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aimadetools/race-kimi@main
        with:
          old-schema-path: ./schema/base.sql
          new-schema-path: ./schema/current.sql
          dialect: postgres
          post-comment: true
          create-check-run: true
          run-only-on-schema-change: true   # skip CI when no .sql files changed
          github-token: ${{ secrets.GITHUB_TOKEN }}
          fail-on-breaking: true
      

View on GitHub ⚡ Setup Wizard

✅ What the PR Check Run looks like

SchemaLens Schema Diff — Successful in 2s

Risk: Medium (42/100) · Breaking: 1

SchemaLens detected 1 added, 0 removed, and 2 modified tables. Risk level: Medium (42/100). 1 breaking change(s) found.

ALTER TABLE users
  ADD COLUMN email_verified_at TIMESTAMP;

-- ... 12 total migration lines.

💡 12 total migration lines. Unlock the full migration script with SchemaLens Pro

📋 What the Job Summary looks like

🔍 SchemaLens Schema Diff Report

🟢 Tables Added	1
🔴 Tables Removed	0
🟡 Tables Modified	2
⚠️ Breaking Changes	1
📊 Risk Score	42/100 (Medium)

Migration Preview (Free Tier)

ALTER TABLE users
  ADD COLUMN email_verified_at TIMESTAMP;

💡 12 total migration lines. Unlock the full migration with SchemaLens Pro →

Generated by SchemaLens GitHub Action

💬 What the PR comment looks like

SchemaLens Bot

commented 2 minutes ago

🔍 SchemaLens Schema Diff (Free Tier)

Risk: Medium (42/100) | Breaking changes: 1

Migration Preview

ALTER TABLE users
  ADD COLUMN email_verified_at TIMESTAMP;

-- ... 12 total migration lines.

12 total migration lines. Unlock full migration with SchemaLens Pro

Generated by SchemaLens GitHub Action

🔴 See it live on our repo

We use the SchemaLens GitHub Action on this very repository. Every time we update the demo schema files, the action runs and posts a diff summary.

👁️ See Interactive PR Demo 🧩 Chrome Extension PR Demo 🔖 Bookmarklet ▶ View Live Action Runs 📄 Demo Schema v1

Open a pull request that changes demo/schema-v2.sql to see the PR comment in action.

Why add schema diff to CI?

🛡️ Prevent production incidents

Breaking changes like dropped columns, removed indexes, or altered constraints get flagged before merge — not after deploy.

✅ Native PR Checks

Create a real GitHub Check Run that appears in the PR checks tab — just like your test suite. Team members see risk scores and migration previews without leaving GitHub.

📋 Rich Job Summary

Every run generates a markdown summary on the Actions run page with tables, risk scores, migration previews, and Pro upgrade CTAs. No clicking required.

💬 PR comments, automatically

Every pull request gets a clear schema diff summary posted as a comment. Reviewers see exactly what changed.

⏭️ Smart Skip

Set run-only-on-schema-change: true and the action skips entirely when no .sql files were modified — saving CI minutes and reducing noise.

⚡ Zero setup required

No database connections, no CLI installation, no license key. Just point the action at two SQL files.

🚦 Fail the build on breaking changes

Set fail-on-breaking: true and the workflow fails if any dangerous schema changes are detected.

📊 Risk score at a glance

Each diff gets a 0-100 risk score. High-risk migrations get extra scrutiny in code review.

🔓 100% free for open source

The free tier includes breaking change detection, risk scoring, and PR comments. No credit card required.

How it works

Dump your schema

Export your database schema to a SQL file as part of your workflow (e.g., pg_dump --schema-only or commit your schema file).

Compare before and after

The action compares the schema from your base branch against the schema in the PR. Any drift is surfaced instantly.

Get a PR comment with the diff

Enable post-comment: true and the action posts a formatted summary directly on the pull request.

Free vs Pro

Feature	Free Tier	Pro (optional)
Schema diff summary	✅	✅
Breaking change detection	✅	✅
Risk score	✅	✅
PR comments	✅	✅
GitHub Check Runs	✅	✅
Rich Job Summary	✅	✅
Smart Skip (no SQL changes)	✅	✅
Full migration SQL	First 5 lines	✅ Complete script
Markdown export	✅	✅
JSON export	✅	✅
Rate limit	15/min	30/min

Full configuration reference

# All available inputs
with:
  old-schema-path: ./schema/old.sql    # required
  new-schema-path: ./schema/new.sql    # required
  dialect: postgres                  # optional: postgres | mysql | sqlite | mssql | oracle
  format: markdown                   # optional: json | markdown | sql
  license-key: ${{ secrets.SCHEMALENS_KEY }}  # optional — unlocks full migration SQL
  fail-on-breaking: false            # optional — fail workflow if breaking changes found
  post-comment: false                # optional — post result as PR comment
  create-check-run: false            # optional — create a GitHub Check Run (needs checks:write)
  run-only-on-schema-change: false    # optional — skip if no .sql files changed in PR
  github-token: ${{ secrets.GITHUB_TOKEN }}  # required if post-comment, create-check-run, or run-only-on-schema-change is true
    

Example: PostgreSQL project

# .github/workflows/schema.yml
name: Schema Check
on:
  pull_request:
    paths:
      - 'migrations/**'
      - 'schema.sql'
jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Get base schema
        run: |
          git show origin/${{ github.base_ref }}:schema.sql > schema-base.sql
      - uses: aimadetools/race-kimi@main
        with:
          old-schema-path: schema-base.sql
          new-schema-path: schema.sql
          dialect: postgres
          post-comment: true
          github-token: ${{ secrets.GITHUB_TOKEN }}
          fail-on-breaking: true
    

Start catching schema drift today

Free forever for open source. Upgrade to Pro for full migration generation.

Try SchemaLens Free View Pro Pricing

🏢 Need this for your team?

Get a personalized walkthrough of SchemaLens for your engineering team — including SSO, shared workspaces, and Slack alerts.

Book a Demo Free Team Audit

SchemaLens GitHub Action Free