Merge pull request #361 from mknycha/add-docs-info-about-dirty-database

Docs: add info about troubleshooting dirty database

Author: Prometheus2677

FAQ.md

@@ -73,4 +73,7 @@ Database-specific locking features are used by *some* database drivers to preven
 No, it is done automatically.
 
 #### Can I use migrate with a non-Go project?
-Yes, you can use the migrate CLI in a non-Go project, but there are probably other libraries/frameworks available that offer better test and deploy integrations in that language/framework.
+Yes, you can use the migrate CLI in a non-Go project, but there are probably other libraries/frameworks available that offer better test and deploy integrations in that language/framework.
+
+#### I have got an error `Dirty database version 1. Fix and force version`. What should I do?
+Keep calm and refer to [the getting started docs](GETTING_STARTED.md#forcing-your-database-version).

GETTING_STARTED.md

@@ -34,6 +34,16 @@ It's also worth checking your migrations in a separate, containerized environmen
 
 **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.
 
+## Forcing your database version
+In case you run a migration that contained an error, migrate will not let you run other migrations on the same database. You will see an error `Dirty database version 1. Fix and force version`, even when you fix migration. This means your database was marked as 'dirty'.
+You need to investigate the migration error - was your migration applied partially, or was it not applied at all? Once you know, you should force your database to a version reflecting it's real state. You can do so with `force` command:
+```
+migrate -path PATH_TO_YOUR_MIGRATIONS -database YOUR_DATBASE_URL force VERSION
+```
+Once you force the version and your migration was fixed, your database is 'clean' again and you can proceed with your migrations.
+
+For details and example of usage see [this comment](https://github.com/golang-migrate/migrate/issues/282#issuecomment-530743258).
+
 ## Further reading:
 - [PostgreSQL tutorial](database/postgres/TUTORIAL.md)
 - [Best practices](MIGRATIONS.md)