ServBay MariaDB/MySQL Probleemoplossingsgids

Overzicht

MariaDB en MySQL zijn toonaangevende open source relationele databasebeheersystemen en worden veel gebruikt in diverse webapplicaties en zakelijke scenario's. ServBay integreert meerdere versies van MariaDB/MySQL in de macOS-omgeving en biedt ontwikkelaars een efficiënte lokale databaseomgeving. Ondanks hun stabiliteit kunt u tijdens het ontwikkelen of runnen toch problemen tegenkomen, zoals het niet kunnen opstarten van het pakket, verbindingsproblemen of prestatieverlies.

Deze gids is bedoeld om ServBay-gebruikers te helpen bij het diagnosticeren en oplossen van veelvoorkomende MariaDB/MySQL-pakketproblemen. We behandelen algemene problemen, diagnoseprocedures en specifieke oplossingen, inclusief ServBay-specifieke paden en commando's.

Belangrijke tips:

• Maak altijd eerst een back-up van uw database voordat u handelingen uitvoert die data of configuratie kunnen wijzigen! ServBay biedt ingebouwde back-upfunctionaliteit — gebruik deze regelmatig.
• In de voorbeelden van commando's en paden wordt een specifiek versienummer gebruikt (zoals 11.3 of 11.5). Vervang deze altijd door de versie die u daadwerkelijk gebruikt in ServBay. U kunt de geïnstalleerde en ingeschakelde pakketversies bekijken in de ServBay-interface.
• In de voorbeeldcommando's zijn <username>, <database>, <your_backup.sql> placeholders; vervang deze door uw eigen gebruikersnaam, databasenaam of back-up-bestandsnaam.
• Deze gids gaat uit van het gebruik van macOS.

Algemene basisstappen voor diagnose

Voordat u dieper op een specifiek probleem ingaat, is het aan te raden eerst deze basiscontroles uit te voeren:

1. Controleer de status van het ServBay-pakket: Open de ServBay-interface en controleer of de door u gewenste MariaDB/MySQL-versie is ingeschakeld en "Draait". Dit kan ook via de commandline worden gecontroleerd:

   servbayctl status mariadb <version>
   # Bijvoorbeeld, de status van MariaDB 11.3 controleren:
   servbayctl status mariadb 11.3

2. Bekijk de ServBay-applicatielogs: Soms registreert ServBay zelf fouten bij het opstarten of beheren van pakketten. Controleer de logsectie in de ServBay-interface of bekijk het hoofdlogbestand van ServBay.
3. Bekijk het MariaDB/MySQL-foutenlogboek: Dit is de belangrijkste stap om problemen met het opstarten of runtime-fouten van de database te achterhalen. Het logbestand staat doorgaans op:

   /Applications/ServBay/logs/mariadb/<version>/<version>.err
   # Bijvoorbeeld, de laatste 50 regels van het foutenlog van MariaDB 11.3 bekijken:
   tail -n 50 /Applications/ServBay/logs/mariadb/11.3/11.3.err

   Let vooral op de laatste foutmeldingen — deze duiden meestal direct op de oorzaak.

Veelvoorkomende problemen en oplossingen

1. Verbindingsfout: SQLSTATE[HY000] [2002] No such file or directory

Deze fout betekent meestal dat de client geen verbinding kan maken met de MariaDB/MySQL-server via het Unix socket-bestand. Op macOS is een Unix socket een lokale communicatiemethode tussen processen en wordt lokaal meestal verkozen boven TCP/IP vanwege een lagere overhead. Deze fout verschijnt als het socket-bestand niet gevonden wordt op het verwachte pad.

Mogelijke oorzaken en oplossingen:

• MariaDB/MySQL-pakket draait niet:
  • Controleer in de ServBay-interface of met servbayctl status mariadb <version> of het pakket actief is.
  • Start het anders met: servbayctl start mariadb <version>, en bekijk het logboek (.err-bestand) als het opstarten faalt.
