Add to your pipeline — copy, paste, done

# .circleci/config.yml
version: 2.1
jobs:
  schema-diff:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Schema Diff
          command: curl -s https://schemalens.tech/ci/circleci-diff.sh | bash
      - store_artifacts:
          path: schema_diff_report.md
      

Download .circleci/config.yml CircleCI Docs

💬 What the PR comment looks like

SchemaLens Bot

commented 2 minutes ago

🔍 SchemaLens Schema Diff Report

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

Generated Migration

ALTER TABLE users
  ADD COLUMN email_verified_at TIMESTAMP;

Generated by SchemaLens CircleCI

📦 Artifact in CircleCI

schema_diff_report.md 2.4 KB

Team members can download the full markdown report from the Artifacts tab of any CircleCI build. The report includes:

Complete diff summary with table counts
Breaking change list with severity levels
Generated migration SQL (full script with Pro)
Risk score and recommendation

Why add schema diff to CircleCI?

🛡️ Prevent production incidents

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

💬 PR comments, automatically

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

📦 Downloadable artifacts

The full markdown report is attached to every build as a CircleCI artifact. Download it for compliance docs, audits, or offline review.

⏭️ Smart skip

Set SKIP_NO_SQL_CHANGE: "true" and the job skips entirely when no .sql files were modified — saving build minutes.

⚡ Zero setup required

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

🚦 Fail the build on breaking changes

Set FAIL_ON_BREAKING: "true" and the build 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, PR comments, and artifact reports. 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 to the repo).

Compare before and after

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

Get a PR comment with the diff

Enable POST_PR_COMMENT: "true" and add a GITHUB_TOKEN environment variable. The job 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	✅	✅
Artifact reports	✅	✅
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

# CircleCI project settings → Environment Variables
GITHUB_TOKEN     # optional — GitHub PAT with repo scope for PR comments
SL_LICENSE_KEY   # optional — SchemaLens Pro license key for full migration output

# Job environment variables
SCHEMA_PATH              "db/schema.sql"      # Path to current schema SQL file
DIALECT                  "postgres"           # postgres | mysql | sqlite | mssql | oracle
FAIL_ON_BREAKING         "false"              # true = fail build on breaking changes
SKIP_NO_SQL_CHANGE       "false"              # true = skip job when no .sql files changed
POST_PR_COMMENT          "false"              # true = post report as PR comment (needs token)
FORMAT                   "markdown"           # markdown | json | sql (sql needs Pro)
    

Example: PostgreSQL project with PR comments

# .circleci/config.yml
version: 2.1

executors:
  node-executor:
    docker:
      - image: cimg/node:20.0

jobs:
  schema-diff:
    executor: node-executor
    environment:
      SCHEMA_PATH: db/schema.sql
      DIALECT: postgres
      FAIL_ON_BREAKING: "true"
      SKIP_NO_SQL_CHANGE: "true"
      POST_PR_COMMENT: "true"
    steps:
      - checkout
      - run:
          name: Smart Skip
          command: |
            if [ "$SKIP_NO_SQL_CHANGE" = "true" ]; then
              CHANGED=$(git diff --name-only origin/${CIRCLE_BRANCH}..HEAD 2>/dev/null || echo "")
              if ! echo "$CHANGED" | grep -q '\.sql$'; then
                echo "No SQL changes — skipping."
                circleci-agent step halt
              fi
            fi
      - run:
          name: Fetch base schema
          command: |
            git fetch origin main 2>/dev/null || true
            git show "origin/main:$SCHEMA_PATH" > /tmp/schema_base.sql 2>/dev/null || echo "-- No base schema" > /tmp/schema_base.sql
      - run:
          name: Run SchemaLens diff
          command: |
            set -euo pipefail
            ENDPOINT="https://schemalens.tech/api/free-diff"
            [ -n "${SL_LICENSE_KEY:-}" ] && ENDPOINT="https://schemalens.tech/api/diff"
            BODY=$(jq -n --arg a "$(cat /tmp/schema_base.sql)" --arg b "$(cat "$SCHEMA_PATH")" --arg d "$DIALECT" --arg f "$FORMAT" '{schemaA:$a,schemaB:$b,dialect:$d,format:$f}')
            curl -s -X POST "$ENDPOINT" -H "Content-Type: application/json" ${SL_LICENSE_KEY:+-H "X-License-Key: $SL_LICENSE_KEY"} -d "$BODY" > /tmp/response.json
            jq -r '.markdown // .migrationTeaser' /tmp/response.json > /tmp/schema_diff_report.md
            cat /tmp/schema_diff_report.md
      - run:
          name: Post PR comment
          command: |
            if [ "$POST_PR_COMMENT" = "true" ] && [ -n "${GITHUB_TOKEN:-}" ] && [ -n "${CIRCLE_PULL_REQUEST:-}" ]; then
              PR_NUM=$(echo "$CIRCLE_PULL_REQUEST" | sed 's/.*\///')
              REPORT=$(cat /tmp/schema_diff_report.md | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
              curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" -H "Accept: application/vnd.github.v3+json" \
                "https://api.github.com/repos/${CIRCLE_PROJECT_USERNAME}/${CIRCLE_PROJECT_REPONAME}/issues/${PR_NUM}/comments" \
                -d "{\"body\": \"## SchemaLens Report\\n\\n${REPORT}\"}" || true
            fi
          when: always
      - store_artifacts:
          path: /tmp/schema_diff_report.md
          destination: schema_diff_report.md

workflows:
  schema-diff:
    jobs:
      - schema-diff:
          filters:
            branches:
              ignore:
                - main
                - master
    

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 CircleCI Free