{"id":3576,"url":"https://github.com/jgilfelt/android-sqlite-asset-helper","last_synced_at":"2025-04-13T20:44:53.697Z","repository":{"id":1994176,"uuid":"2927004","full_name":"jgilfelt/android-sqlite-asset-helper","owner":"jgilfelt","description":"An Android helper class to manage database creation and version management using an application's raw asset files","archived":false,"fork":false,"pushed_at":"2021-09-23T14:43:43.000Z","size":1984,"stargazers_count":2143,"open_issues_count":78,"forks_count":539,"subscribers_count":140,"default_branch":"master","last_synced_at":"2025-04-13T20:44:47.931Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgilfelt.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-12-06T18:41:57.000Z","updated_at":"2025-03-27T01:11:49.000Z","dependencies_parsed_at":"2022-09-20T22:01:50.996Z","dependency_job_id":null,"html_url":"https://github.com/jgilfelt/android-sqlite-asset-helper","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgilfelt%2Fandroid-sqlite-asset-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgilfelt%2Fandroid-sqlite-asset-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgilfelt%2Fandroid-sqlite-asset-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgilfelt%2Fandroid-sqlite-asset-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgilfelt","download_url":"https://codeload.github.com/jgilfelt/android-sqlite-asset-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248782280,"owners_count":21160716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-01-05T20:16:45.388Z","updated_at":"2025-04-13T20:44:53.669Z","avatar_url":"https://github.com/jgilfelt.png","language":"Java","funding_links":[],"categories":["Java","Libraries","Libs"],"sub_categories":["Database","\u003cA NAME=\"Orm\"\u003e\u003c/A\u003eOrm"],"readme":"### THIS PROJECT IS NO LONGER MAINTAINED\n\nAndroid SQLiteAssetHelper\n=========================\n\nAn Android helper class to manage database creation and version management using an application's raw asset files.\n\nThis class provides developers with a simple way to ship their Android app with an existing SQLite database (which may be pre-populated with data) and to manage its initial creation and any upgrades required with subsequent version releases.\n\nIt is implemented as an extension to `SQLiteOpenHelper`, providing an efficient way for `ContentProvider` implementations to defer opening and upgrading the database until first use.\n\nRather than implementing the `onCreate()` and `onUpgrade()` methods to execute a bunch of SQL statements, developers simply include appropriately named file assets in their project's `assets` directory. These will include the initial SQLite database file for creation and optionally any SQL upgrade scripts.\n\nSetup\n-----\n\n#### Gradle\n\nIf you are using the Gradle build system, simply add the following dependency in your `build.gradle` file:\n\n```groovy\ndependencies {\n    compile 'com.readystatesoftware.sqliteasset:sqliteassethelper:+'\n}\n```\n\n#### Ant/Eclipse\n\nIf you are using the old build system, download the latest library [JAR][1] and put it in your project's `libs` folder.\n\nUsage\n-----\n\nSQLiteAssetHelper is intended as a drop in alternative for the framework's [SQLiteOpenHelper](https://developer.android.com/reference/android/database/sqlite/SQLiteOpenHelper.html). Please familiarize yourself with the behaviour and lifecycle of that class.\n\nExtend `SQLiteAssetHelper` as you would normally do `SQLiteOpenHelper`, providing the constructor with a database name and version number:\n\n```java\npublic class MyDatabase extends SQLiteAssetHelper {\n\n    private static final String DATABASE_NAME = \"northwind.db\";\n    private static final int DATABASE_VERSION = 1;\n\n    public MyDatabase(Context context) {\n\t    super(context, DATABASE_NAME, null, DATABASE_VERSION);\n    }\n}\n```\n\nSQLiteAssetHelper relies upon asset file and folder naming conventions. Your `assets` folder will either be under your project root, or under `src/main` if you are using the default gradle project structure. At minimum, you must provide the following:\n\n* A `databases` folder inside `assets`\n* A SQLite database inside the `databases` folder whose file name matches the database name you provide in code (including the file extension, if any)\n\nFor the example above, the project would contain the following:\n\n    assets/databases/northwind.db\n\nEarlier versions of this library required the database asset to be compressed within a ZIP archive. This is no longer a requirement, but is still supported. Applications still targeting Gingerbread (API 10) or lower should continue to provide a compressed archive to ensure large database files are not corrupted during the packaging process. The more Linux friendly GZIP format is also supported. The naming conventions using the above example are as follows:\n\n* ZIP: `assets/databases/northwind.db.zip` (a single SQLite database file must be the only file within the archive)\n* GZIP: `assets/databases/northwind.db.gz`\n\nThe database will be extracted from the assets and copied into place within your application's private data directory. If you prefer to store the database file somewhere else (such as external storage) you can use the alternate constructor to specify a storage path. You must ensure that this path is available and writable whenever your application needs to access the database.\n\n```java\nsuper(context, DATABASE_NAME, context.getExternalFilesDir(null).getAbsolutePath(), null, DATABASE_VERSION);\n```\n\nThe database is made available for use the first time either `getReadableDatabase()` or `getWritableDatabase()` is called.\n\nThe class will throw a `SQLiteAssetHelperException` if you do not provide the appropriately named file.\n\nThe SQLiteOpenHelper methods `onConfigure`, `onCreate` and `onDowngrade` are not supported by this implementation and have been declared `final`.\n\nThe [samples:database-v1](https://github.com/jgilfelt/android-sqlite-asset-helper/tree/master/samples/database-v1) project demonstrates a simple database creation and usage example using the classic Northwind database.\n\nDatabase Upgrades\n-----------------\n\nAt a certain point in your application's lifecycle you will need to alter it's database structure to support additional features. You must ensure users who have installed your app prior to this can safely upgrade their local databases without the loss of any locally held data.\n\nTo facilitate a database upgrade, increment the version number that you pass to your `SQLiteAssetHelper` constructor:\n\n```java\nprivate static final int DATABASE_VERSION = 2;\n```\n\nUpdate the initial SQLite database in the project's `assets/databases` directory with the changes and create a text file containing all required SQL commands to upgrade the database from its previous version to it's current version and place it in the same folder. The required naming convention for this upgrade file is as follows:\n\n    assets/databases/\u003cdatabase_name\u003e_upgrade_\u003cfrom_version\u003e-\u003cto_version\u003e.sql\n\nFor example, [northwind.db_upgrade_1-2.sql](https://github.com/jgilfelt/android-sqlite-asset-helper/blob/master/samples/database-v2-upgrade/src/main/assets/databases/northwind.db_upgrade_1-2.sql) upgrades the database named \"northwind.db\" from version 1 to 2. You can include multiple upgrade files to upgrade between any two given versions.\n\nIf there are no files to form an upgrade path from a previously installed version to the current one, the class will throw a `SQLiteAssetHelperException`.\n\nThe [samples:database-v2-upgrade](https://github.com/jgilfelt/android-sqlite-asset-helper/tree/master/samples/database-v2-upgrade) project demonstrates a simple upgrade to the Northwind database which adds a FullName column to the Employee table.\n\n### Generating upgrade scripts\n\nYou can use 3rd party tools to automatically generate the SQL required to modify a database from one schema version to another. One such application is [SQLite Compare Utility](http://www.codeproject.com/KB/database/SQLiteCompareUtility.aspx) for Windows.\n\n### Upgrades via overwrite\n\nIf you have a read-only database or do not care about user data loss, you can force users onto the latest version of the SQLite database each time the version number is incremented (overwriting the local database with the one in the assets) by calling the `setForcedUpgrade()` method in your `SQLiteAsstHelper` subclass constructor. \n\nYou can additionally pass an argument that is the version number below which the upgrade will be forced.\n\nNote that this will overwrite an existing local database and all data within it.\n\nCredits\n-------\n\n####Author:\n\n  * [Jeff Gilfelt](https://github.com/jgilfelt)\n\n#### Contributors:\n\n  * [Alexandros Schillings](https://github.com/alt236)\n  * [Cyril Mottier](https://github.com/cyrilmottier)\n  * [Jon Adams](https://github.com/jon-adams)\n  * [Kevin](https://github.com/kevinchai)\n\nLicense\n-------\n\n    Copyright (C) 2011 readyState Software Ltd\n    Copyright (C) 2007 The Android Open Source Project\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n\n [1]: https://search.maven.org/remote_content?g=com.readystatesoftware.sqliteasset\u0026a=sqliteassethelper\u0026v=LATEST\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgilfelt%2Fandroid-sqlite-asset-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgilfelt%2Fandroid-sqlite-asset-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgilfelt%2Fandroid-sqlite-asset-helper/lists"}