1## Upgrading SQLite 2 3This document lists the steps needed to upgrade the sources in this repository 4with the latest revision from upstream. 5 6## Source Directory 7 8The upgrade takes place on `aosp-main`. The primary directory is below. 9 10```text 11external/sqlite 12``` 13 14The upgrade steps are: 15 16* Select a version for the upgrade. Note the year it was released by sqlite.org. 17* Find the autoconf amalgamation tarball. For release 3.42.0, the URL is 18 [sqlite-autoconf-3420000.tar.gz](https://sqlite.org/2023/sqlite-autoconf-3420000.tar.gz). 19* Change to the directory `external/sqlite` in the workspace. 20* Run the script `UPDATE-SOURCE.bash`. This script is executable. The 21 arguments are the sqlite release year and the version. Invoke the script without 22 arguments for an example. 23 24`UPDATE-SOURCE.bash` may fail if the Android patch cannot be applied cleanly. If 25this happens, correct the patch failures by hand and rebuild the Android patch 26file. Use the script `REBUILD-ANDROID-PATCH.bash` to rebuild the patch file. 27This script takes a single argument which is the same version number that was 28given to `UPDATE-SOURCE.bash`. Then rerun `UPDATE-SOURCE.bash`. It is important 29that `UPDATE-SOURCE.bash` run without errors. 30 31Once the scripts have completed, there will be a directory containing the new 32source files. The directory is named after the sqlite release and exists in 33parallel with other sqlite release directories. For release 3.42.0, the 34directory name is `external/sqlite/dist/sqlite-autoconf-3420000`. 35 36## Flagging 37 38The release of sqlite can be controlled by trunk-stable build flags. The flag 39is `RELEASE_PACKAGE_LIBSQLITE3`. The value of that flag is the 7-digit sqlite 40release number (e.g., 3420000). Any target that respects trunk-stable flags 41will use the source in `external/sqlite/dist/sqlite-autoconf-FLAG`. Not all 42targets respect the trunk-stable flags, however. Such targets use the directory 43`external/sqlite/dist/sqlite-default`. 44 45A new release of sqlite can be promoted to `trunk` by setting the flag to the 46proper release string. Once a new release of sqlite has been promoted to 47`next`, it is best practice to change the symbolic link `sqlite-default` to 48point to the new release. This ensures that any target that does not honor 49build flags will use the newly promoted release. 50 51Finally, after the new sqlite release has been delivered in an Android update, 52old sqlite release directories can be deleted. 53 54## LICENSE 55 56This file contains the license that allows Android to use the third-party 57software. SQLite is unusual because it has no license: it is in the public 58domain. The current file content is below. 59 60```text 61The author disclaims copyright to this source code. In place of 62a legal notice, here is a blessing: 63 64 May you do good and not evil. 65 May you find forgiveness for yourself and forgive others. 66 May you share freely, never taking more than you give. 67``` 68 69## CTS Version Test 70 71There is a CTS test that verifies the SQLite version. This must be updated as 72well and it must be updated within `aosp-main` at the same time as the source. 73 74```text 75cts/tests/tests/database/src/android/database/sqlite/cts/SQLiteDatabaseTest.java 76``` 77 78Find and update the function `testSqliteLibraryVersion()`. This function must 79be updated as soon as a new sqlite release is installed in `trunk_staging`, and 80the function must accept old and new sqlite releases. Once a new release has 81been committed to `next`, old releases can be rejected by this function. 82 83Note that the CTS test is sometimes propagated to branches for older Android 84releases, which do not use the latest sqlite release. If that happens, the CTS 85test will have to accept both the old and new sqlite releases. 86 87## package.html 88 89```text 90frameworks/base/core/java/android/database/sqlite/package.html 91``` 92 93This is a documentation file that, among other things, maps SQLite versions to 94Android API levels. It should be updated every time SQLite is upgraded and on 95every Android API bump. There is a small problem with API names: Android usually 96prefers not to publicize the new API level until it is official, so care must be 97taken not to expose unofficial API levels through this file. 98 99The current plan for modifying this file when SQLite is upgraded is to add a new 100row, using "latest" as the API level. The file should also be updated 101appropriately when a new API level is formally announced. 102 103This file probably should be modified in an Android branch (not AOSP). That way 104it enters public view with the official release process. 105 106## Recommended Tests 107 108The following tests are recommended before committing an update: 109 110```text 111CtsScopedStorageDeviceOnlyTest 112CtsScopedStorageBypassDatabaseOperationsTest 113CtsScopedStorageGeneralTest 114CtsScopedStorageRedactUriTest 115CtsDatabaseTestCases 116FrameworksCoreTests:android.database 117``` 118 119At the time of writing, there are no test failures in the baseline code. 120