Merge pull request #2144 from dhis2/androsdk-1842

docs: [ANDROSDK-1842] Docs: import/export database
dhis2 · May 9, 2024 · 01abff4 · 01abff4
2 parents 7aff658 + 06a41ed
commit 01abff4
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 15 deletions.
diff --git a/docs/content/developer/compatibility.md b/docs/content/developer/compatibility.md
@@ -2,15 +2,16 @@
 
 Compatibility table between DHIS2 Android SDK library, DHIS2 core and Android SDK API.
 
-| SDK      | DHIS2 core       | Android SDK | Rule engine       |
-|-|-|-|-|
-| 1.0.X    | 2.29 -> 2.33     | 19 - 28     | -                 |
-| 1.1.X    | 2.29 -> 2.34     | 19 - 28     | -                 |
-| 1.2.X    | 2.29 -> 2.34     | 19 - 28     | -                 |
-| 1.3.X    | 2.29 -> 2.35     | 19 - 29     | 2.0.10 - 2.0.15   |
-| 1.4.X    | 2.29 -> 2.36     | 19 - 29     | 2.0.17 - 2.0.20   |
-| 1.5.X    | 2.29 -> 2.37     | 19 - 29     | 2.0.25 - 2.0.27   |
-| 1.6.X    | 2.30 -> 2.38     | 21 - 31     | 2.0.34 - 2.0.35   |
-| 1.7.X    | 2.30 -> 2.39     | 21 - 31     | 2.0.42 - 2.0.43   |
-| 1.8.X    | 2.30 -> 2.40     | 21 - 33     | 2.0.47 - 2.0.48   |
-| 1.9.X    | 2.30 -> 2.40     | 21 - 34     | 2.0.47 - 2.0.48   |
+| SDK    | DHIS2 core   | Android SDK | Rule engine       |
+|--------|--------------|-|-|
+| 1.0.X  | 2.29 -> 2.33 | 19 - 28     | -                 |
+| 1.1.X  | 2.29 -> 2.34 | 19 - 28     | -                 |
+| 1.2.X  | 2.29 -> 2.34 | 19 - 28     | -                 |
+| 1.3.X  | 2.29 -> 2.35 | 19 - 29     | 2.0.10 - 2.0.15   |
+| 1.4.X  | 2.29 -> 2.36 | 19 - 29     | 2.0.17 - 2.0.20   |
+| 1.5.X  | 2.29 -> 2.37 | 19 - 29     | 2.0.25 - 2.0.27   |
+| 1.6.X  | 2.30 -> 2.38 | 21 - 31     | 2.0.34 - 2.0.35   |
+| 1.7.X  | 2.30 -> 2.39 | 21 - 31     | 2.0.42 - 2.0.43   |
+| 1.8.X  | 2.30 -> 2.40 | 21 - 33     | 2.0.47 - 2.0.48   |
+| 1.9.X  | 2.30 -> 2.40 | 21 - 34     | 2.0.47 - 2.0.48   |
+| 1.10.X | 2.30 -> 2.41 | 21 - 34     | 2.0.47 - 2.0.48   |
diff --git a/docs/content/developer/database.md b/docs/content/developer/database.md
@@ -1,9 +1,9 @@
 # Database { #android_sdk_database }
 
-## Database scope
+## Database scope { #android_sdk_database_scope }
 The SDK keeps the data of a [server, user] pair in an isolated database. As of version 1.6.0, the SDK supports multiple accounts (pairs [server, user]) and the information for each account is stored in an isolated database. The database is deleted only when the account is deleted. Databases are created automatically on a successful login.
 
-## Encryption
+## Encryption { #android_sdk_database_encryption }
 As of SDK version 1.1.0, it is possible to store the data in an encrypted database. The encryption key is generated randomly
 by the SDK and kept secure.
 
@@ -18,4 +18,28 @@ if changed, will encrypt or decrypt the current database without data loss.
 
 ### Encryption performance
 - Database size: the database size is approximately the same, regardless of being encrypted or not.
-- Speed: reads and writes are on average 5 to 10% slower using an encrypted database.
+- Speed: reads and writes are on average 5 to 10% slower using an encrypted database.
+
+## Import / export { #android_sdk_database_import_export }
+The database can be exported and imported in a different device. 
+
+One of the main use cases of this functionality is debugging: sometimes it is hard to know the reason for a sync problem or a bug, and it is very useful to replicate the issue in an emulator or a different device.  
+
+```kt
+// Export database
+val database = d2.maintenanceModule().databaseImportExport().exportLoggedUserDatabase()
+
+// Import database
+val metadata = d2.maintenanceModule().databaseImportExport().importDatabase(database)
+
+// The metadata object contains information about the database (serverUrl, username,...) 
+
+// Once the database is imported, it is possible to login as usual
+d2.userModule().login("username", "password", "serverUrl")
+```
+
+The export process encrypts the database using ZIP encryption, so the database file can't be read unless the right user credentials are provided. 
+
+Things to consider:
+- The exported file only contains the database, it does not contain file resources (images, icons, files,...).
+- The receiver device must run an **SDK version that is equal or higher** than the SDK version used to export the database.