Посібник з усунення несправностей для пакету ServBay MariaDB/MySQL

Огляд

MariaDB та MySQL — це провідні у галузі системи управління реляційними базами даних з відкритим кодом, що широко застосовуються у різноманітних веб-додатках та бізнес-сценаріях. ServBay інтегрує декілька версій MariaDB/MySQL для macOS, забезпечуючи розробникам зручне та ефективне локальне середовище для роботи з базами даних. Хоча ці системи відомі своєю стабільністю, під час розробки чи експлуатації можуть виникати проблеми із запуском, підключенням або зниженням продуктивності.

Цей посібник допоможе користувачам ServBay діагностувати і усувати типові несправності з пакетами MariaDB/MySQL. Тут зібрані поширені проблеми, етапи діагностики і конкретні рішення, з урахуванням шляхів і команд саме у середовищі ServBay.

Важливі зауваження:

Перш ніж виконувати будь-які дії, що можуть змінити дані чи конфігурацію, обов’язково зробіть резервну копію вашої бази даних! ServBay має вбудований засіб резервного копіювання, рекомендовано використовувати його регулярно.
У прикладах команд і шляхів використовуються конкретні версії (наприклад, 11.3 або 11.5). Замініть їх на відповідні вашим версіям MariaDB/MySQL у ServBay. Переглянути встановлені та активні версії можна у самому застосунку ServBay.
Маркери <username>, <database>, <your_backup.sql> — це заповнювачі, замініть їх на свої фактичні ім'я користувача, назву бази чи файл.
Інструкції наведені для операційної системи macOS.

Загальні початкові кроки діагностики

Перед детальним вивченням проблеми рекомендується виконати базові перевірки:

Перевірка стану пакету ServBay: Відкрийте інтерфейс ServBay та переконайтесь, що потрібна версія MariaDB/MySQL увімкнена і має статус «Запущено». Також можна скористатися терміналом:
bash
```
servbayctl status mariadb <version>
# Наприклад, перевірка стану MariaDB 11.3:
servbayctl status mariadb 11.3
```
1
2
3
Перегляд логів застосунку ServBay: Іноді основний журнал програми вкаже на проблему запуску чи керування пакетом. Перегляньте розділ логів у інтерфейсі або головний файл журналу ServBay.
Перегляд журналу помилок MariaDB/MySQL: Це ключовий крок для визначення причин збою запуску чи помилок роботи. Типовий шлях до журналу:
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
3
Ретельно вивчіть останні рядки журналу — часто вони одразу вказують на суть проблеми.

Поширені проблеми й рішення

1. Помилка підключення: `SQLSTATE[HY000] [2002] No such file or directory`

Ця помилка означає, що клієнт не може під'єднатися до MariaDB/MySQL за допомогою Unix socket. На macOS Unix socket — це локальний шлях до файлу для міжпроцесної взаємодії; використовується замість TCP/IP та має менше навантаження. Якщо клієнт не може знайти відповідний файл socket, з’явиться ця помилка.

Можливі причини й кроки усунення:

Пакет MariaDB/MySQL не запущено:
- Переконайтеся у статусі пакету через ServBay або командою servbayctl status mariadb <version>.
- Якщо пакет неактивний — запустіть його servbayctl start mariadb <version> і перевірте журнал помилок (.err).
Неправильний шлях до socket-файлу:
- Шлях, який використовує клієнт, не співпадає з налаштуванням у server'і (my.cnf).
- Перевірте параметр socket у конфігураційному файлі (/Applications/ServBay/etc/mariadb/<version>/my.cnf).
- Переконайтеся, що клієнт вказує коректний шлях або використовує значення за замовчуванням ServBay. Типовий шлях знаходиться у /Applications/ServBay/tmp/ або /tmp/, наприклад, /Applications/ServBay/tmp/mysql.sock чи /tmp/mysql.sock.
Проблеми з налаштуваннями ServBay:
- Зайдіть у «Налаштування» → «SQL сервер за замовчуванням» і переконайтеся, що вибрана правильна версія MariaDB/MySQL. Деякі клієнти (mysql CLI без -S або -h) підключаються до версії за замовчуванням.
Проблеми з правами доступу:
- Перевірте, чи має користувач, під яким запущено процес MariaDB/MySQL, права запису до каталогу socket-файлу, а клієнт — права читання. ServBay зазвичай сам налаштовує права, проте ручні зміни до /Applications/ServBay/tmp/ чи /tmp/ можуть їх порушити.

Альтернатива (примусово використовувати мережу):

