SchemaLens GitLab CI — Free Schema Diff in Merge Requests

🚀 Add to your pipeline — copy, paste, done

# .gitlab-ci.yml
stages:
  - validate

schema-diff:
  stage: validate
  image: node:20-alpine
  variables:
    SCHEMA_PATH: "db/schema.sql"
    DIALECT: "postgres"
    POST_MR_COMMENT: "true"
    FAIL_ON_BREAKING: "true"
  before_script:
    - apk add --no-cache git curl jq
  script:
    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
    - git show origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME:$SCHEMA_PATH > /tmp/schema_base.sql
    - node ci/schemalens-diff.js /tmp/schema_base.sql $SCHEMA_PATH --dialect=$DIALECT --format=markdown --output=/tmp/report.md
    - cat /tmp/report.md
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.sql"
  artifacts:
    paths:
      - /tmp/report.md
    expire_in: 1 week
      

Download .gitlab-ci.yml GitLab Snippets

💬 What the MR 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 GitLab CI

📦 What the pipeline artifact looks like

schema_diff_report.md 2.4 KB

Team members can download the full markdown report from the Build > Artifacts section of any merge request pipeline. 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 GitLab CI?

🛡️ Prevent production incidents

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

💬 MR comments, automatically

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

📦 Downloadable artifacts

The full markdown report is attached to every pipeline as an 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 CI minutes.

⚡ Zero setup required

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

🚦 Fail the pipeline on breaking changes

Set FAIL_ON_BREAKING: "true" and the pipeline 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, MR 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 MR. Any drift is surfaced instantly.

Get an MR comment with the diff

Enable POST_MR_COMMENT: "true" and add a GITLAB_TOKEN variable. The job posts a formatted summary directly on the merge request.

Free vs Pro

Feature	Free Tier	Pro (optional)
Schema diff summary	✅	✅
Breaking change detection	✅	✅
Risk score	✅	✅
MR comments	✅	✅
Pipeline artifacts	✅	✅
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

# CI/CD Variables (Settings → CI/CD → Variables)
GITLAB_TOKEN     # optional — Project access token with api scope for MR comments
SL_LICENSE_KEY   # optional — SchemaLens Pro license key for full migration output

# Job 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 pipeline on breaking changes
POST_MR_COMMENT          "false"              # true = post report as MR comment (needs GITLAB_TOKEN)
SKIP_NO_SQL_CHANGE       "false"              # true = skip job when no .sql files changed
    

Example: PostgreSQL project with MR comments

# .gitlab-ci.yml
stages:
  - validate

schema-diff:
  stage: validate
  image: node:20-alpine
  variables:
    SCHEMA_PATH: "db/schema.sql"
    DIALECT: "postgres"
    POST_MR_COMMENT: "true"
    FAIL_ON_BREAKING: "true"
    SKIP_NO_SQL_CHANGE: "true"
  before_script:
    - apk add --no-cache git curl jq
  script:
    - # Fetch base branch schema
    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
    - git show origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME:$SCHEMA_PATH > /tmp/schema_base.sql 2>/dev/null || echo "-- No base schema" > /tmp/schema_base.sql
    - # Run diff via SchemaLens API
    - |
      BODY=$(jq -n \
        --arg schemaA "$(cat /tmp/schema_base.sql)" \
        --arg schemaB "$(cat $SCHEMA_PATH)" \
        --arg dialect "$DIALECT" \
        --arg format "markdown" \
        '{schemaA: $schemaA, schemaB: $schemaB, dialect: $dialect, format: $format}')
      curl -s -X POST "https://schemalens.tech/api/free-diff" \
        -H "Content-Type: application/json" \
        -d "$BODY" > /tmp/response.json
    - # Generate report
    - jq -r '.markdown // .migrationTeaser' /tmp/response.json > /tmp/schema_diff_report.md
    - cat /tmp/schema_diff_report.md
    - # Post MR comment
    - |
      if [ "$POST_MR_COMMENT" = "true" ] && [ -n "$GITLAB_TOKEN" ]; then
        REPORT=$(cat /tmp/schema_diff_report.md | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
        curl -s -X POST \
          -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
          -H "Content-Type: application/json" \
          "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/notes" \
          -d "{\"body\": \"${REPORT}\"}"
      fi
    - # Fail on breaking changes
    - |
      BCOUNT=$(jq -r '(.summary.breakingChangeCount // (.breakingChanges | length) // 0)' /tmp/response.json)
      if [ "$FAIL_ON_BREAKING" = "true" ] && [ "$BCOUNT" != "0" ]; then
        echo "Breaking changes detected: $BCOUNT"
        exit 1
      fi
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "db/schema.sql"
        - "migrations/*.sql"
        - "**/*.sql"
  artifacts:
    paths:
      - /tmp/schema_diff_report.md
    expire_in: 1 week
    

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 GitLab CI Free