From 61012d1f66aa2e523b9223c07469aeda7bcb4b49 Mon Sep 17 00:00:00 2001
From: Jeff Bruemmer <jeff.bruemmer@gmail.com>
Date: Tue, 23 Jul 2024 17:01:46 -0400
Subject: [PATCH] docs - mysql appdb note (#45956)

* notes

* more notes

* edits

* update app db page

* file-based db mention

* anchor link
---
 .../configuring-application-database.md       | 200 ++++++++++--------
 1 file changed, 114 insertions(+), 86 deletions(-)

diff --git a/docs/installation-and-operation/configuring-application-database.md b/docs/installation-and-operation/configuring-application-database.md
index 5a731acbad3..70188af2509 100644
--- a/docs/installation-and-operation/configuring-application-database.md
+++ b/docs/installation-and-operation/configuring-application-database.md
@@ -6,71 +6,129 @@ redirect_from:
 
 # Configuring the Metabase application database
 
-The application database is where Metabase stores information about users, saved questions, dashboards, and any other
-data needed to run the application. The default settings use an embedded H2 database, but this is configurable.
+The application database is where Metabase stores information about user accounts, questions, dashboards, and any other data needed to run the Metabase application.
 
-## Notes
+For production, we recommend using PostgreSQL as your application database.
 
-- Using Metabase with an H2 application database is not recommended for production deployments. For production
-  deployments, we highly recommend using PostgreSQL. If you decide to continue to use H2, please be sure to back up the database file regularly.
-- You cannot change the application database while the application is running. Connection configuration information is
-  read only once when the application starts up and will remain constant throughout the running of the application.
-- Metabase provides limited support for migrating from H2 to Postgres if you decide to upgrade to a more
-  production-ready database. See [Migrating from H2 to PostgreSQL](migrating-from-h2.md) for more details.
+- [PostgreSQL](#postgresql) (recommended for production)
+- [MySQL](#mysql-or-mariadb) (also works for production)
+- [H2](#h2-application-database) (default for local demos - AVOID in production)
 
-## [H2](https://www.h2database.com/) (default)
+Metabase will read the connection configuration information when the application starts up. You can't change the application database while the application is running.
 
-> **For production installations of Metabase we recommend that people [replace the H2 database with PostgreSQL](./migrating-from-h2.md)**. Postgres offers a greater degree of performance and reliability when Metabase is running with many users.
+## PostgreSQL
 
-To use the H2 database for your Metabase instance you don't need to do anything at all. When the application is first launched it will attempt to create a new H2 database in the same filesystem location the application is launched from.
+We recommend that you use [PostgreSQL](https://www.postgresql.org/) for your Metabase application database.
 
-You can see these database files from the terminal:
+You can use [environment variables](../configuring-metabase/environment-variables.md) to set a Postgres database as Metabase's application database. For example, the following commands tell Metabase to use a Postgres database as its application database:
 
-    ls metabase.*
+```sh
+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
+```
 
-You should see the following files:
+Metabase will not create a Postgres database for you. Example command to create the database:
+
+```sh
+createdb --encoding=UTF8 -e metabase
+```
+
+If you have additional parameters, Metabase also supports providing a full JDBC connection string:
+
+```sh
+export MB_DB_CONNECTION_URI="jdbc:postgresql://localhost:5432/metabase?user=<username>&password=<password>"
+java -jar metabase.jar
+```
+
+If you want to pass the connection URI, user, and password credentials separately from the JDBC connection string (useful if the password contains special characters), you can use the `MB_DB_CONNECTION_URI` [environment variable](../configuring-metabase/environment-variables.md) in combination with `MB_DB_USER` and `MB_DB_PASS` variables:
+
+```sh
+export MB_DB_CONNECTION_URI="jdbc:postgresql://localhost:5432/metabase"
+export MB_DB_USER=<username>
+export MB_DB_PASS=<password>
+java -jar metabase.jar
+```
+
+## MySQL or MariaDB
+
+We recommend [PostgreSQL](#postgresql), but you can also use [MySQL](https://www.mysql.com/) or [MariaDB](https://www.mariadb.org/).
+
+The minimum recommended version is MySQL 8.0.17 or MariaDB 10.2.2. The `utf8mb4` character set is required.
+
+You can change the application database to use MySQL using environment variables like so:
+
+```sh
+export MB_DB_TYPE=mysql
+export MB_DB_DBNAME=metabase
+export MB_DB_PORT=3306
+export MB_DB_USER=<username>
+export MB_DB_PASS=<password>
+export MB_DB_HOST=localhost
+java -jar metabase.jar
+```
+
+Metabase won't create this database for you. Example SQL statement to create the database:
+
+```sh
+CREATE DATABASE metabase CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+The following command will tell Metabase to look for its application database using the supplied MySQL connection information. Metabase also supports providing a full JDBC connection string if you have additional parameters:
+
+```sh
+export MB_DB_CONNECTION_URI="jdbc:mysql://localhost:3306/metabase?user=<username>&password=<password>"
+java -jar metabase.jar
+```
 
-    metabase.db.h2.db  # Or metabase.db.mv.db depending on when you first started using Metabase.
-    metabase.db.trace.db
+As with Postgres, `MB_DB_CONNECTION_URI` can also be used in combination with `MB_DB_USER` and/or `MB_DB_PASS` if you
+want to pass one or both separately from the rest of the JDBC connection string:
 
-If for any reason you want to use an H2 database file in a separate location from where you launch Metabase you can do so using an environment variable. For example:
+```sh
+export MB_DB_CONNECTION_URI="jdbc:mysql://localhost:5432/metabase"
+export MB_DB_USER=<username>
+export MB_DB_PASS=<password>
+java -jar metabase.jar
+```
 
-    export MB_DB_TYPE=h2
-    export MB_DB_FILE=/the/path/to/my/h2.db
-    java -jar metabase.jar
+## H2 application database
 
-Note that H2 automatically appends `.mv.db` or `.h2.db` to the path you specify; do not include those in your path! In other words, `MB_DB_FILE` should be something like `/path/to/metabase.db`, rather than something like `/path/to/metabase.db.mv.db` (even though this is the file that actually gets created).
+> **For production installations of Metabase we recommend that people [replace the default H2 database with PostgreSQL](./migrating-from-h2.md)**. Postgres offers a greater degree of performance and reliability.
 
-## [Postgres](https://www.postgresql.org/)
+By default, Metabase ships with an [H2 database](https://www.h2database.com/) to make it easy to demo Metabase on your local machine. **Avoid using this default database in production**.
 
-You can change the application database to use Postgres using a few simple environment variables. For example:
+If when launching Metabase you don't provide environment variables that specify connection details for a production database, Metabase will attempt to create a new H2 database in the same directory as the Metabase JAR.
 
-    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
+H2 is a file-based database, and you can see these H2 database files from the terminal:
 
-Metabase will not create this database for you. Example command to create the database:
+```sh
+ls metabase.*
+```
 
-    createdb --encoding=UTF8 -e metabase
+You should see the following files:
 
-This will tell Metabase to look for its application database using the supplied Postgres connection information.
-Metabase also supports providing a full JDBC connection string if you have additional parameters:
+```sh
+metabase.db.h2.db  # Or metabase.db.mv.db depending on when you first started using Metabase.
+metabase.db.trace.db
+```
 
-    export MB_DB_CONNECTION_URI="jdbc:postgresql://localhost:5432/metabase?user=<username>&password=<password>"
-    java -jar metabase.jar
+If you want to use an H2 database file in a particular directory, use the `MB_DB_TYPE` and `MB_DB_FILE` environment variables:
 
-`MB_DB_CONNECTION_URI` can also be used in combination with `MB_DB_USER` and/or `MB_DB_PASS` if you want to pass one
-or both separately from the rest of the JDBC connection string (useful if the password contains special characters):
+```sh
+export MB_DB_TYPE=h2
+export MB_DB_FILE=/the/path/to/my/h2.db
+java -jar metabase.jar
+```
+
+Note that H2 automatically appends `.mv.db` or `.h2.db` to the path you specify; exclude those extensions in your path! In other words, `MB_DB_FILE` should be something like `/path/to/metabase.db`, rather than something like `/path/to/metabase.db.mv.db` (even though the latter is the file that Metabase will create).
 
-    export MB_DB_CONNECTION_URI="jdbc:postgresql://localhost:5432/metabase"
-    export MB_DB_USER=<username>
-    export MB_DB_PASS=<password>
-    java -jar metabase.jar
+## Migrating from H2
 
+If you've started out using the default, H2 database, but you want to preserve the content you've created and move to a production application database, Metabase provides limited support for [migrating from H2 to PostgreSQL](migrating-from-h2.md).
 
 ## Upgrading from a Metabase version pre-0.38
 
@@ -83,66 +141,36 @@ You can resolve this failure in one of two ways:
 
 How you configure your connection depends on whether you're using Postgres as Metabase's application database or as a data warehouse connected to Metabase:
 
-**For Postgres application databases**:
+### SSL certificate validation for Postgres _application_ databases
 
-To use SSL certificate validation, you'll need to use the `MB_DB_CONNECTION_URI` method to configure your database connection. Here's an example:
+To use SSL certificate validation, you'll need to use the `MB_DB_CONNECTION_URI` environment variable to configure your database connection. Here's an example:
 
-```
+```sh
 export MB_DB_CONNECTION_URI="postgres://localhost:5432/metabase?user=<username>&password=<password>&sslmode=verify-ca&sslrootcert=<path to CA root or intermediate root certificate>"
 ```
 
-If you cannot enable certificate validation, you can enable the `NonValidatingFactory` for your application database via the same environment variable as above:
+If you can't enable certificate validation, you can enable the `NonValidatingFactory` for your application database:
 
-```
+```sh
 export MB_DB_CONNECTION_URI="postgres://localhost:5432/metabase?user=<username>&password=<password>&ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory"
 ```
 
-**For Postgres data warehouse databases**
+### SSL certificate validation for Postgres _data warehouse_ databases
 
-You can do the same inside the Metabase Admin page for the connection to your Postgres database. Add the following to the end of your JDBC connection string for your database:
+Add the following to the end of your JDBC connection string for your database:
 
-```
+```sh
 &sslmode=verify-ca&sslrootcert=<path to CA root or intermediate root certificate>
 ```
 
-If that does not work, you can enable `NonValidatingFactory` by adding the following to the end of your connection URI for your database:
+If that fails, you can enable `NonValidatingFactory` by adding the following to the end of your connection URI for your database:
 
-```
+```sh
 &ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory
 ```
 
-For more options to further tune the SSL connection parameters,
-see the [PostgreSQL SSL client documentation](https://jdbc.postgresql.org/documentation/ssl/#configuring-the-client).
-
-
-## [MySQL](https://www.mysql.com/) or [MariaDB](https://www.mariadb.org/)
-
-We recommend PostgreSQL, but you can also use MySQL or MariaDB. The minimum recommended version is MySQL 8.0.17 or MariaDB
-10.2.2, and the `utf8mb4` character set is required. You can change the application database to use MySQL using
-environment variables like this:
-
-    export MB_DB_TYPE=mysql
-    export MB_DB_DBNAME=metabase
-    export MB_DB_PORT=3306
-    export MB_DB_USER=<username>
-    export MB_DB_PASS=<password>
-    export MB_DB_HOST=localhost
-    java -jar metabase.jar
-
-Metabase will not create this database for you. Example SQL statement to create the database:
+For more options to further tune the SSL connection parameters, see the [PostgreSQL SSL client documentation](https://jdbc.postgresql.org/documentation/ssl/#configuring-the-client).
 
-    CREATE DATABASE metabase CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-
-This will tell Metabase to look for its application database using the supplied MySQL connection information. Metabase
-also supports providing a full JDBC connection string if you have additional parameters:
-
-    export MB_DB_CONNECTION_URI="jdbc:mysql://localhost:3306/metabase?user=<username>&password=<password>"
-    java -jar metabase.jar
-
-As with Postgres, `MB_DB_CONNECTION_URI` can also be used in combination with `MB_DB_USER` and/or `MB_DB_PASS` if you
-want to pass one or both separately from the rest of the JDBC connection string:
+## Further reading
 
-    export MB_DB_CONNECTION_URI="jdbc:mysql://localhost:5432/metabase"
-    export MB_DB_USER=<username>
-    export MB_DB_PASS=<password>
-    java -jar metabase.jar
+- [Environment variables](../configuring-metabase/environment-variables.md)
-- 
GitLab