Спробуйте під’єднатись через IP 127.0.0.1 замість localhost — це змусить клієнт працювати по TCP/IP. Якщо так працює — проблема у socket-файлі.
bash
```
mysql -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).
- Перевірте:
  bash
```
lsof -i :3306
# або
netstat -anv | grep LISTEN | grep 3306
```
  1
  2
  3
- Якщо порт зайнятий — зупиніть процес, що його використовує, або змініть порт у my.cnf (/Applications/ServBay/etc/mariadb/<version>/my.cnf) та перезапустіть пакет.
Мережевий екран (firewall) блокує з’єднання:
- В налаштуваннях macOS → Мережа → Брандмауер перевірте, чи дозволено доступ до 3306.
- Тимчасово дозволіть mysqld через firewall (шлях може змінюватися залежно від версії ServBay):
  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
Параметр bind-address (конфігурація):
- Перевірте значення у my.cnf. Якщо це 127.0.0.1 чи localhost, дозволяється лише локальне підключення. Для підключення з інших машин/VM виставте 0.0.0.0 або певну IP-адресу і перевірте правила firewall.
Проблеми з мережевими налаштуваннями (localhost):
- Переконайтеся, що localhost правильно резолвиться у 127.0.0.1 (IPv4) чи ::1 (IPv6).
- Виконайте ping localhost — перевірте результат.
- Перегляньте /etc/hosts — переконайтесь, що є коректний рядок для localhost.
- Вимкніть сторонні проксі — вони можуть перехоплювати локальний трафік.

3. Пакет MariaDB/MySQL не запускається

Можливі причини й кроки усунення:

Головне — переглянути журнал помилок: Проаналізуйте /Applications/ServBay/logs/mariadb/<version>/<version>.err.
Помилкова конфігурація:
- Файл /Applications/ServBay/etc/mariadb/<version>/my.cnf містить синтаксичні помилки, недійсні параметри або некоректні шляхи.
- Перевірте конфіг файли так:
  bash
```
# Зразок, шлях підберіть під свою версію
/Applications/ServBay/bin/mariadb/<version>/bin/mysqld --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf --validate-config
```
  1
  2
Порт зайнятий: (див. вище, використовуйте lsof -i :<port> або netstat)
Не вистачає місця на диску: Дані (/Applications/ServBay/db/mariadb/<version>/) або логи (/Applications/ServBay/logs/mariadb/<version>/) не можуть записуватися через відсутність вільного місця.
Проблеми з правами:
- Користувач процесу MariaDB/MySQL (часто _mysql, вказаний у ServBay) втратив права на читання/запис до потрібних папок через ручні зміни. Перевірте так:
  bash
```
ls -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
  Переконайтесь, що користувач-власник має права читання/запису/виконання.
Пошкодження файлів даних: (див. розділ нижче — «Крах чи пошкодження бази!») Якщо відбулось аварійне вимкнення чи інша проблема, дані могли бути пошкоджені.

Після усунення причини:

Спробуйте перезапустити пакет: servbayctl restart mariadb <version>

4. Проблеми з правами користувачів або аутентифікацією

Після підключення можуть виникнути помилки через некоректний логін чи права (Access denied).

Можливі причини й рішення:

Помилковий логін чи пароль: Переконайтеся, що дані введено вірно. У ServBay є функція скидання root-пароля.
Обмеження за хостом: Акаунт користувача може бути обмежений підключенням лише з певних хостів — наприклад, 'username'@'localhost'. Підключення з 'username'@'127.0.0.1' може не пройти. Вказівка '%' дозволяє підключення з будь-якого хоста.
Недостатньо прав: Користувач не має прав для підключення чи виконання потрібних запитів (SELECT, INSERT, UPDATE тощо).
Перевірка прав користувача:
- Зайдіть під користувачем з повними правами (наприклад, root):
  bash
```
mysql -u root -p
```
  1
- У SQL-інтерпретаторі перегляньте права:
  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 для зміни прав або створіть нового користувача з необхідними дозволами.

5. Проблеми з продуктивністю

Низька продуктивність бази впливає на швидкодію додатків.

Можливі причини й рішення:

Повільні запити: Неоптимізовані SQL-запити, відсутність індексів, неефективні плани виконання.
- Увімкніть журнал повільних запитів: У my.cnf встановіть slow_query_log = 1 та long_query_time = 1. Вкажіть шлях до журналу slow_query_log_file. Після перезапуску аналізуйте файл на тривалі запити.
- Використовуйте EXPLAIN: Додайте EXPLAIN перед підозрілим запитом — це допоможе побачити, чи застосовуються індекси і наскільки ефективний запит:
  sql
