Skip to main content

CI/CD Impact Checks

This guide explains how to use the Saddle CLI (sd-cli) to prevent breaking changes by verifying schema updates in your CI/CD pipeline.

Overview​

By integrating Saddle Data into your application's CI pipeline, you can automatically detect if a database migration will break your data syncs before the code is merged.

Prerequisites​

  1. Saddle CLI installed in your CI environment.
  2. An API Key with at least Editor permissions.
  3. The Flow ID you want to protect.

Step 1: Export your proposed schema​

Your CI script should generate a JSON representation of the schema after the proposed migration. Most ORMs (Django, Rails, TypeORM) provide tools to dump the schema.

The format should be a JSON array of fields:

[
  { "name": "id", "type": "integer" },
  { "name": "email", "type": "string" },
  { "name": "created_at", "type": "datetime" }
]

Step 2: Run the impact check​

Use the check-impact command in your CI step:

sd auth login --api-key $SADDLE_API_KEY
sd check-impact \
  --flow-id "your-flow-uuid" \
  --entity "users" \
  --schema-file "./proposed_schema.json"

Step 3: Interpret the results​

The CLI will return a non-zero exit code if breaking changes are detected, allowing you to fail the CI build.

Example Output: Breaking Change​

⚠️  DRIFT DETECTED [breaking]
--------------------------------------------------------------------------------
  ❌ BREAKING: Columns removed from source will break this flow mapping.
     Fields: [phone_number]

Suggested Actions:
  - Update downstream reports and BI tools before merging this change.

Example Output: Evolution​

⚠️  DRIFT DETECTED [evolution]
--------------------------------------------------------------------------------
  ℹ️  EVOLUTION: New columns detected in source.
     Fields: [tax_id]

Suggested Actions:
  - Enable 'Auto-Map' or update flow configuration to include these columns.

GitHub Actions Example​

Here is a snippet for a GitHub Action:

jobs:
  validate-data-impact:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate Proposed Schema
        run: ./scripts/dump_schema.sh > schema.json
      - name: Saddle Impact Check
        env:
          SADDLE_API_KEY: ${{ secrets.SADDLE_API_KEY }}
        run: |
          curl -sSL https://get.saddledata.com/install.sh | sh
          sd check-impact --flow-id "..." --entity "users" --schema-file schema.json