Skip to main content

Visual Schema Diff

TalkingSchema's visual schema diff is integrated directly into the ERD canvas. Every time the AI copilot proposes schema changes — whether from a natural language request, an imported DDL update, or a Plan Mode execution — the canvas highlights the delta between the previous state and the proposed state in real time. No separate diff tool required.

How the Schema Diff Works​

TalkingSchema maintains the current schema state as a versioned model. When a change is proposed — either by the AI or by direct canvas editing — the tool computes the structural delta and presents it in two layers:

Layer 1: ERD canvas diff overlay​

The diagram shows every proposed change highlighted:

ColorMeaning
Green border/fillNew table or column being added
Amber borderExisting table or column being modified (rename, type change, constraint change)
Red borderTable or column being removed
Blue annotationRelationship being added or modified

This visual representation makes it immediately clear which parts of the schema are affected by a change — especially valuable in large schemas where a single AI prompt may touch multiple related tables.

Layer 2: Plan Mode checklist​

In Plan Mode, every change is enumerated as a line item before execution:

Proposed changes (7 items):

  ✓ CREATE TABLE carbon_offset_credits
      — 7 columns, 2 indexes, 1 FK to suppliers
  ✓ ALTER TABLE shipments
      — ADD COLUMN emissions_unit VARCHAR(20) DEFAULT 'kg_co2'
      — ADD COLUMN emissions_kg DECIMAL(10,3)
  ✓ CREATE INDEX idx_carbon_credits_supplier
  ✓ CREATE INDEX idx_carbon_credits_date
  ✓ ALTER TABLE shipments
      — RENAME COLUMN co2_kg TO emissions_kg (after backfill)
  ✗ [excluded by user] ALTER TABLE purchase_orders
      — DROP COLUMN legacy_reference

You can exclude individual items from the checklist before execution. Excluded changes are not applied. This per-item control is what separates TalkingSchema's diff workflow from any one-shot AI tool.

Comparing Two Schema Versions​

To diff two explicit schema versions:

Method 1 — Import and compare​

  1. Import your current production schema (from a live database or DDL file)
  2. Ask the AI: "Here is what I want the target schema to look like: [describe changes]. What is the diff between current and target?"
  3. The AI lists every structural difference and asks for confirmation before generating migration SQL

Method 2 — Paste two DDLs​

Compare these two SQL schemas and produce a structured diff.
Schema A (current): [paste DDL]
Schema B (target): [paste DDL]

List: tables added, tables removed, columns added per table,
columns removed per table, columns altered (name/type/nullability/default),
constraints added or removed, indexes added or removed.
Then generate an ordered migration from A to B.

Method 3 — Live database vs. design​

Connect to your live Supabase or Neon database to import the current state, then design the target state in TalkingSchema. The diff between the two becomes the migration.

Example Diff Report​

After adding the carbon_offset_credits table and making column changes to shipments:

Schema diff — GSSC v1.2 → v1.3
Generated: 2026-03-13

ADDITIONS
─────────
  + TABLE carbon_offset_credits (7 columns)
      credit_id       UUID PK DEFAULT gen_random_uuid()
      supplier_id     UUID FK → suppliers.supplier_id NOT NULL
      credit_date     DATE NOT NULL
      volume_tco2e    DECIMAL(12,4) CHECK (> 0) NOT NULL
      registry        VARCHAR(100) NOT NULL
      certificate_ref VARCHAR(100) UNIQUE NULLABLE
      created_at      TIMESTAMPTZ DEFAULT now()

  + INDEX idx_carbon_credits_supplier ON carbon_offset_credits(supplier_id)
  + INDEX idx_carbon_credits_date ON carbon_offset_credits(credit_date)

  + COLUMN shipments.emissions_unit VARCHAR(20) DEFAULT 'kg_co2'

MODIFICATIONS
─────────────
  ~ COLUMN shipments.co2_kg → emissions_kg
      (rename only; type DECIMAL(10,3) unchanged)

REMOVALS
────────
  (none in this migration)

Impact analysis:
  — carbon_offset_credits: no existing data affected (new table)
  — shipments.emissions_unit: safe addition, nullable until backfill
  — shipments.co2_kg rename: requires application code update
    before the old column name is dropped

Frequently Asked Questions​

Does TalkingSchema detect constraint renames?​

Yes. If a constraint is renamed (e.g., a check constraint or unique constraint), the diff report shows the old and new constraint name. The AI generates a DROP CONSTRAINT + ADD CONSTRAINT sequence as the migration.

How do I diff schemas across two separate projects?​

Open one project, export its SQL DDL, then ask the AI in the second project: "Compare the current schema to this DDL: [paste]. What changed?"

Can the diff be exported as a report document?​

Yes. Ask: "Export the diff as a Markdown report summarizing all schema changes, grouped by table." The AI produces a formatted Markdown document suitable for inclusion in a pull request description or architecture decision record (ADR).