• Socket-pad klopt niet:
  • Mogelijk wijkt het pad dat de client gebruikt af van de configuratie in de server (my.cnf).
  • Controleer het socket-pad in /Applications/ServBay/etc/mariadb/<version>/my.cnf.
  • Zorg dat uw applicatie/client het juiste socket-pad gebruikt, meestal ligt het standaardpad bij ServBay onder /Applications/ServBay/tmp/ of /tmp/, afhankelijk van de versie. Bijvoorbeeld: /Applications/ServBay/tmp/mysql.sock of /tmp/mysql.sock.
• Problemen met standaardinstellingen in ServBay:
  • Controleer in “Instellingen” -> “Standaard SQL-server” of de juiste MariaDB/MySQL-versie als standaardpakket is gekozen. Sommige tools (zoals de mysql-client zonder expliciete -S of -h) proberen verbinding te maken via het standaard socket-bestand.
• Rechtenprobleem:
  • Als de gebruiker waaronder MariaDB/MySQL draait geen schrijfrechten heeft op de directory van het socket-bestand, of de client geen leesrechten, kunnen er problemen ontstaan. ServBay regelt dit normaal gesproken, maar handmatige rechtenwijzigingen in /Applications/ServBay/tmp/ of /tmp/ kunnen problemen veroorzaken.

Alternatief (forceer netwerkverbinding):

• Probeer verbinding te maken via IP-adres 127.0.0.1 in plaats van localhost. Hierdoor gebruikt de client altijd TCP/IP in plaats van Unix socket. Lukt dit wel? Dan ligt het probleem bijna zeker bij het socket-bestand.

  mysql -u <username> -p -h 127.0.0.1 -P 3306

