Put tutorial specific info into a separate file

Marcin K · Marcin K · commit 12f7e22e3684 · 2019-08-11T22:06:04.000+02:00
diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
@@ -0,0 +1,42 @@
+# Getting started
+Before you start, you should understand the concept of forward/up and reverse/down database migrations.
+
+Configure a database for your application. Make sure that your database driver is supported [here](README.md#databases)
+
+## Create migrations
+Create some migrations using migrate CLI. Here is an example:
+```
+migrate create -ext sql -dir db/migrations -seq create_users_table
+```
+Once you create your files, you should fill them.
+
+**IMPORTANT:** In a project developed by more than one person there is a small probability of migrations incosistency - e.g. two developers can create conflicting migrations, and the developer that created his migration later gets it merged to the repository first.
+Keep an eye on such cases (and be even more careful when cherry picking).
+
+Consider making your migrations idempotent - we can run the same sql code twice in a row with the same result. This makes our migrations more robust. On the other hand, it causes slightly less control over database schema - e.g. let's say you forgot to drop the table in down migration. You run down migration - the table is still there. When you run up migration again - `CREATE TABLE` would return an error, helping you find an issue in down migration, while `CREATE TABLE IF NOT EXISTS` would not. Use those conditions wisely.
+
+In case you would like to run several commands/queries in one migration, you should wrap them in a transaction (if your database supports it).
+This way if one of commands fails, our database will remain unchanged.
+
+## Run migrations
+Run your migrations through the CLI or your app and check if they applied expected changes.
+Just to give you an idea:
+```
+migrate -database YOUR_DATBASE_URL -path PATH_TO_YOUR_MIGRATIONS up
+```
+
+Just add the code to your app and you're ready to go!
+
+Before commiting your migrations you should run your migrations up, down, and then up again to see if migrations are working properly both ways.
+(e.g. if you created a table in a migration but reverse migration did not delete it, you will encounter an error when running the forward migration again)
+It's also worth checking your migrations in a separate, containerized environment. You can find some tools in the end of this document.
+
+**IMPORTANT:** If you would like to run multiple instances of your app on different machines be sure to use a database that supports locking when running migrations. Otherwise you may encounter issues.
+
+## Further reading:
+- [PostgreSQL tutorial](database/postgres/TUTORIAL.md)
+- [Best practices](MIGRATIONS.md)
+- [FAQ](FAQ.md)
+- Tools for testing your migrations in a container:
+	- https://github.com/dhui/dktest
+	- https://github.com/ory/dockertest
diff --git a/README.md b/README.md
@@ -142,7 +142,13 @@ func main() {
 
 ## Getting started
 
-Go to [tutorial](TUTORIAL.md)
+Go to [getting started](GETTING_STARTED.md)
+
+## Tutorials
+
+- [PostgreSQL](database/postgres/TUTORIAL.md)
+
+(more tutorials to come)
 
 ## Migration files
 
diff --git a/database/postgres/TUTORIAL.md b/database/postgres/TUTORIAL.md
@@ -1,7 +1,7 @@
-# Getting started
-Before you start, you should understand the concept of forward/up and reverse/down database migrations.
+# PostgreSQL tutorial for beginners
+
+## Create/configure database
 
-Configure a database for your application. Make sure that your database driver is supported [here](README.md#databases)
 For the purpose of this tutorial let's create PostgreSQL database called `example`.
 Our user here is `postgres`, password `password`, and host is `localhost`.
 ```
@@ -14,6 +14,7 @@ export POSTGRESQL_URL=postgres://postgres:password@localhost:5432/example?sslmod
 `sslmode=disable` means that the connection with our database will not be encrypted. Enabling it is left as an exercise.
 
 You can find further description of database URLs [here](README.md#database-urls).
+
 ## Create migrations
 Let's create table called `users`:
 ```
@@ -22,10 +23,8 @@ migrate create -ext sql -dir db/migrations -seq create_users_table
 If there were no errors, we should have two files available under `db/migrations` folder:
 - 000001_create_users_table.down.sql
 - 000001_create_users_table.up.sql
-Note the `sql` extension that we provided.
 
-**IMPORTANT:** In a project developed by more than one person there is a small probability of migrations incosistency - e.g. two developers can create conflicting migrations, and the developer that created his migration later gets it merged to the repository first.
-Keep an eye on such cases (and be even more careful when cherry picking).
+Note the `sql` extension that we provided.
 
 In the `.up.sql` file let's create the table:
 ```
@@ -40,10 +39,46 @@ And in the `.down.sql` let's delete it:
 ```
 DROP TABLE IF EXISTS users;
 ```
-By adding `IF EXISTS/IF NOT EXISTS` we are making migrations idempotent - we can run the same sql code twice in a row with the same result. This makes our migrations more robust. On the other hand, it causes slightly less control over database schema - e.g. let's say you forgot to drop the table in down migration. You run down migration - the table is still there. When you run up migration again - `CREATE TABLE` would return an error, helping you find an issue in down migration, while `CREATE TABLE IF NOT EXISTS` would not. Use those conditions wisely.
+By adding `IF EXISTS/IF NOT EXISTS` we are making migrations idempotent - you can read more about idempotency in [getting started](GETTING_STARTED.md#create-migrations)
 
-In case you would like to run several commands/queries in one migration, you should wrap them in a transaction (if your database supports it).
-In our postgres example it would be (migration up):
+## Run migrations
+```
+migrate -database ${POSTGRESQL_URL} -path db/migrations up
+```
+Let's check if the table was created properly by running `psql example -c "\d users"`.
+The output you are supposed to see:
+```
+                                    Table "public.users"
+  Column  |          Type          |                        Modifiers                        
+----------+------------------------+---------------------------------------------------------
+ user_id  | integer                | not null default nextval('users_user_id_seq'::regclass)
+ username | character varying(50)  | not null
+ password | character varying(50)  | not null
+ email    | character varying(300) | not null
+Indexes:
+    "users_pkey" PRIMARY KEY, btree (user_id)
+    "users_email_key" UNIQUE CONSTRAINT, btree (email)
+    "users_username_key" UNIQUE CONSTRAINT, btree (username)
+```
+Great! Now let's check if running reverse migration also works:
+```
+migrate -database ${POSTGRESQL_URL} -path db/migrations down
+```
+Make sure to check if your database changed as expected in this case as well.
+
+## Database transactions
+
+To show database transactions usage, let's create another set of migrations by running:
+```
+migrate create -ext sql -dir db/migrations -seq add_mood_to_users
+```
+Again, it should create for us two migrations files:
+- 000002_add_mood_to_users.down.sql
+- 000002_add_mood_to_users.up.sql
+
+In Postgres, when we want our queries to be done in a transaction, we need to wrap it with `BEGIN` and `COMMIT` commands.
+In our example, we are going to add a column to our database that can only accept enumerable values or NULL.
+Migration up:
 ```
 BEGIN;
 
@@ -56,14 +91,22 @@ ALTER TABLE users ADD COLUMN mood enum_mood;
 
 COMMIT;
 ```
-This way if one of commands fails, our database will remain unchanged.
+Migration down:
+```
+BEGIN;
 
-## Run migrations
+ALTER TABLE users DROP COLUMN mood;
+DROP TYPE enum_mood;
+
+COMMIT;
+```
+
+Now we can run our new migration and check the database:
 ```
 migrate -database ${POSTGRESQL_URL} -path db/migrations up
+psql example -c "\d users"
 ```
-Let's check if the table was created properly by running `psql example -c "\d users"`.
-The output you are supposed to see:
+Expected output:
 ```
                                     Table "public.users"
   Column  |          Type          |                        Modifiers                        
@@ -72,20 +115,12 @@ The output you are supposed to see:
  username | character varying(50)  | not null
  password | character varying(50)  | not null
  email    | character varying(300) | not null
+ mood     | enum_mood              | 
 Indexes:
     "users_pkey" PRIMARY KEY, btree (user_id)
     "users_email_key" UNIQUE CONSTRAINT, btree (email)
     "users_username_key" UNIQUE CONSTRAINT, btree (username)
 ```
-Great! Now let's check if running reverse migration also works:
-```
-migrate -database ${POSTGRESQL_URL} -path db/migrations down
-```
-Make sure to check if your database changed as expected in this case as well.
-
-**IMPORTANT:** Before commiting your migrations you should run your migrations up, down, and then up again to see if migrations are working properly both ways.
-(e.g. if you created a table in a migration but reverse migration did not delete it, you will encounter an error when running the forward migration again)
-It's also worth checking your migrations in a separate, containerized environment. You can find some tools in the end of this tutorial.
 
 ## Optional: Run migrations within your Go app
 Here is a very simple app running migrations for the above configuration:
@@ -110,15 +145,4 @@ func main() {
 	}
 }
 ```
-You can find details [here](README.md#use-in-your-go-project)
-
-Just add the code to your app and you're ready to go!
-
-**IMPORTANT:** If you would like to run multiple instances of your app on different machines be sure to use a database that supports locking when running migrations. Otherwise you may encounter issues.
-
-## Further reading:
-- [Best practices](MIGRATIONS.md)
-- [FAQ](FAQ.md)
-- Tools for testing your migrations in a container:
-	- https://github.com/dhui/dktest
-	- https://github.com/ory/dockertest
+You can find details [here](README.md#use-in-your-go-project)
