Merge pull request #3 from linuxserver/readme-update

Important documentation update for setting DATABASE_URL with version 2.0.30 and later
linuxserver · Aug 21, 2023 · 1905e6f · 1905e6f
2 parents fd97013 + 85706be
commit 1905e6f
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -67,14 +67,19 @@ The architectures supported by this image are:
 
 You have to replace the following values with your defaults:
 
-- the database username "your_db_user"
-- the database password "your_db_pass"
-- the database schema name "your_db_name"
-- the database host or IP "your_db_host"
-- you might have to adapt port "3306" as well
+* the database username "your_db_user"
+* the database password "your_db_pass"
+* the database schema name "your_db_name"
+* the database host or IP "your_db_host"
+* the database character set "your_db_charset" (usually "utf8")
+* the database version "your_db_version"
+  * run `SELECT VERSION();` in your MariaDB/MySQL database to get the version
+  * example for [MariaDB](https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html#mariadb) use "10.11.4-MariaDB-log"
+  * example for [MySQL](https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html#mysql) use "8.0.32"
+* you might have to adapt port "3306" as well
 
 ```env
-DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name
+DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name?charset=your_db_charset&serverVersion=your_db_version
 ````
 
 ### Create your first user
@@ -104,7 +109,7 @@ services:
       - PUID=1000
       - PGID=1000
       - TZ=Etc/UTC
-      - DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name
+      - DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name?charset=your_db_charset&serverVersion=your_db_version
     volumes:
       - /path/to/appdata/config:/config
     ports:
@@ -141,7 +146,7 @@ docker run -d \
   -e PUID=1000 \
   -e PGID=1000 \
   -e TZ=Etc/UTC \
-  -e DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name \
+  -e DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name?charset=your_db_charset&serverVersion=your_db_version \
   -p 80:80 \
   -p 443:443 \
   -v /path/to/appdata/config:/config \
@@ -177,7 +182,7 @@ Container images are configured using parameters passed at runtime (such as thos
 | `-e PUID=1000` | for UserID - see below for explanation |
 | `-e PGID=1000` | for GroupID - see below for explanation |
 | `-e TZ=Etc/UTC` | specify a timezone to use, see this [list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). |
-| `-e DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name` | Configure your database connection |
+| `-e DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name?charset=your_db_charset&serverVersion=your_db_version` | Configure your database connection, see Application Setup instructions. |
 | `-v /config` | Configuration files. |
 
 ## Environment variables from files (Docker secrets)
@@ -289,4 +294,5 @@ Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64
 
 ## Versions
 
+* **21.08.23:** - Important documentation update for setting `DATABASE_URL` with version 2.0.30 and later.
 * **09.08.23:** - Initial Release.
diff --git a/readme-vars.yml b/readme-vars.yml
@@ -31,7 +31,7 @@ common_param_env_vars_enabled: true
 param_container_name: "{{ project_name }}"
 param_usage_include_env: true
 param_env_vars:
-  - { env_var: "DATABASE_URL", env_value: "mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name", desc: "Configure your database connection"}
+  - { env_var: "DATABASE_URL", env_value: "mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name?charset=your_db_charset&serverVersion=your_db_version", desc: "Configure your database connection, see Application Setup instructions."}
 param_usage_include_vols: true
 param_volumes:
   - { vol_path: "/config", vol_host_path: "/path/to/appdata/config", desc: "Configuration files.", name: "Appdata" }
@@ -52,14 +52,19 @@ app_setup_block: |
 
   You have to replace the following values with your defaults:
 
-  - the database username "your_db_user"
-  - the database password "your_db_pass"
-  - the database schema name "your_db_name"
-  - the database host or IP "your_db_host"
-  - you might have to adapt port "3306" as well
+  * the database username "your_db_user"
+  * the database password "your_db_pass"
+  * the database schema name "your_db_name"
+  * the database host or IP "your_db_host"
+  * the database character set "your_db_charset" (usually "utf8")
+  * the database version "your_db_version"
+    * run `SELECT VERSION();` in your MariaDB/MySQL database to get the version
+    * example for [MariaDB](https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html#mariadb) use "10.11.4-MariaDB-log"
+    * example for [MySQL](https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html#mysql) use "8.0.32"
+  * you might have to adapt port "3306" as well
 
   ```env
-  DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name
+  DATABASE_URL=mysql://your_db_user:your_db_pass@your_db_host:3306/your_db_name?charset=your_db_charset&serverVersion=your_db_version
   ````
 
   ### Create your first user
@@ -112,4 +117,5 @@ external_application_unraid_block: "We recommend using our [MariaDB](https://git
 
 # changelog
 changelogs:
+  - { date: "21.08.23:", desc: "Important documentation update for setting `DATABASE_URL` with version 2.0.30 and later." }
   - { date: "09.08.23:", desc: "Initial Release." }