```
EXPLAIN SELECT * FROM your_table_name WHERE column_name = 'value';
```
  1
- Оптимізуйте SQL: Виходячи з аналізу, перепишіть запити так, щоб WHERE та JOIN використовували індекси.
Відсутність або неправильні індекси: Часто використовувані у WHERE, ORDER BY або GROUP BY поля мають бути проіндексовані.
- Проаналізуйте запити й структуру таблиць.
- Додавайте індекси так:
  sql
```
CREATE INDEX idx_column_name ON your_table_name(column_name);
```
  1
  Зверніть увагу, що надмірне індексування збільшує витрати і використання диску.
Неправильні налаштування кешування: У my.cnf параметри, такі як innodb_buffer_pool_size чи key_buffer_size, виставлені некоректно.
- Коригуйте у my.cnf: Орієнтуйтесь на обсяг вільної RAM і характер використання. Для innodb_buffer_pool_size добре дати 50–70% від доступної пам’яті для серверних цілей. Після змін необхідний перезапуск пакету.
  ini
```
[mysqld]
# Зразок, підберіть оптимальне значення для себе
innodb_buffer_pool_size = 2G
# Якщо активно використовуєте MyISAM:
# key_buffer_size = 256M
```
  1
  2
  3
  4
  5
Обмеження апаратних ресурсів: Високе навантаження на CPU, нестача пам’яті, диск на межі. Використовуйте Activity Monitor чи top/htop для моніторингу ресурсів.

6. Крах або пошкодження даних бази

Сервер не запускається, часто падає або дані пошкоджені — можливе пошкодження файлів даних.

Можливі причини та рішення:

Передусім — аналізуйте журнал помилок: Шукайте у /Applications/ServBay/logs/mariadb/<version>/<version>.err згадки про помилки InnoDB, файлової системи чи апаратні збої.
Апаратна несправність: Збої диска чи пам’яті можуть призвести до втрати або пошкодження даних. Перевіряйте системні логи (Console.app) або використовуйте діагностику hardware.
Проблеми програмної сумісності: Баги певних версій MariaDB/MySQL або конфлікти з іншим ПЗ.
Помилки у конфігурації: Некоректний my.cnf може дестабілізувати сервер.
Аварійне вимкнення/kill: Якщо MariaDB/MySQL не вимкнено коректно (kill, крах, закриття програми) — файли можуть бути неконсистентні.

Як діяти:

Спробуйте безпечний перезапуск: Через ServBay чи командно servbayctl restart mariadb <version>. Іноді цього досить для автоматичного відновлення.

Перевірте і спробуйте виправити таблиці в mysqlcheck: Особливо для MyISAM.

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

Примітка: --auto-repair діє лише для MyISAM. Для InnoDB можливий пошук проблем, але виправлення зазвичай складніше (див. нижче про force recovery).

Примусове відновлення InnoDB (innodb_force_recovery): Якщо ядро InnoDB не стартує, спробуйте включити змінну innodb_force_recovery (від 1 до 6, що вища — то більший ризик втрати даних!).
1. Перш ніж щось робити — збережіть копію папки даних: Скопіюйте /Applications/ServBay/db/mariadb/<version>/ в інше місце.
2. Внесіть у [mysqld] у my.cnf рядок innodb_force_recovery = N (N — спершу 1, якщо не допомагає — поступово до 6).
3. Запустіть MariaDB/MySQL: servbayctl start mariadb <version>.
4. Якщо стартує (навіть у обмеженому/читання-only режимі) — терміново збережіть дані через 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
  Переконайтесь, що бекап створився та має реальний розмір!
5. Зупиніть сервер: servbayctl stop mariadb <version>.
6. Видаліть або закоментуйте рядок innodb_force_recovery=N у my.cnf.
7. Далі — повне відновлення: Ініціалізуйте новий data directory, імпортуйте дані з резервної копії.
Відновлення з бекапу: Якщо база не підлягає ремонту чи дані не збігаються — відновіть з останнього надійного бекапу. Бекапи ServBay зазвичай у: /Applications/ServBay/backup/mariadb/<version>/.
- Наприклад, для відновлення у <target_database_name>:
  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. Проблеми резервного копіювання і відновлення

Під час використання вбудованих чи ручних бекапів через mysqldump у ServBay можуть виникати труднощі.

Можливі причини і рішення:

