You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit dfd6b69
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/python-api.rst
+8-2Lines changed: 8 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2022,7 +2022,7 @@ Tables referenced by views
2022
2022
2023
2023
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.
2024
2024
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 isnext queried. This is inherent to SQLite views, whose SQLis 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 isnext queried. If you rename or drop columns that a view depends on you should update that view definition yourself.
2026
2026
2027
2027
To achieve this, the SQL produced by ``transform_sql()`` turns on ``PRAGMA legacy_alter_table``for its ``ALTERTABLE...RENAMETO`` 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.
2028
2028
@@ -2031,12 +2031,18 @@ To achieve this, the SQL produced by ``transform_sql()`` turns on ``PRAGMA legac
2031
2031
Custom transformations with .transform_sql()
2032
2032
--------------------------------------------
2033
2033
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.
2035
2039
2036
2040
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(...)``.
2037
2041
2038
2042
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.
2039
2043
2044
+
When renaming a column without ``keep_table=``, restore triggers that were attached to the original table by appending ``CREATETRIGGER`` statements using the new column name.
0 commit comments