transform() now works for tables referenced by views

Bracket the ALTER TABLE ... RENAME TO statements emitted by
transform_sql() with PRAGMA legacy_alter_table=ON/OFF. Since SQLite
3.25 the rename would otherwise rewrite references in every view
definition, which failed with "no such table" when a view referenced
the just-dropped table, and with keep_table= silently repointed
dependent views at the frozen backup table.

View definitions are now left byte-for-byte unchanged by a transform.

Closes #831

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/changelog.rst

@@ -4,6 +4,13 @@
  Changelog
 ===========
 
+.. _unreleased:
+
+Unreleased
+----------
+
+- ``table.transform()`` now works for tables that are referenced by views. Previously the ``ALTER TABLE ... RENAME TO`` step raised ``no such table`` if a view referenced the table being transformed. View definitions are left unchanged - see :ref:`python_api_transform_views`. This also fixes a bug where ``transform(keep_table=...)`` silently rewrote dependent views to point at the frozen backup table instead of the live one. (:issue:`831`)
+
 .. _v3_39_1:
 
 3.39.1 (2026-07-25)
@@ -18,6 +25,7 @@
 
 - ``table.transform()`` now raises a ``TransactionError`` if called while a transaction is open with ``PRAGMA foreign_keys`` enabled and the table is referenced by foreign keys with destructive ``ON DELETE`` actions - ``CASCADE``, ``SET NULL`` or ``SET DEFAULT``. The pragma cannot be changed inside a transaction, so previously dropping the old table as part of the transform could fire those actions and silently delete or modify referencing rows. See :ref:`python_api_transform_foreign_keys_transactions` for details and workarounds. (:issue:`794`)
 - The :ref:`CLI <cli>` and :ref:`Python API <python_api>` documentation now cross-reference each other: CLI sections link to the equivalent Python API functionality and Python API sections link back to the corresponding CLI command. (:issue:`791`)
+
 .. _v4_1:
 
 4.1 (2026-07-11)

docs/cli.rst

@@ -2288,7 +2288,11 @@ If you want to see the SQL that will be executed to make the change without actu
     INSERT INTO "roadside_attractions_new_4033a60276b9" ("longitude", "latitude", "id", "name")
        SELECT "longitude", "latitude", "pk", "name" FROM "roadside_attractions";
     DROP TABLE "roadside_attractions";
+    PRAGMA legacy_alter_table=ON;
     ALTER TABLE "roadside_attractions_new_4033a60276b9" RENAME TO "roadside_attractions";
+    PRAGMA legacy_alter_table=OFF;
+
+Tables that are referenced by views can be transformed - the view definitions are left unchanged, see :ref:`python_api_transform_views` for details.
 
 .. note::
     In Python: :ref:`table.transform() <python_api_transform>`  CLI reference: :ref:`sqlite-utils transform <cli_ref_transform>`

docs/python-api.rst

@@ -1986,6 +1986,17 @@ A bare column name drops any foreign key that column participates in, including
 
 Renaming a column with ``rename=`` updates any foreign keys that use it, and dropping a column with ``drop=`` also drops any foreign keys it participates in - for a compound foreign key this removes the whole constraint.
 
+.. _python_api_transform_views:
+
+Tables referenced by views
+--------------------------
+
+Tables that are referenced by views can be safely transformed - the view definitions are left byte-for-byte unchanged, and views continue to read from the live table even when ``keep_table=`` is used to keep a copy of the original around.
+
+A view that references a column which the transform renamed or dropped will remain defined but will raise a ``no such column`` error when it is next queried. This is inherent to SQLite views, whose SQL is stored as text - if you rename or drop columns that a view depends on you should update that view definition yourself.
+
+To achieve this, the SQL produced by ``transform_sql()`` brackets its ``ALTER TABLE ... RENAME TO`` statements with ``PRAGMA legacy_alter_table=ON`` and ``PRAGMA legacy_alter_table=OFF`` - without this, SQLite would attempt to rewrite references to the renamed table in every view definition, which fails when a view references the table that was just dropped. One consequence is that ``PRAGMA legacy_alter_table`` is reset to ``OFF`` (the SQLite default) after a transform, even if it was previously set to ``ON`` for the connection.
+
 .. _python_api_transform_sql:
 
 Custom transformations with .transform_sql()