LitePal 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.
Experience the magic right now and have fun!
- Using object-relational mapping (ORM) pattern.
- Almost zero-configuration(only one configuration file with few properties).
- Maintains all tables automatically(e.g. create, alter or drop tables).
- Multi databases supported.
- Encapsulated APIs for avoiding writing SQL statements.
- Awesome fluent query API.
- Alternative choice to use SQL still, but easier and better APIs than the originals.
- More for you to explore.
Edit your build.gradle file and add below dependency.
If you program with Java:
dependencies {
implementation 'org.litepal.android:java:3.0.0'
}If you program with Kotlin:
dependencies {
implementation 'org.litepal.android:kotlin:3.0.0'
}Create a file in the assets folder of your project and name it as litepal.xml. Then copy the following codes into it.
<?xml version="1.0" encoding="utf-8"?>
<litepal>
<!--
Define the database name of your application.
By default each database name should be end with .db.
If you didn't name your database end with .db,
LitePal would plus the suffix automatically for you.
For example:
<dbname value="demo" />
-->
<dbname value="demo" />
<!--
Define the version of your database. Each time you want
to upgrade your database, the version tag would helps.
Modify the models you defined in the mapping tag, and just
make the version value plus one, the upgrade of database
will be processed automatically without concern.
For example:
<version value="1" />
-->
<version value="1" />
<!--
Define your models in the list with mapping tag, LitePal will
create tables for each mapping class. The supported fields
defined in models will be mapped into columns.
For example:
<list>
<mapping class="com.test.model.Reader" />
<mapping class="com.test.model.Magazine" />
</list>
-->
<list>
</list>
<!--
Define where the .db file should be. "internal" means the .db file
will be stored in the database folder of internal storage which no
one can access. "external" means the .db file will be stored in the
path to the directory on the primary external storage device where
the application can place persistent files it owns which everyone
can access. "internal" will act as default.
For example:
<storage value="external" />
-->
</litepal>This is the only configuration file, and the properties are simple.
- dbname configure the database name of project.
- version configure the version of database. Each time you want to upgrade database, plus the value here.
- list configure the mapping classes.
- storage configure where the database file should be stored. internal and external are the only valid options.
You 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:
<manifest>
<application
android:name="org.litepal.LitePalApplication"
...
>
...
</application>
</manifest>Of course you may have your own Application and has already configured here, like:
<manifest>
<application
android:name="com.example.MyOwnApplication"
...
>
...
</application>
</manifest>That's OK. LitePal can still live with that. Just call LitePal.initialize(context) in your own Application:
public class MyOwnApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
LitePal.initialize(this);
}
...
}Make 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.
After setup, you can experience the powerful functions now.
Define the models first. For example you have two models, Album and Song. The models can be defined as below:
public class Album extends LitePalSupport {
@Column(unique = true, defaultValue = "unknown")
private String name;
private float price;
private byte[] cover;
private List<Song> songs = new ArrayList<Song>();
// generated getters and setters.
...
}public class Song extends LitePalSupport {
@Column(nullable = false)
private String name;
private int duration;
@Column(ignore = true)
private String uselessField;
private Album album;
// generated getters and setters.
...
}Then add these models into the mapping list in litepal.xml:
<list>
<mapping class="org.litepal.litepalsample.model.Album" />
<mapping class="org.litepal.litepalsample.model.Song" />
</list>OK! The tables will be generated next time you operate database. For example, gets the SQLiteDatabase with following codes:
SQLiteDatabase db = LitePal.getDatabase();Now the tables will be generated automatically with SQLs like this:
CREATE TABLE album (
id integer primary key autoincrement,
name text unique default 'unknown',
price real,
cover blob
);
CREATE TABLE song (
id integer primary key autoincrement,
name text not null,
duration integer,
album_id integer
);Upgrade tables in LitePal is extremely easy. Just modify your models anyway you want:
public class Album extends LitePalSupport {
@Column(unique = true, defaultValue = "unknown")
private String name;
@Column(ignore = true)
private float price;
private byte[] cover;
private Date releaseDate;
private List<Song> songs = new ArrayList<Song>();
// generated getters and setters.
...
}A releaseDate field was added and price field was annotated to ignore. Then increase the version number in litepal.xml:
<!--
Define the version of your database. Each time you want
to upgrade your database, the version tag would helps.
Modify the models you defined in the mapping tag, and just
make the version value plus one, the upgrade of database
will be processed automatically without concern.
For example:
<version value="1" />
-->
<version value="2" />