docs - troubleshooting guide: load from h2 (#17209)

docs/operations-guide/migrating-from-h2.md

@@ -1,8 +1,25 @@
-# Migrating from using the H2 database to MySQL or Postgres
+# Migrating from using the H2 database to Postgres or MySQL/MariaDB
 
-If you decide to use the default application database (H2) when you initially start using Metabase, but later decide that you'd like to switch to a more production-ready database such as MySQL or Postgres, we make the transition easy for you.
+If you decide to use the default application database (H2) when you initially start using Metabase, but later decide that you'd like to switch to a more production-ready database such as Postgres or MySQL/MariaDB, you're in the right place.
 
-Metabase provides a custom migration command for upgrading H2 application database files by copying their data to a new database. Here's what you'll want to do:
+## Before you migrate
+
+- Avoid upgrading and migrating at the same time, since it can cause problems if one of the database schemas doesn't match.
+- You must be able to connect to the target Postgres or MySQL/MariaDB database in whatever environment you're running this migration command in. So, if you are attempting to move the data to a cloud database, make sure you can connect to that database.
+
+### Migrating when using Docker
+
+We recommend running the migration outside of Docker. You'll need to copy the H2 file out of the Docker container before migrating. For example, if the container is called metabase, you'd run:
+
+```
+docker cp metabase:/metabase.db/metabase.db.mv.db ./
+```
+
+The above command would copy the database file to the directory you ran the command from. With your database file outside of the container, all you need to do is follow the "How to migrate" steps below.
+
+## How to migrate 
+
+Metabase provides a custom migration command for upgrading H2 application database files by copying their data to a new database. Here's what you'll do:
 
 1. Shutdown your Metabase instance so that it's not running. This ensures no accidental data gets written to the db while migrating.
 2. Make a backup copy of your H2 application database by following the instructions in [Backing up Metabase Application Data](backing-up-metabase-application-data.md). Safety first!
@@ -15,15 +32,23 @@ export MB_DB_PORT=5432
 export MB_DB_USER=<username>
 export MB_DB_PASS=<password>
 export MB_DB_HOST=localhost
-java -jar metabase.jar load-from-h2 /path/to/metabase.db # do not include .mv.db or .h2.db suffix
+java -jar metabase.jar load-from-h2 /path/to/metabase.db # do not include .mv.db
 ```
 
-It is expected that you will run the command against a brand-new (empty!) database; Metabase will handle all of the work of creating the database schema and migrating the data for you.
+Note that the file name of the database file itself might be `/path/to/metabase.db.mv.db`, but when running the `load-from-h2` command, you need to truncate the path to `/path/to/metabase.db`.
+
+Metabase expects that you'll run the command against a brand-new (empty) database; it'll create the database schema and migrate the data for you.
+
+### PostgreSQL notes
+
+-  Minimum version is PostgreSQL 9.4, since the code that handles these migrations uses a command that is only available in version 9.4 or newer.
+
+### MySQL/MariaDB notes
+
+- MySQL minimum recommended version is 5.7.7.
+- MariaDB minimum recommended version is 10.2.2.
+- And the following database settings are required (the settings are the default in the above recommended versions): `utf8mb4_unicode_ci` collation, `utf8mb4` character set, and `innodb_large_prefix=ON`.
 
-#### Notes
+### Troubleshooting
 
-- Avoid upgrading and migrating at the same time, since it can cause problems with one of database schemas not matching.
-- It is required that you can connect to the target MySQL or Postgres database in whatever environment you are running this migration command in. So, if you are attempting to move the data to a cloud database, make sure you take that into consideration.
-- For MySQL or MariaDB, the minimum recommended version is MySQL 5.7.7 and MariaDB 10.2.2, while the following is required: `utf8mb4_unicode_ci` collation, `utf8mb4` character set, and `innodb_large_prefix=ON`.
-- For PostgreSQL, the minimum version is PostgreSQL 9.4, since the code that handles these migrations uses a command that is only available in version 9.4 or newer.
-- H2 automatically adds a `.h2.db` or `.mv.db` extension to the database path you specify, so make sure the path to the DB file you pass to the command _does not_ include it. For example, if you have a file named `/path/to/metabase.db.h2.db`, call the command with `load-from-h2 /path/to/metabase.db`.
+If you get an error, check out [Error when loading application database from H2](../troubleshooting-guide/loading-from-h2.md).

docs/troubleshooting-guide/application-database.md

@@ -6,13 +6,15 @@ Metabase stores information about users, questions, and so on in a database of i
 
 ### Metabase fails to start due to database locks
 
-Sometimes Metabase will fail to complete its startup due to a database lock that was not cleared properly. The error message will look something like:
+Sometimes Metabase will fail to start up because a database lock did not clear properly. 
+
+**How to detect this:** The error message will look something like:
 
 ```
 liquibase.exception.DatabaseException: liquibase.exception.LockException: Could not acquire change log lock.
 ```
 
-When this happens, open a shell on the server where Metabase is installed and run:
+**How to fix this:** When this happens, open a shell on the server where Metabase is installed and run:
 
 ```
 java -jar metabase.jar migrate release-locks
@@ -22,7 +24,9 @@ This command will manually clear the locks. When it's done, restart your Metabas
 
 ### Metabase H2 application database gets corrupted
 
-By default, Metabase uses [H2][what-is-h2] for its application database. Because H2 is an on-disk database, it's sensitive to filesystem errors, such as a drive being corrupted or a file not being flushed properly. In these situations, you'll see errors on startup. These vary, but one example is:
+By default, Metabase uses [H2][what-is-h2] for its application database. Because H2 is an on-disk database, it's sensitive to filesystem errors, such as a drive being corrupted or a file not being flushed properly. In these situations, you'll see errors on startup. 
+
+**How to detect this:** Error messages will vary, but one example is:
 
 ```
 myUser@myIp:~$ java -cp metabase.jar org.h2.tools.RunScript -script whatever.sql -url jdbc:h2:~/metabase.db
@@ -31,7 +35,7 @@ Exception in thread "main" org.h2.jdbc.JdbcSQLException: Row not found when tryi
     [etc]
 ```
 
-Not all H2 errors are recoverable (which is why if you're using H2, _please_ have a backup strategy for the application database file). To attempt to recover a corrupted H2 file with a recent version of Metabase, try the commands shown below:
+**How to fix this:** To attempt to recover a corrupted H2 file with a recent version of Metabase, try the commands shown below:
 
 ```
 java -cp metabase.jar org.h2.tools.Recover
@@ -49,15 +53,18 @@ touch metabase.db.h2.db
 java -cp target/uberjar/metabase.jar org.h2.tools.RunScript -script metabase.db.h2.sql -url jdbc:h2:`pwd`/metabase.db;MV_STORE=FALSE
 ```
 
+Not all H2 errors are recoverable (which is why if you're using H2, _please_ have a backup strategy for the application database file).
+
 ### Metabase fails to connect to H2 Database on Windows 10
 
-In some situations on Windows 10, the Metabase JAR needs to have permissions to create local files for the application database. If the Metabase JAR lacks permissions, you might see an error message like this when running the JAR:
+In some situations on Windows 10, the Metabase JAR needs to have permissions to create local files for the application database. 
+
+**How to detect this:** If the Metabase JAR lacks permissions, you might see an error message like this when running the JAR:
 
 ```
 Exception in thread "main" java.lang.AssertionError: Assert failed: Unable to connect to Metabase DB.
 ```
 
-You can unblock the file by right-clicking on it, clicking "Properties," and then clicking "Unblock." See [Microsoft's documentation][ms-unblocking-file] for more details on unblocking downloaded files.
+**How to fix this:** You can unblock the file by right-clicking on it, clicking "Properties," and then clicking "Unblock." 
 
-[ms-unblocking-file]: https://blogs.msdn.microsoft.com/delay/p/unblockingdownloadedfile/
-[what-is-h2]: /faq/setup/what-is-h2.html
+[what-is-h2]: ../faq/setup/what-is-h2.html

docs/troubleshooting-guide/datawarehouse.md

@@ -71,4 +71,4 @@ If your credentials are incorrect, you should see an error message letting you k
 [ec2-troubleshooting]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html
 [elb-timeout]: https://aws.amazon.com/blogs/aws/elb-idle-timeout-control/
 [heroku-timeout]: https://devcenter.heroku.com/articles/request-timeout
-[native-question]: ../users-guide/writing-sql.md
+[native-question]: ../users-guide/writing-sql.html

docs/troubleshooting-guide/loading-from-h2.md

@@ -0,0 +1,33 @@
+## Loading exported application database fails 
+
+If you've been using the default H2 application database that ships with Metabase, and want to [migrate from the default H2 application database][migrate] to a production database like [PostgreSQL][postgres] or MySQL/MariaDB, you'll need to use the `load-from-h2` command, which will fail if the database filename is incorrect. 
+
+**How to detect this:** When running the `load-from-h2` command, you'll see an error that looks something like:
+
+```
+Command failed with exception: Unsupported database file version or invalid file header in file <YOUR FILENAME> 
+```
+
+**How to fix this:** First, make sure to create a copy of the exported H2 database (see [Backing up Metabase Application Data][backup]).
+
+Next, check that the exported, application database file (the H2 database you exported) is named `metabase.db.mv.db`. H2 automatically adds a `.mv.db` extension to the database path you specify, so make sure the path to the DB file you pass to the command does not include the `.mv.db` extension.
+
+For example, if you've exported an application database, and you want to load the data from that H2 database into a PostgreSQL database using `load-from-h2`, your command will look something like:
+
+```
+export MB_DB_TYPE=postgres
+export MB_DB_DBNAME=metabase
+export MB_DB_PORT=5432
+export MB_DB_USER=<username>
+export MB_DB_PASS=<password>
+export MB_DB_HOST=localhost
+java -jar metabase.jar load-from-h2 /path/to/metabase.db # do not include .mv.db
+```
+
+If you're using Metabase Enterprise Edition, you should check out the [Serialization][serialization-docs] feature to snapshot your application database. Serialization is useful when you want to [preload questions and dashboards][serialization-learn] in a new Metabase instance.
+
+[backup]: ../operations-guide/backing-up-metabase-application-data.html
+[migrate]: ../operations-guide/migrating-from-h2.html
+[postgres]: https://www.postgresql.org/
+[serialization-docs]: ../enterprise-guide/serialization.html
+[serialization-learn]: https://www.metabase.com/learn/administration/serialization.html

docs/users-guide/writing-sql.md

@@ -37,8 +37,7 @@ You can use [SQL snippets](sql-snippets.md) to save, reuse, and share SQL code a
 
 ### Learn more
 
-- [Best practices for writing SQL queries](https://www.metabase.com/blog/sql-best-practices/index.html).
-
+- [Best practices for writing SQL queries](https://www.metabase.com/learn/sql-questions/sql-best-practices.html) 
 
 ---