transform(update_incoming_fks=True) and --update-incoming-fks

[simonw]

Summary

Add update_incoming_fks parameter to transform() that automatically updates foreign key constraints in other tables when renaming columns that are referenced by those FKs.

Problem

When renaming a column that is referenced by foreign keys in other tables, the transform fails with a "foreign key mismatch" error (with FK enforcement on) or silently breaks the FK constraints (with FK enforcement off). Users had to manually transform each referencing table first to update their FK constraints before transforming the main table.

Solution

New update_incoming_fks=True parameter for transform() and --update-incoming-fks CLI flag that:

1. Finds all tables with FK constraints pointing to columns being renamed
2. Generates SQL to update those FK constraints to reference the new column names
3. Executes everything in a single transaction (main transform first, then FK updates)
4. Correctly handles self-referential FKs (e.g., employees.manager_id -> employees.id)

Example

# Before: books.author_id REFERENCES authors(id)
db["authors"].transform(
    rename={"id": "author_pk"},
    update_incoming_fks=True,
)
# After: books.author_id REFERENCES authors(author_pk)

Investigation notes: https://github.com/simonw/sqlite-utils/blob/c727ceab0763ff02fe10da720f427db5e9693e4e/TRANSFORM_FK_INVESTIGATION.md

[codecov]

Codecov Report

❌ Patch coverage is 98.03922% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 95.17%. Comparing base (8d74ffc) to head (8bddd3c).

Files with missing lines	Patch %	Lines
sqlite_utils/db.py	97.82%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #703      +/-   ##
==========================================
+ Coverage   95.15%   95.17%   +0.02%     
==========================================
  Files           8        8              
  Lines        3114     3153      +39     
==========================================
+ Hits         2963     3001      +38     
- Misses        151      152       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.