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.
Hi, is it some way to set column as index in sugar record?
Sorry, I don’t know about that.
Hi!
Do you know how to work in Sugar ORM with composite keys?
I have a table with 5 fields and two of those fields are a compound key.
Is there any @annotation for this?
You can try uniqueCombo.
http://ormlite.com/javadoc/ormlite-core/doc-files/ormlite_2.html#index-uniqueCombo