sqlite post added

Author: maciej-nowak

_drafts/2019-05-27-rxandroid.md _drafts/2019-05-27-rxjava.md_drafts/2019-05-27-rxandroid.md renamed to _drafts/2019-05-27-rxjava.md

@@ -0,0 +1,266 @@
+---
+layout: post
+title: "SQLite"
+date: 2019-08-19
+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"
+---
+
+## 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.
+
+## 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`.
+
+{% highlight kotlin %}
+//use SQLiteDatabase in some client
+class SQLiteActivity : AppCompatActivity() {
+    
+    private lateinit var database : SQLiteDatabase
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        //get instance of writable or readable database to reuse it in multiple queries
+        database = Database(this).writableDatabase
+        //use database by defined methods below
+    }
+
+    override fun onDestroy() {
+        //close costly database connection
+        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
+
+    fun put() {
+        //prepare data
+        val values = ContentValues()
+        values.put(DatabaseContract.Person.COLUMN_NAME, "Jack")
+        values.put(DatabaseContract.Person.COLUMN_AGE, 50)
+
+        //put the data and get id of new entry, returns -1 if fails
+        val id = database.insert(DatabaseContract.Entry.TABLE_PERSON, null, values)
+    }
+
+    fun read() {
+        //define the query params
+        val table = DatabaseContract.Person.TABLE_PERSON
+        val columns : Array<String>? = null //get all columns
+        val selection = DatabaseContract.Person.COLUMN_NAME + " = ?" //columns for WHERE
+        val args = arrayOf("Jack") //values for WHERE
+        val groupBy = null //ignore
+        val filterBy = null //ignore
+        val sortOrder = DatabaseContract.Person.COLUMN_AGE + " DESC"
+
+        //make query and read data from the cursor by iterator methods
+        val cursor : Cursor = database.query(table, columns, selection, args, groupBy, filterBy, sortOrder)
+        while (cursor.moveToNext()) {
+            val age = cursor.getString(cursor.getColumnIndex(DatabaseContract.Person.COLUMN_AGE))
+            //do something with item
+        }
+        cursor.close()
+    }
+
+    fun delete() {
+        //define query params
+        val table = DatabaseContract.Person.TABLE_PERSON
+        val selection = DatabaseContract.Person.COLUMN_NAME + " LIKE ?"
+        val args = arrayOf("Jack")
+
+        //delete entries and get number of the removed items
+        val count = database.delete(table, selection, args)
+    }
+
+    fun update() { 
+        //prepare data
+        val values = ContentValues()
+        values.put(DatabaseContract.Person.COLUMN_AGE, 51)
+        
+        //define query params
+        val table = DatabaseContract.Person.TABLE_PERSON
+        val selection = DatabaseContract.Person.COLUMN_NAME + " LIKE ?"
+        val args = arrayOf("Jack")
+        
+        //update entries and updated count
+        val count = database.update(table, values, selection, args)
+    }
+}
+
+//extend SQLiteOpenHelper
+class Database(context : Context) : SQLiteOpenHelper(context, DATABASE_NAME, null, DATABASE_VERSION) {
+
+    companion object {
+        const val DATABASE_VERSION = 1
+        const val DATABASE_NAME = "Person.db"
+    }
+
+    //define SQL queries, use DatabaseContract
+    private val SQL_CREATE =
+        "CREATE TABLE ${DatabaseContract.Person.TABLE_PERSON} (" +
+            "${BaseColumns._ID} INTEGER PRIMARY KEY," +
+            "${DatabaseContract.Person.COLUMN_NAME} TEXT," +
+            "${DatabaseContract.Person.COLUMN_AGE} INTEGER)"
+
+    private val SQL_DELETE =
+        "DROP TABLE IF EXISTS ${DatabaseContract.Person.TABLE_PERSON}"
+
+    override fun onCreate(db: SQLiteDatabase?) {
+        //just create database with specific structure
+        db?.execSQL(SQL_CREATE)
+    }
+
+    override fun onUpgrade(db: SQLiteDatabase?, oldVersion: Int, newVersion: Int) {
+        //do something when database structure has updated, e.g. clear all old data
+        db?.execSQL(SQL_DELETE)
+        onCreate(db)
+    }
+
+    //implement other methods like onDowngrade, onConfigure
+}
+
+//good practice is to define database scheme contract to simpler manage it
+object DatabaseContract {
+
+    //create inner class for each Table, BaseColumns has primary key field called _ID
+    object Person : BaseColumns {
+        const val TABLE_PERSON = "person"
+        const val COLUMN_NAME = "name"
+        const val COLUMN_AGE = "age"
+    }
+}
+{% endhighlight %}
+
+## Ograniczenia
+`SQLiteOpenHelper` umożliwia zarządzanie zarówno strukturą jak i zawartością bazy danych. Jest narzędziem niższego poziomu, które wymaga od programisty implementacji kodu związanego ze strukturą i zapytaniami do bazy co jest podatne na błędy z uwagi na brak weryfikacji poprawności poleceń `SQL` i zgodności ze schematem bazy. Wymaga generowania nadmiarowego kodu konwersji zapytań `SQL` do obiektów i na odwrót (praktycznie jedna metoda dla każdej atomowej operacji dla danego typu). Rozwiązaniem tych problemów może być wykorzystanie biblioteki `Room`.
+
+## Room
+`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).
+
+{% highlight kotlin %}
+//represents some table of database, define scheme here
+@Entity(tableName = "person") //by default tableName is class name
+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
+}
+{% endhighlight %}
+
+## Dao
+Klasa oznaczona jako `@Dao` odpowiedzialna jest za dostarczenie deklaracji metod dostępowych do baz danych. Są one tworzone przy użyciu różnych adnotacji takich jak m.in. `@Insert`, `@Update`, `@Delete` które automatycznie generują kod zapytań czy też przez adnotację `@Query` wymagającej definicji zapytania. W przypadku ciągu operacji, które muszą zostać wykonane w ramach jednej transakcji należy użyć adnotacji `@Transaction`.
+
+{% highlight kotlin %}
+//define methods to use database
+@Dao
+interface PersonDao {
+
+    //provide query command for @Query annotation
+    @Query("SELECT * FROM person")
+    fun getAll(): List<Person>
+
+    @Query("SELECT * FROM person WHERE name LIKE :name LIMIT 1")
+    fun findByName(name: String): Person
+
+    @Query("SELECT * FROM person WHERE age LIKE :age")
+    fun findByAge(age: Int): Person
+
+    //do not have to provide any SQL with @Insert
+    //when conflict just replace so it works also as update
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    fun insert(person : Person)
+
+    @Insert
+    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)
+	
+    //make transaction with atomic operations
+    @Transaction
+    fun increaseAgeForAll() {
+        for (person in getAll()) {
+            person.age = person.age + 1
+            update(person)
+        }
+    }
+}
+{% 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() {
+
+    //abstract no arg methods with returns of entities
+    abstract fun personDao() : PersonDao
+    //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.
+
+{% highlight kotlin %}
+class RoomActivity : AppCompatActivity(), CoroutineScope by MainScope() {
+
+    //create or inject instance, it could be Singleton
+    lateinit var database : AppDatabase
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        database = Room
+            .databaseBuilder(this, AppDatabase::class.java, "RoomDatabase")
+            .build()
+
+        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()
+        }
+    }
+}
+{% endhighlight %}