Working with Sugar ORM

Sugar ORM is a database persistence library that provides a clear and simple APIs for SQLite database operations. Sugar ORM is simple and easy to setup compared to other Android ORM libraries like ActiveAndroid or DBFlow.

The below guide works with Sugar ORM 1.4. Versions before 1.4 has a different way of defining a model.

Install & Config

You can either download the library’s jar file and add it to libs folder or use Gradle to install it.


compile 'com.github.satyan:sugar:1.4'

Add android:name=”com.orm.SugarApp” to application tag and database’s definition within that tag.

        android:name="com.orm.SugarApp" >

        <meta-data android:name="DATABASE" android:value="sugardb.db" />
        <meta-data android:name="VERSION" android:value="1" />
        <meta-data android:name="QUERY_LOG" android:value="true" />
        <meta-data android:name="DOMAIN_PACKAGE_NAME" android:value="com.androidnames.sugarormexample" />

        <activity android:name=".MainActivity">
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />

There are 4 meta-data tag which can be sued to define a database’s info.

  • DATABASE: database’s name.
  • VERSION: database schema’s version. It is changed when there is new change in the schema like adding new table or column.
  • QUERY_LOG: determines whether to log debug messages. It can be either true or false.
  • DOMAIN_PACKAGE_NAME: It is used to specify which package Sugar ORM scan for model classes.

Create Entities and Properties

There are two ways to define a persistent entity.

1) Extend SugarRecord
An empty constructor is required.

public class ComicBook extends SugarRecord {

    String title;
    String publication_name;
    float price;
    String note;

    public ComicBook(){}

    public ComicBook(String title, String publication_name, float price){
        this.title = title;
        this.publication_name = publication_name;
        this.price = price;


2) Use annotation @Table
You must define a private Long id field following this method.

public class Publisher {
    private Long id;
    String name;

    public Publisher(){

    public Publisher(String name){ = name;

    public Long getId() {
        return id;

You can use annotation @Ignore to skip a property from persisting.

String note;

Query Builder

find method is often used to prepare all queries.

//full query
find(Class<T> type, String whereClause, String[] whereArgs, String groupBy, String orderBy, String limit)

Some examples:

ComicBook book = ComicBook.findById(ComicBook.class, 1);
List<ComicBook> books1 = ComicBook.find(ComicBook.class, "publication_name = ?", publication_name);
List<ComicBook> books2 = ComicBook.listAll(ComicBook.class);
List<ComicBook> books3 = Select.from(ComicBook.class).where(Condition.prop("publication_name").eq("Marvel"),Condition.prop("price").eq(10)).list();

ComicBook cb = new ComicBook("A Book Name","A Publisher Name" , 100);;
Publisher.deleteAll(Publisher.class, "name = ?", "A Publisher Name");

Data Migration

Sugar ORM provides an easy way to update database’s schema. You should use it when you need to alter existing tables and columns’s data.

Here are steps to change database’s structure:

  • Create a folder named sugar_upgrades in your assets folder.
  • Change VERSION meta-data value to a new number.
  • Create a file named .sql in that folder. The must be set the same as VERSION meta-data’s number in AndroidManifest file.

Sugar ORM automatically creates fields for existing tables when you add new fields to your Sugar models so you don’t need to add new fields in sql script.