Skip to content

Commit dfd6b69

Browse files
Clarify transform behavior for indexes, views, and triggers
1 parent 6bc1d33 commit dfd6b69

1 file changed

Lines changed: 8 additions & 2 deletions

File tree

‎docs/python-api.rst‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2022,7 +2022,7 @@ Tables referenced by views
20222022
20232023
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.
20242024
2025-
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.
2025+
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. If you rename or drop columns that a view depends on you should update that view definition yourself.
20262026
20272027
To achieve this, the SQL produced by ``transform_sql()`` turns on ``PRAGMA legacy_alter_table`` for its ``ALTER TABLE ... RENAME TO`` statements, then restores the pragma to the value it had when the SQL was generated - 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.
20282028
@@ -2031,12 +2031,18 @@ To achieve this, the SQL produced by ``transform_sql()`` turns on ``PRAGMA legac
20312031
Custom transformations with .transform_sql()
20322032
--------------------------------------------
20332033
2034-
The ``.transform()`` method can handle most cases, but it does not automatically upgrade indexes, views or triggers associated with the table that is being transformed.
2034+
The ``.transform()`` method rebuilds the table, including when called with ``rename=``. This has different effects on indexes, views and triggers:
2035+
2036+
* Explicit indexes are recreated. Simple indexes are updated to refer to renamed columns. Dropping a column used by an explicit index raises ``TransformError``, as does renaming or dropping any column on a table with a partial or expression index. Drop these indexes before calling ``.transform()`` or ``.transform_sql()``, then recreate them with the required changes after executing the transformation.
2037+
* View definitions are left unchanged. See :ref:`python_api_transform_views` for what happens when a view references a renamed or dropped column.
2038+
* Triggers attached to the table are dropped with the original table and are not recreated. With ``keep_table=``, they remain attached to the retained original table, not the transformed table. Triggers attached to other tables are left unchanged, so references in their bodies to renamed or dropped columns need to be updated manually.
20352039
20362040
If you want to do something more advanced, you can call the ``table.transform_sql(...)`` method with the same arguments that you would have passed to ``table.transform(...)``.
20372041
20382042
This method will return a list of SQL statements that should be executed to implement the change. You can then make modifications to that SQL - or add additional SQL statements - before executing it yourself.
20392043
2044+
When renaming a column without ``keep_table=``, restore triggers that were attached to the original table by appending ``CREATE TRIGGER`` statements using the new column name.
2045+
20402046
.. _python_api_transform_foreign_keys_transactions:
20412047
20422048
Foreign keys and transactions

0 commit comments

Comments
 (0)