Create documentation

docs/migrations/migrations-application.md

@@ -0,0 +1,16 @@
+# Execute migration in application
+```kotlin
+import fr.postgresjson.migration.Migrations
+import fr.postgresjson.connexion.Connection
+
+val conn: Connection = TODO()
+val migrations = Migrations(
+    conn,
+    this::class.java.getResource("/sql/migrations")?.toURI() ?: error("No migrations found"),
+    this::class.java.getResource("/sql/functions")?.toURI() ?: error("No sql function found")
+)
+
+migrations.status() // Show executed and not executed migrations
+migrations.runDry() // Execute migration in transaction and rollback at the end
+migrations.run() // Execute migration in transaction and commit if no error
+```

docs/migrations/migrations-gradle.md

@@ -0,0 +1,37 @@
+# Execute Migrations with Gradle
+
+You can execute migration with a Gradle task like this:
+
+```kotlin
+// build.gradle.kts
+import fr.postgresjson.connexion.Connection
+import fr.postgresjson.connexion.Requester
+import fr.postgresjson.migration.Migrations
+
+buildscript {
+    dependencies {
+        classpath("com.github.flecomte:postgres-json:+")
+    }
+}
+
+val migration by tasks.registering {
+    doLast {
+        val connection = Connection(
+            host = "localhost",
+            port = 5432,
+            database = "database",
+            username = "username",
+            password = "password"
+        )
+        Migrations(
+            connection,
+            file("$buildDir/resources/main/sql/migrations").toURI(),
+            file("$buildDir/resources/main/sql/functions").toURI()
+        ).run()
+    }
+}
+```
+
+```shell
+$ gradle migration
+```

docs/migrations/migrations.md

@@ -0,0 +1,71 @@
+# Migration
+## Schemas migration
+Migrations are just manually written `*.sql` files that represent the database schemas.
+Each file is executed one after the other in alphabetical order.
+Each execution is stored in the `migration.history` table.
+
+A migration contains a `*.up.sql` file and a `*.down.sql` file to rollback the migration.
+The content of the `*.down.sql` file is also stored in the database.
+This allows the `*.down.sql` to be executed even if the code is already rollback.
+
+Example:
+```postgresql
+-- resources/sql/migrations/0000-init_schema.up.sql
+create table "user"
+(
+    id         uuid        default uuid_generate_v4() not null primary key,
+    created_at timestamptz default now()              not null,
+    blocked_at timestamptz default null               null,
+    username   varchar(64)                            not null check ( username != '' and lower(username) = username) unique,
+    password   text                                   not null check ( password != '' ),
+    roles      text[]      default '{}'               not null
+);
+```
+
+```postgresql
+-- resources/sql/migrations/0000-init_schema.down.sql
+drop table if exists "user";
+```
+## Stored procedure migrations
+
+Migrations are also stored procedures and other functions.
+Each function is updated with each migration.
+
+Example:
+```postgresql
+-- resources/sql/functions/insert_user.sql
+create or replace function insert_user(inout resource json) language plpgsql as
+$$
+declare
+    new_id uuid;
+begin
+    insert into "user" (id, username, password, blocked_at, roles)
+    select
+        coalesce(t.id, uuid_generate_v4()),
+        t.username,
+        crypt(resource->>'password', gen_salt('bf', 8)),
+        case when t.blocked_at is not null then now() else null end,
+        t.roles
+    from json_populate_record(null::"user", resource) t
+    returning id into new_id;
+
+    select find_user_by_id(new_id) into resource;
+end;
+$$;
+```
+
+```postgresql
+-- resources/sql/functions/find_user_by_id.sql
+create or replace function find_user_by_id(in _id uuid, out resource json) language plpgsql as
+$$
+begin
+    select to_jsonb(u) - 'password' into resource
+    from "user" as u
+    where u.id = _id;
+end;
+$$;
+```
+
+* [Execute migrations in application](./migrations-application.md)
+* [Execute migrations with gradle](./migrations-gradle.md)
+