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 -sL https://schemalens.tech/ci/circleci-diff.sh | bash - store_artifacts: path: schema_diff_report.md
Download .circleci/config.yml CircleCI Docs ⚡ Setup Wizard

💬 What the PR comment looks like

SL
SchemaLens Bot
commented 2 minutes ago

🔍 SchemaLens Schema Diff Report

🟢 Tables Added1
🔴 Tables Removed0
🟡 Tables Modified2
⚠️ Breaking Changes1
📊 Risk Score42/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

1

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).

2

Compare before and after

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

3

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

FeatureFree TierPro (optional)
Schema diff summary
Breaking change detection
Risk score
PR comments
Artifact reports
Smart skip (no SQL changes)
Full migration SQL✅ Complete script✅ Complete script
Markdown export
JSON export
Rate limit15/min30/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 -sL -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?

Preview the shared SchemaLens Team workspace: PR comment history, Slack drift alerts, migration safety scores, and a team risk dashboard — then start a 14-day free trial.

👁️ Preview Team Workspace Start Team Plan — $29/mo Calculate ROI

Generate manager approval email → · Book a setup call →