Packing Up a Room

A popular question over the years has been: how do I ship a pre-populated database with my app?

Android has never offered an “out of the box” solution for this, though there are third-party solutions that we can use. Room changes the problem space slightly, breaking the original solutions and requiring a fresh option. In this chapter, we will review that new solution and how you can use it to ship a database, packaged in your app, and used by Room.

The Problem

Roughly speaking, data for a SQLite database can come from one of three places:

• It can come from user input, through the UI of your app
• It can come from external sources, such as data that you synchronize with a Web service
• It can come with the app itself, when the app was installed

Most apps get by with the first two data sources. However, from time to time, there are situations where shipping a database with an app can prove useful.

Sometimes, that database represents starter data, that the user (or a server) will augment or modify over time. For example, you might be writing an app for documenting household goods and other items, to help a homeowner or renter with future insurance claims in case of a fire, natural disaster, etc. The app allows the user to take photos of items, provide notes about them (make, model, etc.), and categorize them. While the user can manage the list of categories, you might want to ship some pre-defined categories with the app, so that the user is not forced into deciding on categories before the app can be used.

Sometimes, the packaged database is a read-only data repository. Frequently, this is for apps that want to offer offline access to a dataset that otherwise might be pulled from a Web service. Sometimes, the data simply is not meant to change frequently. For example, the APK edition of The Busy Coder’s Guide to Android Development ships with a packaged database containing the prose of the book, indexed by SQLite’s FTS3 engine for use with full-text searching. The database contents are updated when the app is updated, reflecting a new version of the book.

For tiny datasets, you can get away with populating the database yourself when you first create it, using ordinary Java code. This is inefficient for larger databases, though, as it forces us to execute a bunch of SQLite transactions on the user’s device. It would be more efficient to ship an actual SQLite database file. And, since the developers of SQLite have done an admirable job of backwards and forwards compatibility with their database file structure, this works fairly well. You use other tools, such as DB Browser for SQLite, to create the database with your data. Then, you… do… something… to put that database in the APK and use it at runtime.