diff --git a/README.md b/README.md
index f181db4..6d0f2d1 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,9 @@ Prerequisites:
 8. **direnv** (optional, but recommended)
 
 ```shell
+# if you have direnv installed
+direnv allow
+
 # install git hooks and required tools
 make install
 
@@ -46,6 +49,15 @@ go test -v ./...
 TESTS_DB_DSN=postgres://sessions:sessions_pass@127.0.0.1/sessions go test -v ./... 
 ```
 
+#### Creating a new database migration
+
+```shell
+# create a migration
+go run ./cmd/sessions/main.go db migration create go migration 1
+```
+
+![img.png](docs/migration.png)
+
 ## Configuration options
 
 Configuration options can be specified via environment variables.
@@ -65,7 +77,6 @@ Configuration options can be specified via environment variables.
 | ``API_CORS_ALLOW_CREDENTIALS`` | ``false``             | Whether requests with credentials are allowed                                                                  |
 | ``API_CORS_ALLOWED_METHODS``   | ``HEAD,GET,POST,PUT`` | Comma-separated list of allowed methods                                                                        |
 | ``API_CORS_MAX_AGE``           | ``300``               | Max time to cache response (seconds)                                                                           |
-|                                |                       |                                                                                                                |
 
 ## License
 
diff --git a/docs/migration.png b/docs/migration.png
new file mode 100644
index 0000000..613a70c
Binary files /dev/null and b/docs/migration.png differ