Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit dc39dc2b authored by Tyler Gunn's avatar Tyler Gunn
Browse files

Make docs clear that you shouldn't change an existing onUpgrade step. 

Clarifying the API docs to make it clear to the developer the once a
migration step runs, any errors in that step should be corrected by adding
a new migration step instead of modifying the existing step.

Test: Docs only change
Bug: 258831395
Change-Id: I51874bc215a7edfc270eaf4893147e452beb05d3
parent 62229367

core/java/android/database/sqlite/SQLiteOpenHelper.java

+13 −0
Original line number Diff line number Diff line
@@ -513,6 +513,19 @@ public abstract class SQLiteOpenHelper implements AutoCloseable { 
     * This method executes within a transaction.  If an exception is thrown, all changes

     * will automatically be rolled back.

     * </p>

     * <p>

     * <em>Important:</em> You should NOT modify an existing migration step from version X to X+1

     * once a build has been released containing that migration step.  If a migration step has an

     * error and it runs on a device, the step will NOT re-run itself in the future if a fix is made

     * to the migration step.</p>

     * <p>For example, suppose a migration step renames a database column from {@code foo} to

     * {@code bar} when the name should have been {@code baz}.  If that migration step is released

     * in a build and runs on a user's device, the column will be renamed to {@code bar}.  If the

     * developer subsequently edits this same migration step to change the name to {@code baz} as

     * intended, the user devices which have already run this step will still have the name

     * {@code bar}.  Instead, a NEW migration step should be created to correct the error and rename

     * {@code bar} to {@code baz}, ensuring the error is corrected on devices which have already run

     * the migration step with the error.</p>

     *

     * @param db The database.

     * @param oldVersion The old database version.