Working with Sugar ORM

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

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

Install & Config

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

Gradle:

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

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

<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/AppTheme"
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">
<intent-filter>
<action android:name="android.intent.action.MAIN" />

<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>

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

• DATABASE: database’s name.
• VERSION: database schema’s version. It is changed when there is a new change in the schema like adding a 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 scans 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;
@Ignore
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.

@Table
public class Publisher {
private Long id;
String name;

public Publisher(){
}

public Publisher(String name){
this.name = name;
}

public Long getId() {
return id;
}
}

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

@Ignore
String note;

Query Builder

The 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:

//Select
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();

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

Data Migration

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

Here are steps to change the database’s structure:

• Create a folder named sugar_upgrades in your assets folder.
• Change the VERSION meta-data value to a new number.
• Create a file named .sql in that folder. The must be set the same as the VERSION meta-data’s number in the 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.