Android-Room-Database-Backup

Simple tool to backup and restore your room database in Android

Features

• Create simple backups of your room database
• Encrypt the backup file with AES encryption
• Save the backup to any type of storage
• Material design
• Written in Kotlin

Content

• Features
• Changelog
• Getting started
• Usage
• Sample app
• Developed by
• License

Changelog

Changelog and Upgrading notes

Getting started

Android-Room-Database-Backup library is pushed to Maven Central .
Add the dependency for Android-Room-Database-Backup to your app-level build.gradle file.

implementation 'de.raphaelebner:roomdatabasebackup:1.0.0-beta12'

Usage

• Properties
• Exit Codes
• Example Activity (Kotlin and Java)
• Example Fragment (Java and Kotlin)

Properties

Required

• Current context
  Attention
  Must be declared outside of an onClickListener before lifecycle state changes to started

  RoomBackup(this)
  

  • Instance of your room database

    .database(*YourDatabase*.getInstance(this))
    

e.g. YourDatabase.kt

Optional

The following options are optional and the default options

• Enable logging, for debugging and some error messages

  .enableLogDebug(false)
  

• Set custom log tag

  .customLogTag("debug_RoomBackup")
  

• Enable and set maxFileCount

  • if file count of Backups > maxFileCount all old / the oldest backup file will be deleted
  • can be used with internal and external storage
  • default: infinity

  .maxFileCount(5)
  

• Encrypt your backup

  • Is encrypted with AES encryption
  • uses a random 15 digit long key with alphanumeric characters
  • this key is saved in EncryptedSharedPreferences
  • backup name is default backup name + ".aes"

  .backupIsEncrypted(false)
  

• Encrypt your backup with your own password / key

  • This property is only working, if .backupIsEncrypted(true) is set
  • If you use the key to encrypt the backup, you will also need it to decrypt
  • Example: If you want to create an encrypted backup, export it and import it to another device. Then you need a custom key, else the backup is encrypted with a random key, and you can not decrypt it on a new device

  Attention
  i do not assume any liability for the loss of your key

  .customEncryptPassword("YOUR_SECRET_PASSWORD")
  

• Save your backup to different storage

  • External
    • storage path: /storage/emulated/0/Android/data/package/files/backup/
    • This files will be deleted, if you uninstall your app
    • RoomBackup.BACKUP_FILE_LOCATION_EXTERNAL
  • Internal
    • Private, storage not accessible
    • This files will be deleted, if you uninstall your app
    • RoomBackup.BACKUP_FILE_LOCATION_INTERNAL
  • Custom Dialog
    • You can choose to save or restore where ever you want. A CreateDocument() or OpenDocument() Activity will be launched where you can choose the location
    • If your backup is encrypted I reccomend you using a custom encrption password else you can't restore your backup

Exit Codes

Here are all exit codes for the onCompleteListener.
They can be calles using OnCompleteListener.$NAME$

Exit Code	Name	Description
0	EXIT_CODE_SUCCESS	No error, action successful
1	EXIT_CODE_ERROR	Other Error
2	EXIT_CODE_ERROR_BACKUP_FILE_CHOOSER	Error while choosing backup to restore. Maybe no file selected
3	EXIT_CODE_ERROR_BACKUP_FILE_CREATOR	Error while choosing backup file to create. Maybe no file selected
4	EXIT_CODE_ERROR_BACKUP_LOCATION_FILE_MISSING	[BACKUP_FILE_LOCATION_CUSTOM_FILE] is set but [RoomBackup.backupLocationCustomFile] is not set
5	EXIT_CODE_ERROR_BACKUP_LOCATION_MISSING	[RoomBackup.backupLocation] is not set
6	EXIT_CODE_ERROR_BY_USER_CANCELED	Restore dialog for internal/external storage was canceled by user
7	EXIT_CODE_ERROR_DECRYPTION_ERROR	Cannot decrypt provided backup file
8	EXIT_CODE_ERROR_ENCRYPTION_ERROR	Cannot encrypt database backup
9	EXIT_CODE_ERROR_RESTORE_BACKUP_IS_ENCRYPTED	You tried to restore a encrypted backup but [RoomBackup.backupIsEncrypted] is set to false
10	EXIT_CODE_ERROR_RESTORE_NO_BACKUPS_AVAILABLE	No backups to restore are available in internal/external sotrage
11	EXIT_CODE_ERROR_ROOM_DATABASE_MISSING	No room database to backup is provided
12	EXIT_CODE_ERROR_STORAGE_PERMISSONS_NOT_GRANTED	Storage permissions not granted for custom dialog
13	EXIT_CODE_ERROR_WRONG_DECRYPTION_PASSWORD	Cannot decrypt provided backup file because the password is incorrect

Example Activity (Kotlin and Java)

Kotlin

• Backup

      val backup = RoomBackup(this)
      ...
      backup
          .database(FruitDatabase.getInstance(this))
          .enableLogDebug(true)
          .backupIsEncrypted(true)
          .customEncryptPassword("YOUR_SECRET_PASSWORD")
          .backupLocation(RoomBackup.BACKUP_FILE_LOCATION_INTERNAL)
          .maxFileCount(5)
          .apply {
              onCompleteListener { success, message, exitCode ->
                  Log.d(TAG, "success: $success, message: $message, exitCode: $exitCode")
                  if (success) restartApp(Intent(this@MainActivity, MainActivity::class.java))
              }
          }
          .backup()
  

• Restore

      val backup = RoomBackup(this)
      ...
      backup
          .database(FruitDatabase.getInstance(this))
          .enableLogDebug(true)
          .backupIsEncrypted(true)
          .customEncryptPassword("YOUR_SECRET_PASSWORD")
          .backupLocation(RoomBackup.BACKUP_FILE_LOCATION_INTERNAL)
          .apply {
              onCompleteListener { success, message, exitCode ->
                  Log.d(TAG, "success: $success, message: $message, exitCode: $exitCode")
                  if (success) restartApp(Intent(this@MainActivity, MainActivity::class.java))
              }
          }
          .restore()
  

Java

• Backup

  final RoomBackup roomBackup = new RoomBackup(MainActivityJava.this);
  ...
  roomBackup.database(FruitDatabase.Companion.getInstance(getApplicationContext()));
  roomBackup.enableLogDebug(enableLog);
  roomBackup.backupIsEncrypted(encryptBackup);
  roomBackup.backupLocation(RoomBackup.BACKUP_FILE_LOCATION_INTERNAL);
  roomBackup.maxFileCount(5);
  roomBackup.onCompleteListener((success, message, exitCode) -> {
      Log.d(TAG, "success: " + success + ", message: " + message + ", exitCode: " + exitCode);
      if (success) roomBackup.restartApp(new Intent(getApplicationContext(), MainActivityJava.class));
  });
  roomBackup.backup();
  

• Restore

  final RoomBackup roomBackup = new RoomBackup(MainActivityJava.this);
  ...
  roomBackup.database(FruitDatabase.Companion.getInstance(getApplicationContext()));
  roomBackup.enableLogDebug(enableLog);
  roomBackup.backupIsEncrypted(encryptBackup);
  roomBackup.backupLocation(RoomBackup.BACKUP_FILE_LOCATION_INTERNAL);
  roomBackup.onCompleteListener((success, message, exitCode) -> {
      Log.d(TAG, "success: " + success + ", message: " + message + ", exitCode: " + exitCode);
      if (success) roomBackup.restartApp(new Intent(getApplicationCo