How to Setup Database Migrations with greenDAO

If you’ve ever used greenDAO, you’ve probably used their DevOpenHelper class. As the name implies, it helps you open the database, but it also defines what happens when your schema version changes. If you read the documentation for this class, you will see this: WARNING: Drops all table on Upgrade! Use only during development.

So if you ever change your schema (such as add a new table), it will drop all tables first, which wipes the database. For development, where the schema is constantly changing, this might be fine. However, once your app has been released, your users will probably be very unhappy if all of their data gets deleted when they hit update.

This is where database migrations come in, and why you should not be using DevOpenHelper in production. Instead of deleting all of your data, you can tell greenDAO how to handle schema version changes. That way your data does not get lost and app updates are seamless.

Setting up migrations

To demonstrate this, I took the example app from greenDAO’s GitHub and modified it to include migrations. You can find my example project here. Here is the final version of the class used to perform the migrations.

If you want to try it out, you can clone my example project, and check out the commit 689fa205d87e5c74f27e25588eb1b2a5f41588be. This will take you to the first schema version. At this point, there is only a Note table. If you try running the app, you can add some notes to the database.

Now, if you check out the next commit 23fd3802fd105873584023c807b60120b93da142, it will take you to the second schema version. In this version, I added a User table. If you were using the DevOpenHelper class, running the app here would delete the notes you have made previously. Since we are doing a migration, that won’t happen. If you run the app, you can try adding a User, and you will see that your notes are still there.

Lastly, if you check out the third schema version, 5c1367164620858c814cf87860771c06c8140f77, and install the app, it will run another migration. In this version, I added age to the User. If you run the app, none of the data will get lost, and you can now set the age of a User.

In this example, we could have also jumped straight from schema version 1 to 3, and the migrations would've still worked. However, it would have had to run two migrations instead of one. It doesn’t matter which version the user is updating from, the migrations will still work.

Final thoughts

You only need migrations when you’re releasing a new version of an app where you also made changes to the database. If you’re in development and you're constantly making changes to the database, you most likely wouldn’t need to update the schema version constantly. However, you should be aware that during development, if you add a new table or update the app on a device that has already installed it, it won’t update the database. Because the schema version hasn’t changed, it will cause the app to crash if you try to query the database for that table (since it doesn’t exist yet).

Sometimes during development, it’s best to just keep contibue to use DevOpenHelper to update the schema version. Just remember to change it back for release. Alternatively, if you update the database schema, you can clear the data for your app. That way, it will force it to recreate the database with the altered schema.

If you're interested to learn more about integrating greenDAO into your Android application, read this post.