Неповний або зламаний бекап:
- Перевірте розмір файлу (ls -lh /path/to/your_backup.sql), чи відповідає він обсягу ваших даних.
- Перегляньте вміст через текстовий редактор чи less (less /path/to/your_backup.sql), файл має бути придатним для читання, структурований як SQL.
- Якщо ви користувалися mysqldump, перевірте повідомлення у консолі. Якщо ж резервували через ServBay, — подивіться логи застосунку.
Помилки при відновленні:
- Перевірте правильність користувача, пароля, імені бази.
- Перевірте, чи в користувача достатньо прав.
- Проблеми SQL-сумісності — наприклад, при міграції між різними версіями MariaDB і MySQL.
Проблеми із зовнішніми ключами: Порядок імпорту таблиць може спровокувати конфлікт по зовнішніх ключах, якщо залежні таблиці ще не створені або не містять даних. Можна тимчасово вимкнути перевірку ключів:
sql
```
-- До імпорту
SET foreign_key_checks = 0;
-- Імпорт файлу:
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: SQL-бекап може використовувати іншу кодування чи sorting rule — це спричинить помилки при імпорті чи "крякозябри" у даних. Переконайтесь, що кодування backup-рівно відповідає кодуванню цільової бази (наприклад, utf8mb4).

Правильне відновлення бази (приклад):

bash

# Якщо ваш бекап для певної БД,
# Переконайтесь, що база (<target_database_name>) є:
# 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>

# Якщо це глобальний бекап усіх баз (--all-databases) — не вказуйте БД:
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

Примітка: Не забудьте змінити <version> на фактичну версію. Фірмовий бекап ServBay зазвичай легко відновлюється та має зрозумілі назви файлів.

8. Відомий баг: збій InnoDB в MariaDB 11.5.1 (`ib_logfile0 was not found` / `Missing FILE_CHECKPOINT`)

Це критичний баг у MariaDB 11.5.1: InnoDB не може ініціалізуватися чи відновитися через проблеми з лог-файлом.

Ознаки у журналі:

У /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

або:

[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

Це вказує, що відсутній/пошкоджений ib_logfile0 або InnoDB не може перемотати WAL.

Рішення (містить ризиковану міграцію — обов’язково спочатку зробіть копію!):

Це відомий і майже непоправний баг. Оптимально — експортувати дані, ініціалізувати інший сервер, імпортувати на стабільну версію.

Спробуйте примусове відновлення та бекап:
- Редагуйте файл конфігурації /Applications/ServBay/etc/mariadb/11.5/my.cnf.
- Внесіть у секцію [mysqld]: innodb_force_recovery = 6
- Запустіть MariaDB 11.5 через інтерфейс або команду: servbayctl start mariadb 11.5
- Якщо стартує, відразу зробіть повний dump:
  bash
```
mysqldump --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
```
  1
  Переконайтесь, що файл бекапу створено і він не пустий!
Зупиніть і обробіть пошкоджену директорію:
- Зупиніть пакет: servbayctl stop mariadb 11.5
- Далі відредагуйте my.cnf та видаліть або закоментуйте innodb_force_recovery.

Посібник з усунення несправностей для пакету ServBay MariaDB/MySQL ​

Огляд ​

Загальні початкові кроки діагностики ​

Поширені проблеми й рішення ​

1. Помилка підключення: SQLSTATE[HY000] [2002] No such file or directory ​

2. Помилка підключення: пов’язана з мережею (Connection refused, Can't connect to MySQL server) ​

3. Пакет MariaDB/MySQL не запускається ​

4. Проблеми з правами користувачів або аутентифікацією ​

5. Проблеми з продуктивністю ​

6. Крах або пошкодження даних бази ​

7. Проблеми резервного копіювання і відновлення ​

8. Відомий баг: збій InnoDB в MariaDB 11.5.1 (ib_logfile0 was not found / Missing FILE_CHECKPOINT) ​

Посібник з усунення несправностей для пакету ServBay MariaDB/MySQL

Огляд

Загальні початкові кроки діагностики

Поширені проблеми й рішення

1. Помилка підключення: `SQLSTATE[HY000] [2002] No such file or directory`

2. Помилка підключення: пов’язана з мережею (`Connection refused`, `Can't connect to MySQL server`)

3. Пакет MariaDB/MySQL не запускається

4. Проблеми з правами користувачів або аутентифікацією

5. Проблеми з продуктивністю

6. Крах або пошкодження даних бази

7. Проблеми резервного копіювання і відновлення

8. Відомий баг: збій InnoDB в MariaDB 11.5.1 (`ib_logfile0 was not found` / `Missing FILE_CHECKPOINT`)