feat(docs): Improve docs on migrations

docs/content/docs/developer-guide/migrations.md

@@ -12,7 +12,7 @@ Database migrations are needed whenever the database schema changes. This can be
 
 ## Synchronize vs migrate
 
-TypeORM (which Vendure uses to interact with the database layer) has a `synchronize` option which, when set to `true`, will automatically update your database schema to reflect the current Vendure configuration.
+TypeORM (which Vendure uses to interact with the database) has a `synchronize` option which, when set to `true`, will automatically update your database schema to reflect the current Vendure configuration.
 
 This is convenient while developing, but should not be used in production, since a misconfiguration could potentially delete production data. In this case, migrations should be used.
 
@@ -34,12 +34,18 @@ export const config: VendureConfig = {
 
 ### Generate a migration
 
-The [`generateMigration` function]({{< relref "generate-migration" >}}) will compare the provided VendureCofig against the current database schema and generate a new migration file containing SQL statements which, when applied to the current database, will modify the schema to fit with the configuration. It will also contain statements to revert these changes.
+The [`generateMigration` function]({{< relref "generate-migration" >}}) will compare the provided VendureConfig against the current database schema and generate a new migration file containing SQL statements which, when applied to the current database, will modify the schema to fit with the configuration. It will also contain statements to revert these changes.
 
 ### Run migrations
 
 The [`runMigrations` function]({{< relref "run-migrations" >}}) will apply any migrations files found according to the pattern provided to `dbConnectionOptions.migrations` to the database. TypeORM keeps a track of which migrations have already been applied, so running this function multiple times will not apply the same migration more than once.
 
+{{% alert "warning" %}}
+⚠ TypeORM will attempt to run each migration inside a transaction. This means that if one of the migration commands fails, then the entire transaction will be rolled back to its original state.
+
+_However_ this is **not supported by MySQL / MariaDB**. This means that when using MySQL or MariaDB, errors in your migration script could leave your database in a broken or inconsistent state. Therefore it is **critical** that you first create a backup of your database before running a migration.
+{{< /alert >}}
+
 ### Revert a migration
 
 The [`runMigrations` function]({{< relref "run-migrations" >}}) will revert the last applied migration. If run again it will then revert the one before that, and so on.

docs/content/docs/developer-guide/updating-vendure.md

@@ -58,10 +58,11 @@ The key rule is **never run your production instance with the `synchronize` opti
 For any database schema changes, it is advised to:
 
 1. Read the changelog breaking changes entries to see what changes to expect
-2. Create a new database migration as described in the [Migrations guide](https://www.vendure.io/docs/developer-guide/migrations/)
-3. Manually check the migration script. In some cases manual action is needed to customize the script in order to correctly migrate your existing data.
-4. Test the migration script against non-production data.
-5. Only when you have verified that the migration works as expected, run it against your production database.
+2. **Important:** Make a backup of your database!
+3. Create a new database migration as described in the [Migrations guide]({{< relref "migrations" >}})
+4. Manually check the migration script. In some cases manual action is needed to customize the script in order to correctly migrate your existing data.
+5. Test the migration script against non-production data.
+6. Only when you have verified that the migration works as expected, run it against your production database.
 
 ### GraphQL schema changes