Skip to content

Commit e14ce71

Browse files
joshtrichardsmiaulalala
authored andcommitted
docs(admin): clarify purpose of utf8mb4 support
Signed-off-by: Josh <josh.t.richards@gmail.com>
1 parent 0b683d9 commit e14ce71

1 file changed

Lines changed: 32 additions & 14 deletions

File tree

Lines changed: 32 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,29 @@
1-
=====================================
2-
Enabling MySQL/MariaDB 4-byte support
3-
=====================================
1+
===========================================
2+
Enabling MySQL/MariaDB full Unicode support
3+
===========================================
44

55
.. note::
66

7-
Be sure to backup your database before performing this database upgrade.
7+
Be sure to back up your database before performing this database upgrade.
88

9-
In order to use Emojis (textbased smilies) on your Nextcloud server with a MySQL database, the
10-
installation needs to be tweaked a bit.
9+
To store the full range of Unicode characters in Nextcloud, including emoji,
10+
less-common writing systems, historic scripts, and specialized symbols, a
11+
MySQL or MariaDB database must use the ``utf8mb4`` character set. The older
12+
three-byte ``utf8`` character set cannot store characters outside `Unicode's
13+
Basic Multilingual Plane <https://en.wikipedia.org/wiki/Plane_(Unicode)>`_.
1114

1215
.. warning::
1316

1417
This guide applies only to MySQL 8 or newer and MariaDB 10.6 or newer.
1518
For a list of supported MySQL and MariaDB versions, see our
1619
:doc:`system requirements documentation <../installation/system_requirements>`.
1720

18-
1. Make sure the following InnoDB settings are set on your MySQL server::
21+
1. Make sure the following InnoDB setting is enabled on your database server::
1922

2023
[mysqld]
2124
innodb_file_per_table=1
2225

23-
2. Restart the MySQL server in case you changed the configuration in step 1.
26+
2. Restart the database server if you changed the configuration in step 1.
2427

2528
You can then verify that the change worked:
2629

@@ -38,35 +41,50 @@ The result should look like this::
3841
+-----------------------+-------+
3942
1 row in set (0.00 sec)
4043

41-
3. Open a shell, change dir (adjust ``/var/www/nextcloud`` to your nextcloud location if needed), and put your nextcloud instance in maintenance mode, if it isn't already::
44+
3. Open a shell, change to the Nextcloud installation directory (adjust
45+
``/var/www/nextcloud`` as needed), and enable maintenance mode if it is not
46+
already enabled::
4247

4348
$ cd /var/www/nextcloud
4449
$ sudo -E -u www-data php occ maintenance:mode --on
4550

46-
4. Change your databases character set and collation:
51+
4. Change the database character set to ``utf8mb4`` and set its default
52+
collation:
4753

4854
.. code-block:: sql
4955
5056
ALTER DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
5157
52-
5. Set the ``mysql.utf8mb4`` config to true in your config.php::
58+
.. note::
59+
60+
The character set determines which characters can be stored. The collation
61+
determines how text is compared and sorted.
62+
63+
5. Enable ``utf8mb4`` support in the Nextcloud system configuration::
5364

5465
$ sudo -E -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
5566

56-
6. Convert all existing tables to the new collation by running the repair step::
67+
6. Run the repair command to convert the existing tables to the ``utf8mb4``
68+
character set and collation::
5769

5870
$ sudo -E -u www-data php occ maintenance:repair
5971

6072
.. note::
6173

62-
This will also change the `ROW_FORMAT` to `DYNAMIC` for your tables.
74+
This also changes the ``ROW_FORMAT`` of all tables to ``DYNAMIC``.
6375

6476
7. Disable maintenance mode::
6577

6678
$ sudo -E -u www-data php occ maintenance:mode --off
6779

6880
Now you should be able to use Emojis in your file names, calendar events, comments and many more.
81+
Nextcloud can now use the full range of Unicode characters - such as emojis - in file names,
82+
calendar events, and comments.
6983

7084
.. note::
7185

72-
Also make sure your backup strategy still work. If you use ``mysqldump`` make sure to add the ``--default-character-set=utf8mb4`` option. Otherwise your backups are broken and restoring them will result in ``?`` instead of the emojis, making files inaccessible.
86+
Make sure your backup strategy supports ``utf8mb4``. If you use
87+
``mysqldump``, add the ``--default-character-set=utf8mb4`` option.
88+
Otherwise, four-byte Unicode characters may not be preserved correctly
89+
when the backup is restored. (A common symptom of this problem is the
90+
appearance of ``?`` instead of emojis in text and file names).

0 commit comments

Comments
 (0)