room description updated

Author: maciej-nowak

_drafts/2019-07-29-coroutines.md

@@ -4,7 +4,7 @@ title: "Coroutines"
 date: 2019-07-29
 categories: ["Kotlin"]
 image: kotlin/coroutines
-github: kotlin/blob/master/coroutines
+github: kotlin/blob/master/coroutines.kt
 description: "Kotlin"
 version: Kotlin v1.3
 keywords: "kotlin, coroutines, coroutine, scope, context, dispatcher, suspend, suspendig, async, withcontext, coroutinescope, runBlocking, launch, channel, actor, produce, android, programowanie, programming"

_drafts/2019-08-19-sqlite.md

@@ -6,11 +6,11 @@ categories: ["Przechowywanie"]
 image: store/sqlite
 github: store/tree/master/sqlite
 description: "Przechowywanie danych"
-keywords: "store, data, database, sql, sqlite, baza, dane, room, query, put, insert, select, update, delete, transaction, android, programowanie, programming"
+keywords: "store, data, database, sql, sqlite, baza, dane, room, query, put, insert, select, update, delete, transaction, dao, entity, migration, android, programowanie, programming"
 ---
 
 ## Bazy danych
-Przechowywanie informacji w bazie danych jest jednym z najpopularniejszych sposobów zarządzania zbiorem danych o ustalonej strukturze. Doskonale spełnia swoją rolę w sytuacji gromadzenia przede wszystkim wielu obiektów zdefiniowanych typów (np. kontakty). Podobnie jak w przypadku plików w `storage` czy wartości prymitywnych w `SharedPreferences` dane pozostają dostępne do odczytu i zapisu niezależnie od cyklu życia aplikacji. Są zachowane dopóki nie zostaną usunięte programowo lub ręcznie przez użytkownika poprzez wyczyszczenie danych aplikacji. `Android` wykorzystuje bazy danych w schemacie `SQL` w implementacji `SQLite`. Pomimo możliwości bezpośredniego operowania na bazie danych za pomocą zapytań `SQLite` przez klienta `SQLiteOpenHelper` wysoce zalecane jest użycie biblioteki `Room` dostarczającej dodatkowej warstwy abstrakcji.
+Przechowywanie informacji w bazie danych jest jednym z najpopularniejszych sposobów zarządzania zbiorem danych o ustalonej strukturze. Doskonale spełnia swoją rolę w sytuacji gromadzenia przede wszystkim wielu obiektów zdefiniowanych typów (np. kontakty). Podobnie jak w przypadku plików w `storage` czy wartości prymitywnych w `SharedPreferences` dane pozostają dostępne do odczytu i zapisu niezależnie od cyklu życia aplikacji. Są zachowane w pamięci wewnętrznej urządzenia dopóki nie zostaną usunięte programowo lub ręcznie przez użytkownika poprzez wyczyszczenie danych aplikacji. `Android` wykorzystuje bazy danych w schemacie `SQL` w implementacji `SQLite`. Pomimo możliwości bezpośredniego operowania na bazie danych za pomocą zapytań `SQLite` przez klienta `SQLiteOpenHelper` wysoce zalecane jest użycie biblioteki `Room` dostarczającej dodatkowej warstwy abstrakcji.
 
 ## Implementacja
 Jedną z głównych zasad tworzenia baz danych `SQL` jest formalna deklaracja struktury. Definiuje ona sposób w jaki baza danych jest organizowana oraz jakie typy obiektów mogą być przechowywane i modyfikowane. Dane znajdują się w tabelach zbudowanych z kolumn i wierszy. Reprezentacją jednego wpisu (porcji informacji) jest encja. Aby zaimplementować bazę danych należy rozszerzyć klasę `SQLiteOpenHelper` oraz nadpisać metody `onCreate` i `onUpgrade` definiując jej strukturę. Modyfikacja zawartości bazy odbywa się przy pomocy zapytań `SQL` w metodach `put`, `query`, `delete`, `update`.
@@ -33,7 +33,7 @@ class SQLiteActivity : AppCompatActivity() {
         database.close()
         super.onDestroy()
     }
-	
+    
     //some database manage methods, there could be inside some manager with conversion some object type into raw data
     //notice how many lines of code are needed to do simple single query operation
 
@@ -142,21 +142,46 @@ object DatabaseContract {
 `Room` dostarcza warstwy abstrakcji dla `SQLite` dzięki czemu dostęp i zarządzanie bazą danych staje się łatwiejsze, a pisanie kodu szybsze. Weryfikuje poprawność zapytań `SQL` już w trakcie kompilacji co znacznie zmniejsza możliwość popełnienia błędu. Ponadto wspiera mechanizm transakcji i dostarcza wiele adnotacji redukując tym samym potrzebę pisania wielu zapytań. Aby umożliwić współpracę z `Room` należy dostarczyć trzy komponenty oznaczone jako `@Database`, `@Entity`, `@Dao`. 
 
 ## Entity
-Klasa oznaczona jako `@Entity` reprezentuje tabele, gdzie każde jej pole jest kolumną. Pełni ona rolę modelu w bazie danych i nie zawiera żadnej logiki. `@PrimaryKey` ustawia klucz podstawowy na wskazanym polu, a `@ForeignKey` wskazuje klucz obcy. `@ColumnInfo` definiuje nazwę kolumny, `@Embedded` umożliwia dostęp do pól wewnętrznych klasy, natomiast `@Ignore` pozwala zignorowanie konstruktorów i pól przy tworzeniu obiektu przez `Room` (jeśli jest kilka konstruktorów).
+Klasa oznaczona jako `@Entity` reprezentuje tabele, gdzie każde jej pole jest kolumną. Pełni ona rolę modelu w bazie danych i nie zawiera żadnej logiki. `@PrimaryKey` ustawia klucz podstawowy na wskazanym polu, a `@ForeignKey` wskazuje klucz obcy i łączy. `@ColumnInfo` definiuje nazwę kolumny, `@Embedded` umożliwia dostęp do wewnętrznych pól klasy jako kolumn tabeli, natomiast `@Ignore` pozwala zignorowanie konstruktorów czy pól przy tworzeniu obiektu przez `RoomDatabase` (jeśli jest kilka konstruktorów).
 
 {% highlight kotlin %}
-//represents some table of database, define scheme here
-@Entity(tableName = "person") //by default tableName is class name
-data class Person 
+//represents a table of database, define scheme here
+@Entity(
+    tableName = "person",
+    foreignKeys = [ForeignKey(entity = Address::class, parentColumns = ["id"], childColumns = ["addressId"])])
+data class Person
 (
-    @ColumnInfo(name = "name")
-    var firstName: String,
-    var age: Int //by default column name is field name	    
-) 
-{
     @PrimaryKey(autoGenerate = true)
-    var id: Int = 0
+    val id : Long,
+
+    @ColumnInfo(name = "name") //set column nam for this field
+    var fullName : String,
+
+    //by default column name is field name so no need to use @ColumnInfo
+    var age : Int,
+
+    //some annotations can be declared as @Entity parameters e.g. foreignKeys instead of @ForeignKey
+    var addressId : Long,
+
+    @Embedded //fields of this class are columns of the table
+    var Contact : Contact
+)
+{
+    @Ignore //tell Room to ignore this constructor
+    constructor(fullName : String, age : Int, addressId : Long, contact : Contact) : this(0, fullName, age, addressId, contact)
+
+    //some class body
 }
+
+//by default tableName is a class name, indices speeds up select but slows down insert or update
+@Entity(tableName = "address", indices = [Index(value = ["street"])])
+data class Address(@PrimaryKey(autoGenerate = true) val id : Long, var city : String, var street : String) {
+
+    @Ignore
+    constructor(city : String, street: String) : this(0, city, street)
+}
+
+data class Contact(var phone : String, var email : String)
 {% endhighlight %}
 
 ## Dao
@@ -169,98 +194,176 @@ interface PersonDao {
 
     //provide query command for @Query annotation
     @Query("SELECT * FROM person")
-    fun getAll(): List<Person>
+    fun getAll() : List<Person>
 
     @Query("SELECT * FROM person WHERE name LIKE :name LIMIT 1")
-    fun findByName(name: String): Person
+    fun findByName(name : String) : Person
 
-    @Query("SELECT * FROM person WHERE age LIKE :age")
-    fun findByAge(age: Int): Person
+    @Query("SELECT * FROM person INNER JOIN address ON address.id = person.id WHERE address.city LIKE :city")
+    fun findByCity(city : String) : List<Person>
 
-    //do not have to provide any SQL with @Insert
-    //when conflict just replace so it works also as update
+    //do not have to provide any SQL with @Insert, when conflict just replace so it works also as update
+    //return id primary key
     @Insert(onConflict = OnConflictStrategy.REPLACE)
-    fun insert(person : Person)
+    fun insert(person : Person) : Long
 
     @Insert
-    fun insertAll(vararg persons: Person)
-    
+    fun insertAll(vararg persons : Person)
+
     //do not have to provide any SQL with @Update or @Delete but it can be also replace by normal @Query
     @Update
     fun update(person : Person)
 
     @Delete
-    fun delete(person: Person)
-	
+    fun delete(person : Person)
+
     //make transaction with atomic operations
     @Transaction
-    fun increaseAgeForAll() {
+    suspend fun increaseAgeForAll() {
         for (person in getAll()) {
             person.age = person.age + 1
             update(person)
         }
     }
 }
+
+@Dao
+interface AddressDao {
+
+    @Query("SELECT * FROM address")
+    fun getAll() : List<Address>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    fun insert(address: Address) : Long
+
+    @Delete
+    fun delete(address: Address)
+}
 {% endhighlight %}
 
 ## Database
 Klasa oznaczona jako `@Database` łączy wybrane tabele klas `@Entity` i metody dostępowe klas `@Dao` w jedną całość. Taka klasa musi być abstrakcyjna i rozszerzać `RoomDatabase` oraz deklarować metody abstrakcyjne zwracające obiekty `@Dao`.
 
 {% highlight kotlin %}
 //serves as the access point, define list of entities associated with database
-@Database(entities = arrayOf(Person::class), version = 1)
-//must be abstract and extends RoomDatabase and marked as Database
-abstract class AppDatabase : RoomDatabase() {
+@Database(entities = [Person::class, Address::class], version = 1, exportSchema = false)
+abstract class AppDatabase : RoomDatabase() { //must be abstract and extends RoomDatabase
 
     //abstract no arg methods with returns of entities
     abstract fun personDao() : PersonDao
+    abstract fun addressDao() : AddressDao
+
     //define more methods for other entities class
 }
 {% endhighlight %}
 
 ## Użycie
-Tworzenie instancji bazy danych `Room` odbywa się przy użyciu budowniczego. Ze względu na kosztowność bazy warto rozważyć zastosowanie wzorca `Singleton` i tym samym ograniczyć instancję do jednej dla całej aplikacji.
+Tworzenie instancji bazy danych `RoomDatabase` odbywa się przy użyciu budowniczego. Ze względu na kosztowność bazy warto rozważyć zastosowanie wzorca `Singleton` i tym samym ograniczyć instancję do jednej dla całej aplikacji.
 
 {% highlight kotlin %}
 class RoomActivity : AppCompatActivity(), CoroutineScope by MainScope() {
 
-    //create or inject instance, it could be Singleton
     lateinit var database : AppDatabase
+    lateinit var personDao : PersonDao
+    lateinit var addressDao : AddressDao
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
 
+        //create or inject instance, it could be Singleton
+        //can be created also by inMemoryDatabaseBuilder() which helps testing
         database = Room
-            .databaseBuilder(this, AppDatabase::class.java, "RoomDatabase")
+            .databaseBuilder(this, AppDatabase::class.java, "AppDatabase")
             .build()
+        //there are more builders options like allowMainThreadQueries()
 
+        //access to database by dao
+        personDao = database.personDao()
+        addressDao = database.addressDao()
+
+        //must be run on the background thread otherwise exception will be thrown
         doSomeOperations()
     }
 
     fun doSomeOperations() {
-        //must be run on the background thread otherwise exception will be thrown
         launch(Dispatchers.IO) {
-            //use it by Dao instance
-            val personDao = database.personDao()
-
-            //CREATE objects
-            personDao.insert(Person("Jack", 50))
-            personDao.insertAll(Person("Johhnie", 60), Person("William", 70))
-
-            //SELECT objects
-            var persons = personDao.getAll()
-            val person = personDao.findByName("Jack")
-
-            //UPDATE object
-            person.age = 20
-            personDao.update(person)
-
-            //DELETE object
-            personDao.delete(person)
-            
-            //run transaction method
-            personDao.increaseAgeForAll()
+            createData()
+            val person = selectData()
+            updateData(person)
+            deleteData(person)
+            runTransaction()
         }
     }
+
+    fun createData() {
+        //put some data using dao example methods
+        val address = Address("Poznan", "sw. Marcin")
+        val contact = Contact("111 222 333", "jack@daniels.com")
+        val addressId = addressDao.insert(address)
+        personDao.insert(Person("Jack Daniels", 50, addressId, contact))
+
+        val polwiejskaId = addressDao.insert(Address("Poznan", "Polwiejska"))
+        val johnnie = Person("Johnnie Walker", 60, polwiejskaId, Contact("222 333 444", "johnnie@walker.com"))
+        val william = Person("William Grant", 70, polwiejskaId, Contact("333 444 555", "william@grant.com"))
+        personDao.insertAll(johnnie, william)
+    }
+
+    fun selectData() : Person {
+        //example of getting data usage
+        val persons = personDao.getAll()
+        val person = personDao.findByName("Jack Daniels")
+        return person
+    }
+
+    fun updateData(person : Person) {
+        person.age = 20
+        personDao.update(person)
+    }
+
+    fun deleteData(person : Person) {
+        personDao.delete(person)
+    }
+
+    suspend fun runTransaction() {
+        //run transaction by annotated method
+        personDao.increaseAgeForAll()
+
+        //or this can be achieve also by transaction directly on database
+        database.runInTransaction {
+            for (person in personDao.getAll()) {
+                person.age = person.age + 1
+                personDao.update(person)
+            }
+        }
+    }
+}
+{% endhighlight %}
+
+## Migracja
+W trakcie rozwijania aplikacji nierzadko występuje potrzeba zmiany struktury bazy danych. W takiej sytuacji może okazać się, że jakaś część danych z poprzedniego formatu bazy jest nadal potrzebna. W związku z tym należy zapewnić poprawną migrację danych między wersjami bazy poprzez skonstrukowanie odpowiedniego zapytania `SQL` w obiekcie `Migration` oraz dodanie go przez `addMigrations` w trakcie tworzenia bazy. Z uwagi na to, że proces migracji narażony jest na występowanie poważnych błędów przed wypuszczeniem wersji produkcyjnej aplikacji nie można zapomnieć o lokalnej kopii zapasowej danych i właściwych testach migracji wspieranych przez `MigrationTestHelper`.
+
+{% highlight kotlin %}
+class MigrationActivity : AppCompatActivity() {
+
+    //address entity is extended by new building number column and database upgraded version
+
+    lateinit var database : AppDatabase
+
+    //provide proper SQL migration
+    val MIGRATION_1_2 = object: Migration(1, 2) {
+        override fun migrate(database: SupportSQLiteDatabase) {
+            database.execSQL("ALTER TABLE address ADD COLUMN number TEXT")
+            //if new column can not be null inject some default values by execSQL
+        }
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        database = Room
+            .databaseBuilder(this, AppDatabase::class.java, "RoomDatabase")
+            .addMigrations(MIGRATION_1_2) //pass more of them if needed
+            .build()
+    }
 }
 {% endhighlight %}