Create documentation

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)
+