Documents some issues and the required manual fixes for MariaDB

docs/advanced_usage.rst

@@ -424,3 +424,24 @@ For example, using Docker Compose:
         # ...
         volumes:
           - /path/to/my/scripts:/custom-cont-init.d:ro
+
+.. _advanced-mysql-caveats:
+
+MySQL Caveats
+#############
+
+Case Sensitivity
+================
+
+The database interface does not provide a method to configure a MySQL database to
+be case sensitive.  This would prevent a user from creating a tag ``Name`` and ``NAME``
+as they are considered the same.
+
+Per Django documentation, to enable this requires manual intervention.  To enable
+case sensetive tables, you can execute the following command against each table:
+
+``ALTER TABLE <table_name> CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;``
+
+You can also set the default for new tables (this does NOT affect existing tables) with:
+
+``ALTER DATABASE <db_name> CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;``

docs/configuration.rst

@@ -38,8 +38,14 @@ PAPERLESS_REDIS=<url>
 PAPERLESS_DBENGINE=<engine_name>
     Optional, gives the ability to choose Postgres or MariaDB for database engine.
     Available options are `postgresql` and `mariadb`.
+
     Default is `postgresql`.
 
+    .. warning::
+
+      Using MariaDB comes with some caveats.  See :ref:`advanced-mysql-caveats` for details.
+
+
 PAPERLESS_DBHOST=<hostname>
     By default, sqlite is used as the database backend. This can be changed here.
 

docs/setup.rst

@@ -649,7 +649,7 @@ Migration to paperless-ngx is then performed in a few simple steps:
 
 
 Migrating from LinuxServer.io Docker Image
-========================
+==========================================
 
 As with any upgrades and large changes, it is highly recommended to create a backup before
 starting.  This assumes the image was running using Docker Compose, but the instructions
@@ -663,7 +663,7 @@ are translatable to Docker commands as well.
         to step 4.
     b)  Otherwise, in the ``docker-compose.yml`` add a new service for Redis,
         following `the example compose files <https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose>`_
-    b)  Set the environment variable ``PAPERLESS_REDIS`` so it points to the new Redis container
+    c)  Set the environment variable ``PAPERLESS_REDIS`` so it points to the new Redis container
 
 4.  Update user mapping
 
@@ -692,11 +692,12 @@ are translatable to Docker commands as well.
 
 .. _setup-sqlite_to_psql:
 
-Moving data from SQLite to PostgreSQL
+Moving data from SQLite to PostgreSQL or MySQL/MariaDB
-=====================================
+======================================================
 
-Moving your data from SQLite to PostgreSQL is done via executing a series of django
+Moving your data from SQLite to PostgreSQL or MySQL/MariaDB is done via executing a series of django
-management commands as below.
+management commands as below.  The commands below use PostgreSQL, but are applicable to MySQL/MariaDB
+with the
 
 .. caution::
 
@@ -713,6 +714,11 @@ management commands as below.
     and filenames (1024 characters). If you have data in these fields that surpasses these
     limits, migration to PostgreSQL is not possible and will fail with an error.
 
+.. warning::
+
+    MySQL is case insensitive by default, treating values like "Name" and "NAME" as identical.
+    See :ref:`advanced-mysql-caveats` for details.
+
 
 1.  Stop paperless, if it is running.
 2.  Tell paperless to use PostgreSQL: