Посібник з усунення несправностей пакету ServBay MariaDB/MySQL
Огляд
MariaDB та MySQL — провідні у галузі відкриті системи управління реляційними базами даних, широко використовуються у різноманітних веб-застосунках та бізнес-сценаріях. ServBay інтегрує кілька версій пакетів MariaDB/MySQL у середовищах macOS та Windows, забезпечуючи розробникам зручне та ефективне локальне середовище для роботи з базами даних. Незважаючи на стабільність цих систем, під час розробки та експлуатації можуть виникати проблеми з запуском пакету, помилки підключення або падіння продуктивності.
Цей посібник допоможе користувачам ServBay діагностувати та вирішувати типові проблеми з MariaDB/MySQL. Ми розглянемо найчастіші питання, кроки діагностики та конкретні рішення, також наведемо особливості шляхів і команд в середовищі ServBay.
Важливі зауваження:
- Перед виконанням будь-яких дій, що можуть вплинути на дані чи конфігурацію, обов’язково створюйте резервну копію вашої бази даних! ServBay має вбудовану функцію резервного копіювання — рекомендуємо користуватися нею регулярно.
- Приклади команд і шляхів містять конкретні версії (наприклад,
11.3
чи11.5
) — підставляйте номер версії MariaDB/MySQL, який у вас встановлений. За допомогою інтерфейсу ServBay можна переглянути встановлені та активовані версії пакета. - У прикладах команд значення
<username>
,<database>
,<your_backup.sql>
— це змінні, їх потрібно замінити на ваші реальні дані. - Посібник актуальний для macOS та Windows — у відповідних розділах наведені специфічні шляхи й приклади команд.
Загальні початкові кроки діагностики
Перед тим, як розпочати глибоке розслідування, рекомендується виконати такі базові перевірки:
Перевірка статусу пакета ServBay: Відкрийте інтерфейс програми ServBay й впевніться, що потрібна версія MariaDB/MySQL активована й має статус "Активовано". Також можна використати команду:
bashservbayctl status mariadb <version> # Наприклад, перевірка статусу MariaDB 11.3: servbayctl status mariadb 11.3
1
2
3Перевірка журналу ServBay: Помилки запуску або керування пакетом можуть бути записані у лог програми ServBay. Перевіряйте журнали через інтерфейс або безпосередньо у файлі звітів.
Перевірка журналу помилок MariaDB/MySQL: Це головне місце для пошуку причин збоїв у завантаженні та роботі пакета.
macOS:
bash/Applications/ServBay/logs/mariadb/<version>/<version>.err # Приклад: перегляд останніх 50 рядків журналу помилок MariaDB 11.3: tail -n 50 /Applications/ServBay/logs/mariadb/11.3/11.3.err
1
2
3Windows:
cmdC:\ServBay\logs\mariadb\<version>\<version>.err # Приклад: перегляд останніх 50 рядків журналу помилок MariaDB 11.3: powershell "Get-Content -Path 'C:\ServBay\logs\mariadb\11.3\11.3.err' -Tail 50"
1
2
3Особливу увагу звертайте на записи про останні помилки у кінці журналу.
Найпоширеніші проблеми та їх вирішення
1. Помилка підключення: SQLSTATE[HY000] [2002] No such file or directory
Ця помилка свідчить, що клієнт не може під'єднатися до MariaDB/MySQL через Unix socket. На macOS Unix socket використовується для локального з'єднання, це швидше, ніж TCP/IP. Якщо шлях до сокет-файлу неправильний або сокет не створений — з'явиться ця помилка.
Можливі причини та рішення:
- Пакет MariaDB/MySQL не працює:
- Перевірте статус в інтерфейсі ServBay або командою
servbayctl status mariadb <version>
. - Якщо пакет не активний, запустіть:
servbayctl start mariadb <version>
та перегляньте журнал помилок (.err
).
- Перевірте статус в інтерфейсі ServBay або командою
- Некоректний шлях до сокету (macOS/Linux):
- Шлях, який вказує клієнт, повинен відповідати значенню параметру
socket
у конфігурації (my.cnf
):- macOS: Перевірте файл
/Applications/ServBay/etc/mariadb/<version>/my.cnf
. - Windows: Unix socket не використовується, застосовується TCP/IP або іменовані канали.
- macOS: Переконайтесь, що програма-клієнт використовує саме той шлях, який зазначений у конфігурації ServBay, зазвичай
/Applications/ServBay/tmp/mysql.sock
або/tmp/mysql.sock
.
- macOS: Перевірте файл
- Шлях, який вказує клієнт, повинен відповідати значенню параметру
- Проблеми з налаштуваннями ServBay:
- В "Налаштування" -> "SQL-сервер за замовчуванням" впевніться, що вибрана необхідна версія пакету. Деякі клієнти (наприклад,
mysql
без параметрів-S
чи-h
) спробують підключитися до сервера за замовчуванням.
- В "Налаштування" -> "SQL-сервер за замовчуванням" впевніться, що вибрана необхідна версія пакету. Деякі клієнти (наприклад,
- Проблеми з правами:
- macOS: Користувач, що запускає MariaDB/MySQL, має мати права запису у каталозі сокета, а клієнтські програми — права читання. Якщо ви змінювали права у
/Applications/ServBay/tmp/
чи/tmp/
, це може спричинити проблеми. - Windows: Перевірте, чи користувач, під яким працює ServBay, може відкривати потрібні порти/канали.
- macOS: Користувач, що запускає MariaDB/MySQL, має мати права запису у каталозі сокета, а клієнтські програми — права читання. Якщо ви змінювали права у
Альтернатива (примусово використовувати TCP/IP):
- З'єднуйтесь з сервером через IP-адресу
127.0.0.1
замістьlocalhost
: клієнт використовуватиме TCP/IP. Якщо таке з'єднання працює — проблема саме з сокетом:bashmysql -u <username> -p -h 127.0.0.1 -P 3306
1
2. Помилки підключення: проблеми з мережею (Connection refused
, Can't connect to MySQL server
)
Такі помилки означають, що клієнт не може підключитися до MariaDB/MySQL через TCP/IP.
Можливі причини та рішення:
Пакет MariaDB/MySQL не працює: (див. вище, перевірте статус пакета і
.err
).Порт зайнятий:
- Переконайтесь, що порт 3306 (або інший, зазначений у конфігурації) не зайнятий сторонніми процесами.
macOS:
bashlsof -i :3306 # або netstat -anv | grep LISTEN | grep 3306
1
2
3Windows:
cmdnetstat -an | findstr :3306 # або PowerShell: Get-NetTCPConnection -LocalPort 3306
1
2
3Якщо порт зайнято — завершіть чужий процес або змініть параметр
port
у файлі конфігурації MariaDB/MySQL.- macOS:
/Applications/ServBay/etc/mariadb/<version>/my.cnf
- Windows:
C:\ServBay\etc\mariadb\<version>\my.cnf
Брандмауер блокує з'єднання:
macOS:
- Перевіряйте "Системні настройки" -> "Мережа" -> "Брандмауер".
- Можна дозволити процесу
mysqld
доступ через брандмауер:bash# Приклад, шлях слід налаштувати під вашу систему sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/ServBay/bin/mariadb/<version>/bin/mysqld sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/ServBay/bin/mariadb/<version>/bin/mysqld
1
2
3
Windows:
- Перевіряйте налаштування Windows Defender чи стороннього брандмауера.
- Додати правило в Windows Firewall:cmd
netsh advfirewall firewall add rule name="ServBay MariaDB" dir=in action=allow program="C:\ServBay\bin\mariadb\<version>\bin\mysqld.exe"
1
Проблеми з параметром
bind-address
:- Якщо у
my.cnf
зазначеноbind-address=127.0.0.1
абоlocalhost
, TCP-з'єднання можливе лише з локальної машини. Для доступу з інших машин встановіть0.0.0.0
чи конкретну адресу.
- Якщо у
Проблеми з налаштуванням мережі (
localhost
):- Переконайтесь, що
localhost
коректно відображає IP 127.0.0.1 (IPv4) та ::1 (IPv6).
macOS:
bashping localhost cat /etc/hosts
1
2Windows:
cmdping localhost type C:\Windows\System32\drivers\etc\hosts
1
2Файл hosts має містити правильний запис для
localhost
. Деякі проксі-програми можуть перенаправляти локальний трафік — вимкніть їх для тесту.- Переконайтесь, що
3. Пакет MariaDB/MySQL не запускається
Можливі причини та рішення:
Перевірка журналів помилок: Найважливіше — перегляньте журнали помилок:
- macOS:
/Applications/ServBay/logs/mariadb/<version>/<version>.err
- Windows:
C:\ServBay\logs\mariadb\<version>\<version>.err
- macOS:
Помилки у файлі конфігурації:
- Перевірте синтаксис, валідність і правильність шляхів.
Шлях до конфігурації:
- macOS:
/Applications/ServBay/etc/mariadb/<version>/my.cnf
- Windows:
C:\ServBay\etc\mariadb\<version>\my.cnf
Перевірити конфігурацію:
bash# macOS /Applications/ServBay/bin/mariadb/<version>/bin/mysqld --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf --validate-config # Windows C:\ServBay\bin\mariadb\<version>\bin\mysqld.exe --defaults-file=C:\ServBay\etc\mariadb\<version>\my.cnf --validate-config
1
2
3
4
5Порт зайнятий: Див. вище (lsof, netstat).
Недостатньо місця на диску: Каталог для бази чи журналу повинен бути на розділі з достатнім обсягом.
- macOS:
- Каталог даних:
/Applications/ServBay/db/mariadb/<version>/
- Каталог журналу:
/Applications/ServBay/logs/mariadb/<version>/
- Каталог даних:
- Windows:
- Каталог даних:
C:\ServBay\db\mariadb\<version>\
- Каталог журналу:
C:\ServBay\logs\mariadb\<version>\
- Каталог даних:
- macOS:
Проблеми з правами доступу: Перевірте права на читання/запис/виконання каталогу даних, журналу та файлів конфігурації.
macOS:
bashls -ld /Applications/ServBay/db/mariadb/<version> ls -l /Applications/ServBay/etc/mariadb/<version>/my.cnf ls -ld /Applications/ServBay/logs/mariadb/<version>
1
2
3Користувач (наприклад,
_mysql
) має мати відповідний доступ.Windows: Перевірте властивості в Провіднику Windows — користувач ServBay повинен мати права на каталоги та файли.
Пошкоджені файли даних: Про це — у розділі "Крах чи пошкодження даних". Якщо ПК вимкнувся некоректно або були інші проблеми — деякі файли можуть пошкодитися.
Після вирішення:
- Спробуйте перезапустити пакет:
servbayctl restart mariadb <version>
4. Проблеми з правами користувача або автентифікацією
Може виникати помилка "Access denied" через неправильний логін, пароль або нестачу прав.
Можливі причини та рішення:
- Невірний логін/пароль: Перевірте правильність даних для підключення. ServBay дозволяє легко скинути пароль root, якщо його забуто.
- Обмеження за хостом: Обліковий запис користувача може дозволяти підключення лише з певного хоста (
'<username>'@'localhost'
). Підключення від'<username>'@'127.0.0.1'
може бути заборонено.'%'
— дозволяє з будь-якого хоста. - Недостатньо прав: Користувач не має дозволів на підключення до потрібної бази чи виконання певних операцій.
- Перевірка прав:
- Зайдіть у MariaDB/MySQL під root:bash
mysql -u root -p
1 - Перегляньте привілеї:sql
SHOW GRANTS FOR '<username>'@'<hostname>'; -- Приклад для 'webapp' з 'localhost': SHOW GRANTS FOR 'webapp'@'localhost'; -- Для 'admin' з будь-якого хоста: SHOW GRANTS FOR 'admin'@'%';
1
2
3
4
5 - За потреби змініть привілеї через
GRANT
чиREVOKE
, або створіть нового користувача.
- Зайдіть у MariaDB/MySQL під root:
5. Зниження продуктивності
Падіння продуктивності бази даних може негативно впливати на додатки.
Можливі причини та рішення:
- Повільні запити: Некоректний SQL, відсутність індексів, поганий план виконання.
- Увімкнути журнал повільних запитів: Укажіть
slow_query_log = 1
,long_query_time = 1
, і шлях до логу уmy.cnf
. Перезапустіть пакет і проаналізуйте лог. - Використовуйте
EXPLAIN
: Додайте перед запитом — аналізуйте план виконання, використання індексів, кількість рядків:sqlEXPLAIN SELECT * FROM your_table_name WHERE column_name = 'value';
1 - Оптимізуйте запити: Змінюйте запити відповідно до рекомендацій EXPLAIN, додавайте індекси до колонок, які використовуються у WHERE та JOIN.
- Увімкнути журнал повільних запитів: Укажіть
- Відсутність чи неправильні індекси: Часто використовувані колонки у вибірках, групуванні чи сортуванні мають бути проіндексовані.
- Аналізуйте структуру та запити: Визначте, де потрібен індекс.
- Створіть індекс:sqlСтворення індексів підвищує швидкість читання, але може вплинути на швидкість запису та споживання диску.
CREATE INDEX idx_column_name ON your_table_name(column_name);
1
- Неправильна кеш-конфігурація: Занадто малі або великі значення параметрів кешу у
my.cnf
, наприклад,innodb_buffer_pool_size
,key_buffer_size
(MyISAM).- Налаштуйте параметри: Врахуйте обсяг RAM та основне призначення сервера.
innodb_buffer_pool_size
для InnoDB рекомендується ~50-70% доступної пам’яті, якщо система використовується головно для СУБД. Після змін — перезапустіть пакет.ini[mysqld] # Приклад — підлаштуйте під вашу систему innodb_buffer_pool_size = 2G # Для MyISAM: # key_buffer_size = 256M
1
2
3
4
5
- Налаштуйте параметри: Врахуйте обсяг RAM та основне призначення сервера.
- Апаратні обмеження: Високе навантаження на CPU, RAM, диск чи мережу. Перевіряйте використання системних ресурсів через Activity Monitor (macOS) або командою
top
/htop
.
6. Крах чи пошкодження даних
База не стартує, часто падає або дані некоректні — можливо, пошкоджені файли.
Можливі причини та рішення:
- Перевірте журнал помилок: Найчастіше там вказано причину — помилки InnoDB, проблеми з файловою системою, апаратні збої.
- macOS:
/Applications/ServBay/logs/mariadb/<version>/<version>.err
- Windows:
C:\ServBay\logs\mariadb\<version>\<version>.err
- macOS:
- Апаратні проблеми: Краші диску, помилки RAM — перевіряйте журнали системи або запускайте діагностику.
- Конфлікти програм/Баги: Деякі версії MariaDB/MySQL містять бага або мають конфлікти з іншими програмами.
- Помилки у конфігурації: Некоректні параметри можуть призводити до нестабільності.
- Некоректне зупинення: Якщо MariaDB/MySQL завершувалися некоректно (форсовано), це могло призвести до пошкодження файлів.
Варіанти вирішення:
- Спробуйте безпечний перезапуск: Через інтерфейс ServBay або команду
servbayctl restart mariadb <version>
- Перевірка та відновлення таблиць через
mysqlcheck
:bashУвага:mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --check --all-databases # Для MyISAM: # mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --auto-repair --check --all-databases
1
2
3--auto-repair
— лише для MyISAM. Для InnoDB потрібні складніші варіанти — див. нижче. - Форсоване відновлення InnoDB (
innodb_force_recovery
): Якщо InnoDB не стартує, можна спробувати форсоване відновлення. Це ризиковано, можливі втрати! Використовуйте лише для зняття резервної копії.- Передусім скопіюйте каталог даних
/Applications/ServBay/db/mariadb/<version>/
у інше місце. - Відкрийте
/Applications/ServBay/etc/mariadb/<version>/my.cnf
, додайте рядокinnodb_force_recovery = N
(N — від 1 до 6, щоразу тільки одне значення!). - Запустіть пакет:
servbayctl start mariadb <version>
- Якщо стартує (навіть у режимі тільки читання), одразу зробіть експорт за допомогою
mysqldump
:bashПереконайтеся, що файл резервної копії створено і він достатнього розміру!mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --all-databases --routines --triggers --events > /path/to/your_emergency_backup.sql
1 - Зупиніть пакет:
servbayctl stop mariadb <version>
- Видаліть/закоментуйте параметр
innodb_force_recovery
уmy.cnf
. - Відновлення даних: Часто це означає ініціалізацію нового каталогу даних, потім імпорт резервної копії у чисту базу.
- Передусім скопіюйте каталог даних
- Відновлення із резервної копії: Якщо база не підлягає відновленню, найнадійніше — імпорт із свіжої копії. ServBay зберігає резервні файли у
/Applications/ServBay/backup/mariadb/<version>/
.- Приклад імпорту:bashНагадування:
# Створіть нову базу # mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;" # Імпортуйте резервний файл mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>
1
2
3
4
5<version>
— замініть на номер вашого пакета.
- Приклад імпорту:
7. Проблеми із резервним копіюванням та відновленням
Використовуючи вбудовану функцію ServBay або вручну через mysqldump
, можна зіткнутися з такими помилками.
Можливі причини та рішення:
- Пошкоджені чи неповні файли резервної копії:
- Перевірте розмір файлу (
ls -lh /path/to/your_backup.sql
). - Перегляньте у редакторі або через
less
— чи файл містить SQL. - Для ручного копіювання через
mysqldump
— перевірте повідомлення про помилки. Для ServBay — дивіться логи бекапу.
- Перевірте розмір файлу (
- Помилки при імпорті:
- Невірне ім'я користувача/бази/пароль.
- Недостатні привілеї.
- Синтаксичні помилки SQL: перенесення між різними версіями або між MySQL/MariaDB може спричинити конфлікти.
- Помилки з зовнішніми ключами: Порядок імпорту таблиць може спричинити порушення обмежень. Тимчасове вимкнення перевірки допоможе:sqlУвага: Тимчасово вимкнений контроль може спричинити невідповідність даних — робіть це тільки на час імпорту!
-- До імпорту SET foreign_key_checks = 0; -- Далі — імпорт SQL source /path/to/your_backup.sql; -- у клієнті mysql -- або: mysql ... < /path/to/your_backup.sql -- Після імпорту SET foreign_key_checks = 1;
1
2
3
4
5
6
7
8 - Проблеми із кодуванням чи Collation: Відмінність кодувань у бекапі та у цільовій базі може призвести до помилок імпорту або псування даних. Переконайтеся, що використовуєте той самий charset (зазвичай
utf8mb4
).
Правильний процес відновлення (приклади):
macOS:
bash
# Якщо backup — тільки однієї бази
# Створіть базу
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"
# Імпортуйте дані
mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>
# Якщо backup містить всі бази (--all-databases), не потрібно вказувати назву бази
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
Windows:
cmd
REM Якщо backup — тільки однієї бази
REM Створіть базу
REM C:\ServBay\bin\mariadb\<version>\bin\mysql.exe --defaults-file=C:\ServBay\etc\mariadb\<version>\my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"
REM Імпорт даних
C:\ServBay\bin\mariadb\<version>\bin\mysql.exe --defaults-file=C:\ServBay\etc\mariadb\<version>\my.cnf -u <username> -p <target_database_name> < C:\ServBay\backup\mariadb\<version>\<your_backup.sql>
REM Якщо backup — для всіх баз (--all-databases), не потрібно вказувати назву бази
REM C:\ServBay\bin\mariadb\<version>\bin\mysql.exe --defaults-file=C:\ServBay\etc\mariadb\<version>\my.cnf -u <username> -p < C:\ServBay\backup\mariadb\<version>\<your_backup.sql>
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
Нагадування: <version>
— підставте ваш номер версії пакета. ServBay створює резервні файли для простого імпорту.
8. Специфічний баг: MariaDB 11.5.1 InnoDB не запускається (ib_logfile0 was not found
/ Missing FILE_CHECKPOINT
)
Ця проблема — відомий серйозний баг у версії MariaDB 11.5.1, через який InnoDB не може ініціалізуватися або відновити логи, і запуск бази стає неможливим.
Типові повідомлення у журналі помилок:
macOS (/Applications/ServBay/logs/mariadb/11.5/11.5.err
):
[ERROR] InnoDB: File /Applications/ServBay/db/mariadb/11.5/ib_logfile0 was not found
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB
1
2
3
4
2
3
4
Windows (C:\ServBay\logs\mariadb\11.5\11.5.err
):
[ERROR] InnoDB: File C:\ServBay\db\mariadb\11.5\ib_logfile0 was not found
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB
1
2
3
4
2
3
4
Або:
[ERROR] InnoDB: Missing FILE_CHECKPOINT(xxxxx) at xxxxx
[ERROR] InnoDB: Log scan aborted at LSN xxxxx
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB
1
2
3
4
5
2
3
4
5
Ці повідомлення означають, що InnoDB не може знайти чи унормувати свої файли журналів, і старт неможливий.
Варіанти вирішення (містить міграцію даних — ОБОВ'ЯЗКОВО попередньо створіть резервну копію):
Це відома проблема, яку важко полагодити стандартно. Найкраще — спробувати примусовий запуск і експорт даних, потім мигрувати їх у стабільну версію MariaDB.
Спробуйте форсоване відновлення для копіювання даних (ризик!):
Редагування конфігурації:
- macOS:
/Applications/ServBay/etc/mariadb/11.5/my.cnf
- Windows:
C:\ServBay\etc\mariadb\11.5\my.cnf
Додайте у секцію
[mysqld]
:innodb_force_recovery = 6
Спробуйте запустити:
bashservbayctl start mariadb 11.5
1Якщо стартує — одразу зробіть резервну копію:
macOS:
bashmysqldump --defaults-file=/Applications/ServBay/etc/mariadb/11.5/my.cnf -u root -p --all-databases --routines --triggers --events > /Applications/ServBay/backup/mariadb/11.5/mariadb_11.5_emergency_backup.sql
1Windows:
cmdC:\ServBay\bin\mariadb\11.5\bin\mysqldump.exe --defaults-file=C:\ServBay\etc\mariadb\11.5\my.cnf -u root -p --all-databases --routines --triggers --events > C:\ServBay\backup\mariadb\11.5\mariadb_11.5_emergency_backup.sql
1Обов'язково перевірте, чи створено резервний файл і він має адекватний розмір!
- macOS:
Зупиніть і обробіть каталог даних проблемної версії:
- Зупиніть MariaDB 11.5:
servbayctl stop mariadb 11.5
- Вилучіть чи закоментуйте в my.cnf параметр
innodb_force_recovery
.
- Зупиніть MariaDB 11.5: