====== Полный переход на utf8 (utf8mb4) ======

С версии 3.13.07 доступен переход с режима работы в koi8r/koi8u на utf8/utf8mb4

===== Подготовка к переходу =====

<alert type="danger">Обязательно сначала проверить на запасном/резервном/тестовом сервере</alert>

<alert type="danger">**Перед выполнением любых действий из этой статьи необходимо сделать полный бекап базы и файлов биллинга**</alert>

  - Уметь откатывать версию биллинга
  - Уметь восстанавливать базу из бекапа
  - Сделать бекап базы
  - Узнать какая версия mysql установлена и поддерживает ли она кодировку utf8mb4
  - Должна быть установлена версия биллинга не ниже **3.13.07** (админка, ЛК, ЛК API и другие компоненты)

==== Возможные проблемы ====

Если во время перевода базы возникает ошибка **Index column size too large. The maximum column size is X bytes** то нужно выполнить команду в MySQL:
<code>
SET GLOBAL innodb_default_row_format = 'DYNAMIC';
</code>

===== Перевод базы =====

<tabs>
  * [[#tab-file|Через восстановление бекапа (Для больших баз)]]
  * [[#tab-command|Через консольную команду (Для маленьких баз)]]
 
<pane id="tab-file">
=== Перевод базы методом замены кодировки в файле бекапа ===

  - Консоль в которой это будете делать должна поддерживать utf8, если не поддерживает (не отображаются кириллица) то найдите в google как это сделать
  - Сделайте бекап бекапа, на случай если что то пойдет не так, то вы не испортите оригинал бекапа.
  - Отключите nginx что бы не было ошибок для абонентов, сотрудников и платежных систем.

\\ Далее нужно выполнить команду на смену кодировок в файле бекапа
\\ Все предварительные переводы с разных кодировок в koi8r нужны что бы привести все к общему виду.
\\ Данная команда сделает следующее:
  - Переведет utf8mb4 кодировки в koi8r
  - Переведет utf8mb3 кодировки в koi8r
  - Переведет utf8 кодировки в koi8r
  - Переведет koi8u кодировки в koi8r
  - Переведет koi8r кодировки в utf8mb4

<alert type="info">В примерах команд используется название бекапа **database_backup.sql** и он располагается **в той же директории где запускаются команды**)</alert>

<alert type="warning">Если mysql не поддерживает **utf8mb4**, то в конце при переводе с koi8r на utf8mb4 (**s/koi8r/utf8mb4/g**) нужно указать просто **utf8** без mb4</alert>
<code>
sed -i -e 's/_0900_ai_/_general_/g' -e 's/_unicode_/_general_/g' -e 's/utf8mb4/koi8r/g' -e 's/utf8mb3/koi8r/g' -e 's/utf8/koi8r/g' -e 's/koi8u/koi8r/g' -e 's/koi8r/utf8mb4/g' database_backup.sql
</code>

\\ Далее если вы использовали буквы украинского алфавита: і І ї Ї є Є ґ Ґ
\\ То нужно запустить еще команду для замены символов на буквы
<code>
sed -i -e 's/╕/і/g' -e 's/╤/І/g' -e 's/╖/ї/g' -e 's/╥/Ї/g' -e 's/╓/є/g' -e 's/╢/Є/g' -e 's/╜/ґ/g' -e 's/╫/Ґ/g' database_backup.sql
</code>

\\ Перед восстановлением измените кодировку подключения к базе на utf8mb4 или utf8, иначе можете нарваться на ошибку **Illegal mix of collations for operation 'UNION'**
<code>
SET NAMES utf8mb4;
SET CHARSET utf8mb4;
SET sql_mode = '';
</code>

\\ Далее восстановите базу из этого бекапа (можно в другую базу и просто переключиться на неё в конфиге)
\\ Новую базу нужно создавать уже в новой кодировке (utf8mb4_general_ci или utf8_general_ci)
<code>
CREATE DATABASE mikbill CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
</code>

\\ Так же не забывайте про процедуры базы.

</pane>

<pane id="tab-command">
=== Перевод базы запуском консольной команды ===
\\ Нужно остановить web сервер (nginx) что бы во время перехода абоненты и сотрудники не сталкивались с ошибками.
\\ Далее нужно перейти в директорию админки и запустить консольную команду биллинга на смену кодировки
<alert type="info">Рекомендуем запускать консольную команду в **screen** так как этот процесс может занять **много времени** (зависит от размера базы)</alert>

<alert type="warning">Если mysql не поддерживает **utf8mb4**, то запускать нужно указав просто **utf8**</alert>

<code>
cd /var/www/mikbill/admin
php index.php sql_convert utf8mb4
</code>

В процессе работы модуль будет записывать свою работу в дебаг лог.
</pane>

</tabs>


===== После перевода =====

В файлы конфига в раздел **<nowiki><mysql></nowiki>** нужно добавить параметр **<nowiki><charset>utf8mb4</charset></nowiki>**, пример:

<alert type="warning">Если mysql не поддерживает **utf8mb4**, то нужно указать просто **utf8**</alert>

<file xml>
<config>
    <parameters>
        <mysql>
            <host>db.localhost</host>
            <username>root</username>
            <password></password>
            <dbname>mikbill</dbname>
            <charset>utf8mb4</charset>
        </mysql>
        <timezone>Europe/Kiev</timezone>
        <partialUTF8>false</partialUTF8>
        ...
    </parameters>
</config>
</file>

Данный параметр нужно добавлять в конфиг админки, ЛК и ЛК API (если установлено)

После добавления параметра, включите nginx и у вас все должно работать на новой кодировке.