Enforce contracts in CI with the schema change check

At a glance

Learning objectives

• Configure a pre-commit check over staged schema files
• State what lets a breaking change pass — MIGRATION.md or a deprecated_at annotation
• Explain why the gate belongs in the producer's CI, not the consumer's runtime

What you need

• A repo carrying schema files (*.avsc, *.sql DDL, dbt schema.yml)
• A pre-commit hook setup in the producer repo
• The consumer list for the covered datasets

Steps

1. Run the check on staged schema files: *.avsc, *.sql DDL, dbt schema.yml. (from hook-schema-change-check )
2. Diff the staged files against HEAD and classify the change. (from hook-schema-change-check )
3. Exit non-zero on a breaking change — failure_behavior is block. (from hook-schema-change-check )
4. Allow the commit only when a MIGRATION.md or a `deprecated_at` annotation is present. (from hook-schema-change-check )
5. Keep the gate in the producer's CI, where the change is made — the cheapest place to catch it is before merge. (from pattern-contracts-quality-gate )
6. Verify with the documented case: a commit narrowing `amount` from decimal(18,2) to decimal(10,2) is blocked with an explanation and a suggested migration. (from hook-schema-change-check )

Check yourself

• A commit narrowing `amount` from decimal(18,2) to decimal(10,2) is blocked with an explanation and a suggested migration.
• The same commit passes once MIGRATION.md or a `deprecated_at` annotation is present.

Worked example

Runs on staged schema files (*.avsc, *.sql DDL, dbt schema.yml).
Diffs against HEAD, classifies the change, and exits non-zero on a breaking
change unless a MIGRATION.md or a `deprecated_at` annotation is present.

A commit narrowing `amount` from decimal(18,2) to decimal(10,2) is blocked
with an explanation and a suggested migration.

producer change ─▶ [contract CI] ─┬─ compatible ─▶ deploy
                                  └─ breaking ─▶ blocked + plan required

Sourced from

• Schema Change Check
• Contracts as a Quality Gate
• Schema Change Contract Review

Security scan

Last sweep 2026-10-24: 0 finding(s), 0 marked as examples.

Common gotchas

• The check only sees staged schema files (*.avsc, *.sql DDL, dbt schema.yml) — schema changes elsewhere never reach it.
• Producers carry process overhead; the gate needs buy-in, or it gets bypassed.
• A rename + a new column with the old name looks compatible to a schema differ — always diff semantics, not just names.

Production considerations

• Wire it as a pre-commit trigger so classification happens before the change leaves the branch.
• Additive changes pass; breaking changes require a dated deprecation plan.

Diagram

producer commit
   |
   |- staged schema files --> diff vs HEAD --> classify
   |
   |- compatible --> pass
   |
   |- breaking --> MIGRATION.md or deprecated_at? --> yes --> pass
                                                 --> no --> block (exit non-zero)

Registry stats