Docs: correct what transform() does to indexes, views and triggers - #854
Open
dchaudhari7177 wants to merge 1 commit into
Open
Docs: correct what transform() does to indexes, views and triggers#854dchaudhari7177 wants to merge 1 commit into
dchaudhari7177 wants to merge 1 commit into
Conversation
The line under "Custom transformations with .transform_sql()" said
`.transform()` "does not automatically upgrade indexes, views or triggers".
All three parts are wrong, and the trigger one is wrong in the dangerous
direction. Measured on current main:
rename a column triggers ['trg'] -> [] views kept indexes kept
change a type triggers ['trg'] -> [] views kept indexes kept
drop a column triggers ['trg'] -> [] views kept indexes kept
* Indexes *are* handled. `transform_sql()` captures each one before the old
table is dropped and reissues its CREATE INDEX, rewriting a renamed
column: `CREATE INDEX "idx" ON "t" ("new_name")`.
* Views are kept, and were already documented accurately under "Tables
referenced by views" -- so the old sentence also contradicted a section
four paragraphs above it.
* Triggers are not merely "not upgraded". They are **dropped**. SQLite
deletes a table's triggers with the table, and `transform_sql()` never
captures them. A reader told the trigger was not *upgraded* would expect
it to still exist, possibly stale. It is gone.
Replaces the sentence with an "Indexes and triggers" section covering what
actually happens, including the `UNIQUE`-constraint index case (not
reissued, because the constraint is reproduced in the new CREATE TABLE) and
the TransformError raised for any other index without stored SQL.
The trigger part carries a recipe using `table.triggers_dict`, with the
caveat that a captured trigger body still names the old columns. Both the
recipe and every claim above were run against main before being written.
Docs build clean under `sphinx-build -W`.
Closes simonw#849
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #849.
The line under Custom transformations with
.transform_sql()says.transform()"does not automatically upgrade indexes, views or triggers". All three parts are wrong — and the trigger one is wrong in the dangerous direction.Measured on current
main, across all three kinds of transform:transform_sql()captures each one before the old table is dropped and reissues itsCREATE INDEX, rewriting a renamed column:CREATE INDEX "idx" ON "t" ("new_name").transform_sql()never captures them.That last one is why I'd treat this as more than a wording tidy. A reader told a trigger was not upgraded reasonably expects it to still exist, possibly stale. It is gone — silently, on every
transform(), including one called with no arguments to reformat the schema.What replaces it
A short Indexes and triggers section covering what actually happens, including two details I had to read
transform_sql()to get right:CREATE INDEX(one implied by aUNIQUEconstraint) is not reissued, because the constraint is reproduced in the newCREATE TABLEinstead — verified,UNIQUEsurvives;TransformErrortelling you to drop and recreate it yourself.The trigger part carries a recipe using
table.triggers_dict, with the caveat that a captured trigger body still names the old columns.Verification
Everything asserted above was run against
mainbefore being written, including the recipe:The issue also suggested the views wording needed changing. I left the Tables referenced by views section alone — it is already precise, including the
no such columncase — and only removed the stale sentence that contradicted it.Happy to split the trigger behaviour into its own issue if you'd rather
transform()preserved them instead; this PR only documents what it does today.📚 Documentation preview 📚: https://sqlite-utils--854.org.readthedocs.build/en/854/