https://github.com/realm/realm-java
In today's tutorial, we are going to be learning Migrations in Realm Database. Similar to working with any database, you are likely to change your model class which sometimes is called database schema overtime. Since model classes in Realm are as easy as defining standard objects, changing schemas is easy.
In order for Realm to be able to handle your change in your schema, Migrations are neccesary, meaning migrating from the Schema configuration saved in Realm to the new one you must altered which can be done adding a new field to your model class.
To understanding the concept behind Migration, we are going to be creating an android application which we will be defining a Model class at the beginning and then adding a new field once we have run the application once and then we will Migrate to the new Model class configuration.
The ButterKnife dependency should be placed in your application level gradle file - "build.gradle" which will make the injection of views (e.g ImageView, TextView) as easy as possible which we will be seeing in this tutorial.
The lombok dependency also is placed in the application level gradle file which makes the generator of getter and setter methods for our model classes by just adding the annotations @Getter for getters and @Setter for the setter methods.
Realm dependency
Steps
Head to your project level gradle file and add the classpath dependency:
classpath "io.realm:realm-gradle-plugin:5.1.0"
Next, head to your application level Gradle file "build.gradle" and add the realm-android plugin to the top of the file.
apply plugin:'realm-android'
Finally, refresh your Gradle dependencies.
After you have added the necessary dependencies, your application level Gradle file should look like this :
And your project level Gradle file should look like this :
In order for us to show the result of our migrations in our tutorial, we are going to be adding one TextView in our activity_main.xml file :
<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".Activities.MainActivity">
<TextView
android:id="@+id/result"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:padding="10dp"
android:layout_centerInParent="true"
android:text="Hello World!" />
</RelativeLayout>
Code Explanation
The above code includes a TextView in our layout file with the id - result and places the text right in the center of the screen with - android:layout_centerInParent="true" and has a padding of 10 on every side - android:padding="10dp".
Next, we are going to create a new java class file which can be done by right-clicking on java folder => New => Java class and then input the name the class Person.
Step 1
Step 2
Next, let the Person class extend the RealmObject class and add the following fields - name (String) , age (int) and then we add the annotations @Getter and @Setter using lombok in order to inject our getter and setter methods, this way boilerplate are eliminated.
@Getter
@Setter
public class Person extends RealmObject {
private String name;
private int age;
}
In order for us to illustrate Realm Migration, we are going to be creating a realm database using a custom configuration where we are going to be specifying a schemaVerson and a Migration class that will run automatically if Migration is needed.
Migration helps you to change your realm file configuration while you retain the details in your realm database.
In order to illustrate Migration in our MainActivity.java class file, we are going to be creating a custom Realm Configuration , specify its schemaVersion and the Migration method.
Firstly, we have to create a Realm variable - private Realm realm; and then add the following codes in our onCreate() method
Realm.init(this);
RealmConfiguration customConfig = new RealmConfiguration.Builder()
.schemaVersion(1) // Must be bumped when the schema changes
.migration(new NewMigration())
.build()
realm = Realm.getInstance(customConfig);
createRealmObjects();
private class NewMigration implements RealmMigration {
@Override
public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {
RealmSchema schema = realm.getSchema();
if (oldVersion == 0) {
schema.create("Person")
.addField("name", String.class)
.addField("age", int.class);
oldVersion++;
}
}
Code Explanation
Realm.init(this);customConfig and then we indicate the schemaVerson as 1 and also specify the configuration method as NewMigration() which will be ran automatically once a Migration is needed.customConfig as its configuration - realm = Realm.getInstance(customConfig);.migrate() method and use the DynamicRealm argument to get an editable schema - RealmSchema schema = realm.getSchema();.Person schema and add the fields - name and age specifying their datatypes - String.class and int.class respectively.oldVersion++.createRealmObjects()
private void createRealmObjects() {
realm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
Person Eben = realm.createObject(Person.class);
Eben.setName("Ebenezer");
Eben.setAge(27);
Person Jude = realm.createObject(Person.class);
Jude.setAge(31);
Jude.setName("Yanbor Jude");
}
});
StringBuilder toDisplay = new StringBuilder();
RealmResults<Person> results = realm.where(Person.class).findAll();
for (Person result : results) {
toDisplay.append("Name :"+result.getName() + " Age :" + result.getAge()+" \n \n");
}
resultTv.setText(toDisplay);
}
Code Explanation
executeTransaction() on our realm variable and then we override the execute() method where we create two new Person objects with the details
Person class and append their details to the StringBuilder object - toDisplay using a for each loop.
resultTv.setText(toDisplay.toString());Application Execution Image
Now, in our Person class, we want to include a new String field - birthDay which is supposed to hold the birthday in the format - "May 05", hence, our Person class should look like below -
NB:: The below code will only feature additions for brevity
//@Getter and @Setter annotations for lombok
public class Person extends RealmObject {
//exisitng fields - name and age
String birthDay;
}
When we try to run the application with the above changes, we get this error in our logcat -
Which states that Migration is required due to the following reasons - property Person.birthDay has been added.
Now, in order to solve this issue, We need to make two changed to our MainActivity.java file :
RealmConfiguration customConfig = new RealmConfiguration.Builder()
.schemaVersion(2)
.migration(new NewMigration())
.build();
Code Explanation
2.NewMigration() method
private class NewMigration implements RealmMigration {
@Override
public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {
RealmSchema schema = realm.getSchema();
if (oldVersion == 1) {
schema.get("Person")
.addField("birthDay", String.class);
oldVersion++;
}
}
Code Explanation
Person class and then we use the addField method, passing the property we just added ("birthDay") as the first argument and the class type - String.class as the second argument.3.CreateRealmObjects()
private void createRealmObjects() {
realm.executeTransaction(new Realm.Transaction() {
@Override
public void execute(Realm realm) {
Person Paul = realm.createObject(Person.class);
Paul.setName("Paul");
Paul.setAge(27);
Paul.setBirthDay("May 05");
Person Bola = realm.createObject(Person.class);
Bola.setAge(31);
Bola.setName("Bola");
Bola.setBirthDay("June 06");
}
});
StringBuilder toDisplay = new StringBuilder();
RealmResults<Person> results = realm.where(Person.class).findAll();
for (Person result : results) {
toDisplay.append("Name :"+result.getName() + " Age :" + result.getAge()+" birthDay : "+result.getBirthDay()+" \n \n");
}
resultTv.setText(toDisplay.toString());
}
Code Explanation
Person objects - Paul and Bola and then we set the nessary details including the newly created one - Paul.setBirthDay("May 05") and Bola.setBirthDay("June 6").resultTv.setText(toDisplay.toString());Application Execution Image
This shows that with migration, you can still maintain your objects in your realm and continue with newly added objects.
https://github.com/generalkolo/Realm-Examples/tree/master/Realm%20Migration