2. Verbindingsfout: netwerkproblemen (Connection refused, Can't connect to MySQL server)

Dit soort fouten duiden erop dat de client geen verbinding kan maken via het TCP/IP-netwerk met de server.

Mogelijke oorzaken en oplossingen:

• MariaDB/MySQL-pakket draait niet: Zie hierboven, controleer status/logs.
• Poort in gebruik:
  • Mogelijk wordt poort 3306 al door een ander proces gebruikt.
  • Controleer met:

    lsof -i :3306
    # Of
    netstat -anv | grep LISTEN | grep 3306

  • Als de poort bezet is, stop het betreffende proces of wijzig het port-nummer in /Applications/ServBay/etc/mariadb/<version>/my.cnf en herstart.
• Firewall blokkeert poort:
  • De ingebouwde of een derde partij firewall op macOS kan toegang tot 3306 blokkeren.
  • Controleer dit via Systeeminstellingen > Netwerk > Firewall.
  • Sta het mysqld-proces tijdelijk toe toegang te krijgen — het pad kan variëren per ServBay-versie:

    # Voorbeeld, pas het pad aan indien nodig
    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

• Configuratieprobleem (bind-address):
  • Staat bind-address op 127.0.0.1 of localhost in my.cnf, dan accepteert de server alleen lokale verbindingen. Voor toegang van buitenaf zet u dit op 0.0.0.0 (alle IP’s) of een specifiek IP en controleert u de firewall.
• Netwerkconfiguratieprobleem (localhost resolutie):
  • Zorg dat localhost naar 127.0.0.1 (IPv4) en/of ::1 (IPv6) verwijst.
  • Test met ping localhost in de terminal.
  • Controleer of /etc/hosts niet verkeerd is aangepast en nog de juiste regels bevat.
  • Schakel eventueel een proxy uit; deze kunnen lokale verbindingen verstoren.

3. MariaDB/MySQL-pakket start niet op

Mogelijke oorzaken en oplossingen:

1. Bekijk het foutenlogboek (zeer belangrijk!): Zoals eerder, open /Applications/ServBay/logs/mariadb/<version>/<version>.err voor de exacte fout.
2. Fout in configuratiebestand:
   • Syntaxfouten, ongeldige parameters of foute paden in /Applications/ServBay/etc/mariadb/<version>/my.cnf.
   • Controleer het bestand op syntaxfouten (let op: het exacte pad naar mysqld kan verschillen per versie):

     # Voorbeeld
     /Applications/ServBay/bin/mariadb/<version>/bin/mysqld --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf --validate-config

3. Poort bezet: Zie hierboven, gebruik lsof -i :<port> of netstat.
4. Te weinig schijfruimte: Controleer of de database- (/Applications/ServBay/db/mariadb/<version>/) of log-directory (/Applications/ServBay/logs/mariadb/<version>/) voldoende vrije ruimte heeft.
5. Rechtenprobleem:
   • De systeemgebruiker waaronder MariaDB/MySQL draait (vaak _mysql) heeft mogelijk geen leesrechten op config, gegevens of logs. Dit wordt standaard door ServBay geregeld, maar handmatige wijzigingen kunnen problemen veroorzaken.
   • Controlevoorbeeld:

     ls -ld /Applications/ServBay/db/mariadb/<version>
     ls -l /Applications/ServBay/etc/mariadb/<version>/my.cnf
     ls -ld /Applications/ServBay/logs/mariadb/<version>

     Zorg dat de gebruiker de juiste lees-, schrijf- en uitvoerrechten heeft.
6. Databestanden beschadigd: Zie het onderdeel “Databasecrash of gegevenscorruptie” verderop. Bij bijvoorbeeld een niet goed afgesloten sessie kan de data corrupt raken.

Na oplossen:

• Herstart het pakket met: servbayctl restart mariadb <version>

4. Gebruikersrechten- of authenticatieproblemen

Na verbinding met de database kunt u meldingen als Access denied krijgen door een onjuist(e) gebruikersnaam, wachtwoord of rechten.

Mogelijke oorzaken en oplossingen:

• Onjuiste gebruikersnaam of wachtwoord: Controleer deze heel zorgvuldig bij het verbinding maken. ServBay biedt een optie om het root-wachtwoord te resetten mocht u deze vergeten zijn.
• Hostbeperking: Een databasegebruiker kan beperkt zijn tot een bepaald hostadres, bijvoorbeeld '<username>'@'localhost'. Verbinding via '<username>'@'127.0.0.1' kan dan mislukken. '%' staat alle hosts toe.
• Onvoldoende rechten: Mogelijk heeft de gebruiker onvoldoende rechten voor de doel-database of bepaalde bewerkingen.
• Gebruikersrechten controleren:
  • Meld u aan als gebruiker met voldoende rechten (zoals root):

    mysql -u root -p

  • In de betreffende SQL-shell:

    SHOW GRANTS FOR '<username>'@'<hostname>';
    -- Bijvoorbeeld, voor 'webapp' op 'localhost':
    SHOW GRANTS FOR 'webapp'@'localhost';
    -- Of 'admin' via elke host:
    SHOW GRANTS FOR 'admin'@'%';

  • Waar nodig rechten aanpassen via GRANT en REVOKE of nieuwe gebruikers aanmaken.

5. Prestatieproblemen

Een trage database heeft direct invloed op de respons van uw applicatie.

Mogelijke oorzaken en oplossingen:

1. Langzame queries: Niet-optimale query’s, te weinig indexen of slechte queryplannen.
   • Schakel de slow query-log in: Stel in my.cnf in: slow_query_log = 1, long_query_time = 1, en geef slow_query_log_file op. Herstart de database, analyseer het bestand.
   • Gebruik EXPLAIN: Analyseer trage queries door EXPLAIN ervoor te zetten. Zo ziet u indexgebruik en aantal gescande regels.

     EXPLAIN SELECT * FROM your_table_name WHERE column_name = 'value';

   • Query's optimaliseren: Herstructureer op basis van EXPLAIN de queries, voorkom bijvoorbeeld SELECT *, function calls in WHERE of JOIN-voorwaarden, en zorg dat indexen worden gebruikt.
2. Ontbrekende of foutieve indexering: Kolommen die vaak gefilterd, gesorteerd of gegroepeerd worden moeten een index krijgen.
   • Analyseer structuur en queries: Zoek uit welke kolommen baat hebben bij indexen.
   • Index creëren:

     CREATE INDEX idx_column_name ON your_table_name(column_name);

     Let wel: indexen kosten schrijfprestaties en schijfruimte — weeg dit af.
3. Cache-instellingen verkeerd: Parameters als innodb_buffer_pool_size, key_buffer_size (MyISAM) zijn te groot of te klein.
   • Pas configuratie aan: Stem af op het geheugen van uw Mac en het gebruik van de database. Voor InnoDB is innodb_buffer_pool_size essentieel — stel dit op 50-70% van het beschikbare geheugen als de machine hoofdzakelijk database serveert. Herstart vereist.

     [mysqld]
     # Voorbeeld, pas aan uw situatie aan, eenheden: bytes, K, M, G
     innodb_buffer_pool_size = 2G
     # Voor veel MyISAM-tabellen:
     # key_buffer_size = 256M

4. Hardware-bottleneck: Hoge CPU-belasting, te weinig geheugen of veel schijf-I/O. Gebruik Activiteitenweergave of de terminalcommando’s top/htop om knelpunten te ontdekken.

6. Databasecrash of gegevenscorruptie

Onmogelijk opstarten, vaak vastlopen of vreemde data kan wijzen op beschadigde databestanden.

Mogelijke oorzaken en oplossingen:

1. Bekijk foutenlog: Altijd eerst controleren — /Applications/ServBay/logs/mariadb/<version>/<version>.err bevat vaak duidelijke foutmeldingen, zoals InnoDB-problemen of hardwarefouten.
2. Hardwaredefect: Problemen met schijven of geheugen veroorzaken fouten. Controleer systeemlogs (Console.app) en voer hardwaretests uit.
3. Softwareconflict of bug: Specifieke MariaDB/MySQL-versies kunnen bugs bevatten of conflicteren met andere software.
4. Fout in configuratie: Slechte parameters kunnen leiden tot instabiliteit of crashes.
5. Hard reset/incomplete afsluiting: Servers abrupt stoppen (zoals directe app-sluiting of geforceerd beëindigen) kan inconsistenties veroorzaken.

Oplossingen:

• Probeer een normale herstart: Via ServBay of servbayctl restart mariadb <version>. Soms kan de database zichzelf herstellen.
• Gebruik mysqlcheck voor controle en herstel van tabellen: Vooral effectief voor MyISAM-tabellen.

  # Gebruik het ServBay my.cnf en rootgebruiker voor controle van alle databases/tabellen
  mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --check --all-databases
  # Voor MyISAM automatische reparatie proberen:
  # mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --auto-repair --check --all-databases

  Let op: --auto-repair werkt vooral voor MyISAM. InnoDB-hertstel vereist meestal complexe handelingen of het terugzetten van een back-up.
• InnoDB geforceerd herstel (innodb_force_recovery): Als InnoDB niet wil opstarten, kunt u geforceerd proberen een back-up te maken. Let op: dit is risicovol en kan leiden tot dataverlies! Alleen proberen als laatste redding.
  1. Maak altijd eerst een kopie van de datamap, ook als deze (deels) stuk is: Kopieer /Applications/ServBay/db/mariadb/<version>/ naar een veilige locatie.
  2. Bewerk het configuratiebestand van het getroffen pakket (/Applications/ServBay/etc/mariadb/<version>/my.cnf).
  3. Voeg onder [mysqld] een regel toe: innodb_force_recovery = N (waarbij N start bij 1, als het niet lukt langzaam verhogen naar 6, probeer steeds maar één niveau tegelijk en herstart tussen de pogingen).
  4. Start MariaDB/MySQL: servbayctl start mariadb <version>.
  5. Als het lukt te starten, maak direct met mysqldump een back-up!

     mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --all-databases --routines --triggers --events > /path/to/your_emergency_backup.sql

     Controleer het back-upbestand op inhoud en grootte.
  6. Stop MariaDB/MySQL direct na het back-uppen: servbayctl stop mariadb <version>.
  7. Verwijder of comment innodb_force_recovery = N in het configuratiebestand.
  8. Dataherstel uitvoeren: Meestal komt dit neer op het initialiseren van een nieuwe datamap (hernoem of verwijder de corrupte map) en het importeren van de back-up.
• Herstel vanuit een back-up: Als bovenstaande niet werkt of de data inconsistent is, is terugzetten vanuit een back-up de betrouwbaarste weg. ServBay's ingebouwde back-upbestanden vindt u doorgaans op: /Applications/ServBay/backup/mariadb/<version>/.
  • Herstelvoorbeeld (waarin <target_database_name> de database is waarin u herstelt):

    # Zorg dat de target database bestaat:
    # mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"
    
    # Importeer het back-upbestand:
    mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

    Opmerking: Vervang <version> door uw MariaDB/MySQL-versie.

7. Problemen bij back-up en herstel

Bij het werken met de ingebouwde ServBay-back-ups of handmatige mysqldump-back-ups kunt u issues tegenkomen.

Mogelijke oorzaken en oplossingen:

• Back-upbestand is incompleet/beschadigd:
  • Controleer de bestandsgrootte (ls -lh /path/to/your_backup.sql).
  • Open het bestand met een teksteditor of less om te kijken of het een geldig SQL-bestand is.
  • Bij een handmatige dump, check of er foutmeldingen waren. Kijk bij ServBay's logboek voor terugkijk op back-upacties.
• Fout in herstelcommando:
  • Mogelijk heeft u een verkeerde gebruikersnaam, wachtwoord of database ingegeven, of onvoldoende rechten.
  • SQL-fouten: Migratie tussen verschillende database-types of -versies (MariaDB vs MySQL) kan incompatibiliteit veroorzaken.
• Problemen met foreign keys: Importvolgorde kan van belang zijn door onderlinge afhankelijkheden. U kunt tijdelijk foreign key-controle uitzetten:

  -- Voor de import:
  SET foreign_key_checks = 0;
  -- Uitvoeren van de import, bijvoorbeeld:
  source /path/to/your_backup.sql; -- Binnen de mysql-shell
  -- Of importeren met de commandline: mysql ... < /path/to/your_backup.sql
  
  -- Na afloop:
  SET foreign_key_checks = 1;

  Let op: Zet foreign key checks alleen uit bij import — onjuiste datarelaties kunnen anders ontstaan.
• Problemen met tekenset/collation: Tekenreeksen of tabellen in de back-up gebruiken mogelijk een andere collatie of character set dan de doelomgeving. Stem dit vóór import af (bijv. op utf8mb4).

Correct herstellen via de command line:

# Stel: de back-up is van één database
# Zorg dat de doeldatabase (<target_database_name>) bestaat
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"

# Importeer op juiste wijze:
mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

# Als het een complete all-databases-back-up betreft:
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

Let op: Vervang <version> door de juiste MariaDB/MySQL-versie. ServBay's back-ups zijn standaard compatible en makkelijk te herstellen.

8. Specifieke Bug: MariaDB 11.5.1 InnoDB start niet (ib_logfile0 was not found / Missing FILE_CHECKPOINT)

Dit is een bekende, ernstige bug in MariaDB 11.5.1 waarbij InnoDB soms niet kan initialiseren of logbestanden kan uitlezen. De database start dan niet op.

Kenmerken in het foutenlog:

In /Applications/ServBay/logs/mariadb/11.5/11.5.err kan je foutmeldingen zien als:

[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

of

[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

Deze fouten geven aan dat InnoDB zijn logbestanden niet kan vinden of lezen en daardoor faalt.

Oplossing (data-migratie noodzakelijk, maak altijd eerst een back-up!):

Deze bug is niet of nauwelijks structureel te herstellen. De beste aanpak is geforceerd opstarten om de data te exporteren, en deze vervolgens naar een stabiele MariaDB-versie te migreren.

1. Probeer geforceerd te herstellen voor een back-up (risicovolle actie!):
   • Bewerk /Applications/ServBay/etc/mariadb/11.5/my.cnf.
   • Voeg onder [mysqld] toe: innodb_force_recovery = 6
   • Start MariaDB 11.5 via ServBay of command line: servbayctl start mariadb 11.5
   • Als het lukt, maak direct via mysqldump een volledige back-up!

     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

     Controleer of het back-upbestand geldig is en een realistische grootte heeft.
2. Stop het pakket en behandel de probleemdata:
   • Stop MariaDB 11.5: servbayctl stop mariadb 11.5
   • Verwijder of comment innodb_force_recovery uit het config-bestand.