{"id":15034072,"url":"https://github.com/guolindev/litepal","last_synced_at":"2025-05-14T06:06:53.899Z","repository":{"id":7030884,"uuid":"8305132","full_name":"guolindev/LitePal","owner":"guolindev","description":"An Android library that makes developers use SQLite database extremely easy.","archived":false,"fork":false,"pushed_at":"2022-08-19T08:29:56.000Z","size":5433,"stargazers_count":8105,"open_issues_count":95,"forks_count":1587,"subscribers_count":288,"default_branch":"master","last_synced_at":"2024-10-29T15:35:59.478Z","etag":null,"topics":["android","litepal","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"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/guolindev.png","metadata":{"files":{"readme":"README.md","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":"2013-02-20T03:20:07.000Z","updated_at":"2024-10-29T08:01:40.000Z","dependencies_parsed_at":"2022-08-02T20:45:13.761Z","dependency_job_id":null,"html_url":"https://github.com/guolindev/LitePal","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guolindev%2FLitePal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guolindev%2FLitePal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guolindev%2FLitePal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guolindev%2FLitePal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guolindev","download_url":"https://codeload.github.com/guolindev/LitePal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312994,"owners_count":21082784,"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":["android","litepal","sqlite3"],"created_at":"2024-09-24T20:23:50.143Z","updated_at":"2025-04-10T23:21:01.737Z","avatar_url":"https://github.com/guolindev.png","language":"Java","readme":"# LitePal for Android  \n![Logo](https://github.com/LitePalFramework/LitePal/blob/master/sample/src/main/logo/mini_logo.png) \n\n[中文文档](https://blog.csdn.net/sinyu890807/category_9262963.html)\n\nLitePal is an open source Android library that allows developers to use SQLite database extremely easy. You can finish most of the database operations without writing even a SQL statement, including create or upgrade tables, crud operations, aggregate functions, etc. The setup of LitePal is quite simple as well, you can integrate it into your project in less than 5 minutes. \n\nExperience the magic right now and have fun!\n\n## Features\n * Using object-relational mapping (ORM) pattern.\n * Almost zero-configuration(only one configuration file with few properties).\n * Maintains all tables automatically(e.g. create, alter or drop tables).\n * Multi databases supported.\n * Encapsulated APIs for avoiding writing SQL statements.\n * Awesome fluent query API.\n * Alternative choice to use SQL still, but easier and better APIs than the originals.\n * More for you to explore.\n\n## Quick Setup\n#### 1. Include library\n\nEdit your **build.gradle** file and add below dependency.\n\n``` groovy\ndependencies {\n    implementation 'org.litepal.guolindev:core:3.2.3'\n}\n```\n\n#### 2. Configure litepal.xml\nCreate a file in the **assets** folder of your project and name it as **litepal.xml**. Then copy the following codes into it.\n``` xml\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n\u003clitepal\u003e\n    \u003c!--\n    \tDefine the database name of your application. \n    \tBy default each database name should be end with .db. \n    \tIf you didn't name your database end with .db, \n    \tLitePal would plus the suffix automatically for you.\n    \tFor example:    \n    \t\u003cdbname value=\"demo\" /\u003e\n    --\u003e\n    \u003cdbname value=\"demo\" /\u003e\n\n    \u003c!--\n    \tDefine the version of your database. Each time you want \n    \tto upgrade your database, the version tag would helps.\n    \tModify the models you defined in the mapping tag, and just \n    \tmake the version value plus one, the upgrade of database\n    \twill be processed automatically without concern.\n\t\t\tFor example:    \n    \t\u003cversion value=\"1\" /\u003e\n    --\u003e\n    \u003cversion value=\"1\" /\u003e\n\n    \u003c!--\n    \tDefine your models in the list with mapping tag, LitePal will\n    \tcreate tables for each mapping class. The supported fields\n    \tdefined in models will be mapped into columns.\n    \tFor example:    \n    \t\u003clist\u003e\n    \t\t\u003cmapping class=\"com.test.model.Reader\" /\u003e\n    \t\t\u003cmapping class=\"com.test.model.Magazine\" /\u003e\n    \t\u003c/list\u003e\n    --\u003e\n    \u003clist\u003e\n    \u003c/list\u003e\n    \n    \u003c!--\n        Define where the .db file should be. \"internal\" means the .db file\n        will be stored in the database folder of internal storage which no\n        one can access. \"external\" means the .db file will be stored in the\n        path to the directory on the primary external storage device where\n        the application can place persistent files it owns which everyone\n        can access. \"internal\" will act as default.\n        For example:\n        \u003cstorage value=\"external\" /\u003e\n    --\u003e\n    \n\u003c/litepal\u003e\n```\nThis is the only configuration file, and the properties are simple. \n * **dbname** configure the database name of project.\n * **version** configure the version of database. Each time you want to upgrade database, plus the value here.\n * **list** configure the mapping classes.\n * **storage** configure where the database file should be stored. **internal** and **external** are the only valid options.\n \n#### 3. Configure LitePalApplication\nYou don't want to pass the Context param all the time. To makes the APIs simple, just configure the LitePalApplication in **AndroidManifest.xml** as below:\n``` xml\n\u003cmanifest\u003e\n    \u003capplication\n        android:name=\"org.litepal.LitePalApplication\"\n        ...\n    \u003e\n        ...\n    \u003c/application\u003e\n\u003c/manifest\u003e\n```\nOf course you may have your own Application and has already configured here, like:\n``` xml\n\u003cmanifest\u003e\n    \u003capplication\n        android:name=\"com.example.MyOwnApplication\"\n        ...\n    \u003e\n        ...\n    \u003c/application\u003e\n\u003c/manifest\u003e\n```\nThat's OK. LitePal can still live with that. Just call **LitePal.initialize(context)** in your own Application:\n```java\npublic class MyOwnApplication extends Application {\n\n    @Override\n    public void onCreate() {\n        super.onCreate();\n        LitePal.initialize(this);\n    }\n    ...\n}\n```\nMake sure to call this method as early as you can. In the **onCreate()** method of Application will be fine. And always remember to use the application context as parameter. Do not use any instance of activity or service as parameter, or memory leaks might happen.\n## Get Started\nAfter setup, you can experience the powerful functions now.\n\n#### 1. Create tables\nDefine the models first. For example you have two models, **Album** and **Song**. The models can be defined as below:\n``` java\npublic class Album extends LitePalSupport {\n\t\n    @Column(unique = true, defaultValue = \"unknown\")\n    private String name;\n    \n    @Column(index = true)\n    private float price;\n\t\n    private List\u003cSong\u003e songs = new ArrayList\u003c\u003e();\n\n    // generated getters and setters.\n    ...\n}\n```\n``` java\npublic class Song extends LitePalSupport {\n\t\n    @Column(nullable = false)\n    private String name;\n\t\n    private int duration;\n\t\n    @Column(ignore = true)\n    private String uselessField;\n\t\n    private Album album;\n\n    // generated getters and setters.\n    ...\n}\n```\nThen add these models into the mapping list in **litepal.xml**:\n``` xml\n\u003clist\u003e\n    \u003cmapping class=\"org.litepal.litepalsample.model.Album\" /\u003e\n    \u003cmapping class=\"org.litepal.litepalsample.model.Song\" /\u003e\n\u003c/list\u003e\n```\nOK! The tables will be generated next time you operate database. For example, gets the **SQLiteDatabase** with following codes:\n``` java\nSQLiteDatabase db = LitePal.getDatabase();\n```\nNow the tables will be generated automatically with SQLs like this:\n``` sql\nCREATE TABLE album (\n\tid integer primary key autoincrement,\n\tname text unique default 'unknown',\n\tprice real\n);\n\nCREATE TABLE song (\n\tid integer primary key autoincrement,\n\tname text not null,\n\tduration integer,\n\talbum_id integer\n);\n```\n\n#### 2. Upgrade tables\nUpgrade tables in LitePal is extremely easy. Just modify your models anyway you want:\n```java\npublic class Album extends LitePalSupport {\n\t\n    @Column(unique = true, defaultValue = \"unknown\")\n    private String name;\n\t\n    @Column(ignore = true)\n    private float price;\n\t\n    private Date releaseDate;\n\t\n    private List\u003cSong\u003e songs = new ArrayList\u003c\u003e();\n\n    // generated getters and setters.\n    ...\n}\n```\nA **releaseDate** field was added and **price** field was annotated to ignore.\nThen increase the version number in **litepal.xml**:\n```xml\n\u003c!--\n    Define the version of your database. Each time you want \n    to upgrade your database, the version tag would helps.\n    Modify the models you defined in the mapping tag, and just \n    make the version value plus one, the upgrade of database\n    will be processed automatically without concern.\n    For example:    \n    \u003cversion value=\"1\" /\u003e\n--\u003e\n\u003cversion value=\"2\" /\u003e\n```\nThe tables will be upgraded next time you operate database. A **releasedate** column will be added into **album** table and the original **price** column will be removed. All the data in **album** table except those removed columns will be retained.\n\nBut there are some upgrading conditions that LitePal can't handle and all data in the upgrading table will be cleaned:\n * Add a field which annotated as `unique = true`.\n * Change a field's annotation into `unique = true`.\n * Change a field's annotation into `nullable = false`.\n\nBe careful of the above conditions which will cause losing data.\n\n#### 3. Save data\nThe saving API is quite object oriented. Each model which inherits from **LitePalSupport** would have the **save()** method for free.\n\nJava:\n``` java\nAlbum album = new Album();\nalbum.setName(\"album\");\nalbum.setPrice(10.99f);\nalbum.setCover(getCoverImageBytes());\nalbum.save();\nSong song1 = new Song();\nsong1.setName(\"song1\");\nsong1.setDuration(320);\nsong1.setAlbum(album);\nsong1.save();\nSong song2 = new Song();\nsong2.setName(\"song2\");\nsong2.setDuration(356);\nsong2.setAlbum(album);\nsong2.save();\n```\n\nKotlin:\n```kotlin\nval album = Album()\nalbum.name = \"album\"\nalbum.price = 10.99f\nalbum.cover = getCoverImageBytes()\nalbum.save()\nval song1 = Song()\nsong1.name = \"song1\"\nsong1.duration = 320\nsong1.album = album\nsong1.save()\nval song2 = Song()\nsong2.name = \"song2\"\nsong2.duration = 356\nsong2.album = album\nsong2.save()\n```\nThis will insert album, song1 and song2 into database with associations.\n\n#### 4. Update data\nThe simplest way, use **save()** method to update a record found by **find()**.\n\nJava:\n``` java\nAlbum albumToUpdate = LitePal.find(Album.class, 1);\nalbumToUpdate.setPrice(20.99f); // raise the price\nalbumToUpdate.save();\n```\n\nKotlin:\n```kotlin\nval albumToUpdate = LitePal.find\u003cAlbum\u003e(1)\nalbumToUpdate.price = 20.99f // raise the price\nalbumToUpdate.save()\n```\n\nEach model which inherits from **LitePalSupport** would also have **update()** and **updateAll()** method. You can update a single record with a specified id.\n\nJava:\n``` java\nAlbum albumToUpdate = new Album();\nalbumToUpdate.setPrice(20.99f); // raise the price\nalbumToUpdate.update(id);\n```\n\nKotlin:\n```kotlin\nval albumToUpdate = Album()\nalbumToUpdate.price = 20.99f // raise the price\nalbumToUpdate.update(id)\n```\n\nOr you can update multiple records with a where condition.\n\nJava:\n``` java\nAlbum albumToUpdate = new Album();\nalbumToUpdate.setPrice(20.99f); // raise the price\nalbumToUpdate.updateAll(\"name = ?\", \"album\");\n```\n\nKotlin:\n```kotlin\nval albumToUpdate = Album()\nalbumToUpdate.price = 20.99f // raise the price\nalbumToUpdate.updateAll(\"name = ?\", \"album\")\n```\n\n#### 5. Delete data\nYou can delete a single record using the static **delete()** method in **LitePal**.\n\nJava:\n``` java\nLitePal.delete(Song.class, id);\n```\n\nKotlin:\n```kotlin\nLitePal.delete\u003cSong\u003e(id)\n```\n\nOr delete multiple records using the static **deleteAll()** method in **LitePal**.\n\nJava:\n``` java\nLitePal.deleteAll(Song.class, \"duration \u003e ?\" , \"350\");\n```\n\nKotlin:\n```kotlin\nLitePal.deleteAll\u003cSong\u003e(\"duration \u003e ?\" , \"350\")\n```\n\n#### 6. Query data\nFind a single record from song table with specified id.\n\nJava:\n``` java\nSong song = LitePal.find(Song.class, id);\n```\n\nKotlin:\n```kotlin\nval song = LitePal.find\u003cSong\u003e(id)\n```\n\nFind all records from song table.\n\nJava:\n``` java\nList\u003cSong\u003e allSongs = LitePal.findAll(Song.class);\n```\n\nKotlin:\n```kotlin\nval allSongs = LitePal.findAll\u003cSong\u003e()\n```\n\nConstructing complex query with fluent query.\n\nJava:\n``` java\nList\u003cSong\u003e songs = LitePal.where(\"name like ? and duration \u003c ?\", \"song%\", \"200\").order(\"duration\").find(Song.class);\n```\n\nKotlin:\n``` kotlin\nval songs = LitePal.where(\"name like ? and duration \u003c ?\", \"song%\", \"200\").order(\"duration\").find\u003cSong\u003e()\n```\n\n#### 7. Multiple databases\nIf your app needs multiple databases, LitePal support it completely. You can create as many databases as you want at runtime. For example:\n```java\nLitePalDB litePalDB = new LitePalDB(\"demo2\", 1);\nlitePalDB.addClassName(Singer.class.getName());\nlitePalDB.addClassName(Album.class.getName());\nlitePalDB.addClassName(Song.class.getName());\nLitePal.use(litePalDB);\n```\nThis will create a **demo2** database with **singer**, **album** and **song** tables.\n\nIf you just want to create a new database but with same configuration as **litepal.xml**, you can do it with:\n```java\nLitePalDB litePalDB = LitePalDB.fromDefault(\"newdb\");\nLitePal.use(litePalDB);\n```\nYou can always switch back to default database with:\n```java\nLitePal.useDefault();\n```\nAnd you can delete any database by specified database name:\n```java\nLitePal.deleteDatabase(\"newdb\");\n```\n\n#### 8. Transaction\nLitePal support transaction for atomic db operations. All operations in the transaction will be committed or rolled back together.\n\nJava usage:\n```java\nLitePal.beginTransaction();\nboolean result1 = // db operation1\nboolean result2 = // db operation2\nboolean result3 = // db operation3\nif (result1 \u0026\u0026 result2 \u0026\u0026 result3) {\n    LitePal.setTransactionSuccessful();\n}\nLitePal.endTransaction();\n```\n\nKotlin usage:\n```kotlin\nLitePal.runInTransaction {\n    val result1 = // db operation1\n    val result2 = // db operation2\n    val result3 = // db operation3\n    result1 \u0026\u0026 result2 \u0026\u0026 result3\n}\n```\n\n## ProGuard\nIf you are using ProGuard you might need to add the following option:\n\n```proguard\n-keep class org.litepal.** {*;}\n-keep class * extends org.litepal.crud.LitePalSupport {*;}\n```\n\n## Bugs Report\nIf you find any bug when using LitePal, please report **[here](https://github.com/LitePalFramework/LitePal/issues/new)**. Thanks for helping us making better.\n\n## Change logs\n\n### 3.2.3\n * Support database index by adding @Column(index = true) on field.\n * Adding return value for **runInTransaction()** function for Kotlin.\n * Fix known bugs.\n\n### 3.1.1\n * Support transaction.\n * Add return value for **LitePal.saveAll()** method.\n * No longer support byte array field as column in table.\n * Deprecate all async methods. You should handle async operations by yourself.\n * Fix known bugs.\n \n### 3.0.0\n * Optimize generic usage for async operation APIs.\n * Add **LitePal.registerDatabaseListener()** method for listening create or upgrade database events.\n * Provider better CRUD API usage for using generic declaration instead of Class parameter for kotlin.\n * Fix known bugs.\n\n### 2.0.0\n * Offer new APIs for CRUD operations. Deprecate **DataSupport**, use **LitePal** and **LitePalSupport** instead.\n * Fully support kotlin programming.\n * Fix known bugs.\n\n### 1.6.1\n * Support AES and MD5 encryption with @Encrypt annotation on fields.\n * Support to store database file on any directory of external storage.\n * Fix known bugs.\n\n### 1.5.1\n * Support async operations for all crud methods.\n * Add **saveOrUpdate()** method in DataSupport.\n * Fix known bugs.\n\n### 1.4.1\n * Support multiple databases.\n * Support crud operations for generic collection data in models.\n * Add SQLite keywords convert function to avoid keywords conflict.\n * Fix bug of DateSupport.count error.\n * Fix bug of losing blob data when upgrading database.\n * Fix other known bugs.\n \n### 1.3.2\n * Improve an outstanding speed up of querying and saving.\n * Support to store database file in external storage.\n * Support to mapping fields which inherit from superclass.\n * Add **findFirst()** and **findLast()** in fluent query.\n * Add **isExist()** and **saveIfNotExist()** method in DataSupport.\n\n### 1.3.1\n * Support storing binary data. Byte array field will be mapped into database as blob type.\n * Add **saveFast()** method in DataSupport. If your model has no associations to handle, use **saveFast()** method will be much more efficient.\n * Improve query speed with optimized algorithm.\n \n### 1.3.0\n * Add annotation functions to declare **unique**, **not null** and **default** constraints.\n * Remove the trick of ignore mapping fields with non-private modifier.\n * Support to use annotation to ignore mapping fields with `ignore = true`\n * Add some magical methods in DataSupport for those who understand LitePal deeper.\n * Fix known bugs.\n \n## License\n```\nCopyright (C) Lin Guo, LitePal Framework Open Source Project\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n     http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguolindev%2Flitepal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguolindev%2Flitepal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguolindev%2Flitepal/lists"}