Clarify transform() behavior for indexes, views and triggers
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 92/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- python
- Domain
- documentation
Research direction
Start in docs/python-api.rst at the “Custom transformations with .transform_sql()” section, then compare it with the existing “Tables referenced by views” section. Update the contradictory paragraph so it accurately distinguishes index recreation, safe transformations of tables referenced by views, unchanged view definitions, and triggers requiring manual updates; done when the two sections no longer conflict.
Written by the indexing model from the issue text.
Description
The documentation for transform_sql() appears to be slightly out of date.
In the “Custom transformations with .transform_sql()” section, it currently says:
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.
That is now misleading for indexes and views:
- Indexes on renamed columns are recreated using the new column name.
- Tables referenced by views can be transformed safely.
- View definitions are kept unchanged and continue to point to the live table.
- Triggers are not automatically updated, so that part of the warning is still useful.
I verified this against the current main branch with a table containing an index and a dependent view. After renaming a column with transform(rename=...), the index was recreated against the new column name and the view remained unchanged and queryable when it only referenced an unaffected column.
Could this paragraph be updated to clarify the current behavior? For example:
The .transform() method preserves and recreates indexes where possible, and tables referenced by views can be transformed without repointing those views. View definitions and triggers are not automatically rewritten when their referenced columns change, so those definitions may need to be updated manually.
The existing “Tables referenced by views” section already documents much of this behavior, so this would mainly remove the contradiction between the two sections.
References:
- Dominant language
- Python
- Stars
- 2.2k
- Forks
- 172
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from simonw/sqlite-utils
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
simonw/sqlite-utils#872 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
simonw/sqlite-utils#857 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
simonw/sqlite-utils#588 · 4 comments · 1 reaction ·
-
bug documentation help wanted
Difficulty 1/5 Under an hour Newbie friendliness 88/100
simonw/sqlite-utils#493 · 5 comments ·
-
Difficulty 3/5 1-2 days Newbie friendliness 85/100
simonw/sqlite-utils#870 ·
All issues in simonw/sqlite-utils
Similar issues
-
documentation help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100