Update documentation

README.md

@@ -6,9 +6,15 @@ _Kotlin library to request postgres with native SQL queries_
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=postgres-json&metric=coverage)](https://sonarcloud.io/dashboard?id=postgres-json)
 [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=postgres-json&metric=ncloc)](https://sonarcloud.io/dashboard?id=postgres-json)
 
-* [Installation](./docs/installation.md)
-* [Migrations](./docs/migrations/migrations.md)
-* [Usage](./docs/usage/usage.md)
+---
+
+## What is this lib for?
+This library allows you to make sql requests and return the result in json format, then deserialize it into an entity.
+It also allows you to save an entity (INSERT) by serializing it and sending the json to the database, allowing you to insert several entities with their children, in a single request.
+
+It also manages the migrations of the schema of tables and stored procedures.
+
+All sql requests are handled manually for full control over what you do.
 
 ---
 
@@ -16,7 +22,16 @@ _Kotlin library to request postgres with native SQL queries_
 
 * Total control of all Postgresql features and SQL language
 * More speed and flexible than an ORM
-* [Multi level request](./docs/usage/multi-level.md)
+* [Multi level request](./docs/usage/multi-level.md) (Can return multiple tables and these children in a single request)
 * Queries are written in separate native `.sql` files
+* Unit testing of SQL queries
+* Migrations are written in separate native `.sql` files
 * Automatic tested database migration and rollback
-* Unit testing of SQL queries
+---
+## Documentation: Table of Contents
+
+* [Installation](./docs/installation.md)
+* [Migrations](./docs/migrations/migrations.md)
+* [Usage](./docs/usage/usage.md)
+* [How that works](./docs/call%20function.png) (Diagram)
+* [How to begin](./docs/checklist.md)

docs/call function.puml

@@ -0,0 +1,52 @@
+@startuml
+
+participant  Gradle
+participant  App
+control  Migration
+control  Repository
+control  Requester
+control  Function
+control  Connection
+database Database
+
+== Migration ==
+
+[-> Gradle++ : run gradle
+    Gradle -> Migration** : Init Migration
+        Migration -> Migration : Read Schemas
+        Migration -> Migration : Read SQL Function
+    Gradle -> Migration++ : Run Migrations
+        Migration -> Migration : Run Migrations
+    return
+    Gradle -> Migration!!
+return
+
+== Application ==
+
+[-> App : run app
+    App -> Connection** : Create Connection
+        Connection -> Database : Connect to the database
+    App -> Requester** : Create Requester
+        Requester -> Requester: Read all Function file
+        Requester -> Function** : Create Function object
+            Function -> Function : Parse function
+            Function -> Function : Store parameters and function name
+    App -> Repository** : Create Repository
+
+... wait request ...
+
+[-> Repository++ : call repository with args
+    Repository -> Repository : Define function name
+    Repository -> Requester++ : get function
+        Requester -> Function++ : select()
+            Function -> Function : Compile args
+            Function -> Function : Compile SQL
+            Function -> Connection++ : select()
+                Connection -> Database++ : Send Prepared Statement
+                return
+                Connection -> Connection : Convert json to Entity
+            return entity
+        return entity
+    return entity
+return entity
+@enduml

docs/checklist.md

@@ -0,0 +1,9 @@
+# Checklist
+
+- [ ] Define schemas with migrations files (*.up.sql & *.down.sql)
+- [ ] Define query with sql function (*.sql)
+- [ ] Create Entity (*.kt)
+- [ ] Create repository (*.kt)
+- [ ] Configure migrations in gradle
+- [ ] Execute migrations functions
+- [ ] Call Repository

docs/usage/raw-request.md

@@ -24,9 +24,11 @@ val connection: Connection = TODO()
 
 data class Inventor(
     val id: UUID = UUID.randomUUID(),
-    val name: String
+    val name: String,
+    val roles: List<String> = listOf(),
 ): Serializable
 
+// Select one entity
 val result: Inventor? = connection.selectOne(
     """
     SELECT json_build_object(
@@ -37,9 +39,47 @@ val result: Inventor? = connection.selectOne(
     mapOf("name" to "Nikola Tesla")
 )
 
-val inventor = connection.selectOne<Inventor>("SELECT * FROM mytable WHERE id = :id")
+// Select multiple entities
+val result = connection.select<List<Inventor>>(
+    """
+    SELECT json_build_array(
+        json_build_object(
+           'id', '9e65de49-712e-47ce-8bf2-dfffae53a82e',
+           'name', :name
+        ),
+        json_build_object(
+           'id', '32f67ed3-af6d-403b-a3b9-5fe3540c3412',
+           'name', :name2
+        )
+    )
+    """,
+    mapOf(
+        "name" to "Nikola Tesla",
+        "name2" to "Albert Einstein",
+    )
+)
 
-val inventors: List<Inventor> = connection.select("SELECT * FROM mytable WHERE status = 'done'")
+// Select multiple with real query
+val result: List<Inventor> = connection.select(
+    """
+        select json_agg(i)
+        from inventor i
+        where roles @> ARRAY[:role];
+    """,
+    mapOf("role" to "ADMIN")
+)
+
+
+// Select multiple with only some rows
+val result: List<Inventor> = connection.select(
+    """
+        select json_agg(i)
+        from (
+             select id, name
+             from inventor
+        ) i;
+    """
+)
 ```