Database voor FiveM: oxmysql, verbinding en SQL-import

Frameworks en de meeste scripts slaan personages, geld, auto's en inventarissen op in een database. FiveM benadert die via de resource oxmysql. We laten zien hoe je de database aanmaakt, goed koppelt, er SQL in importeert en er een back-up van maakt.

Waarom oxmysql#

oxmysql is een bibliotheek waarmee andere resources query's naar een MySQL- of MariaDB-database sturen. Het vervangt de oudere mysql-async en ghmattimysql en begrijpt hun syntaxis, zodat oudere scripts blijven werken. De txAdmin-recepten voor ESX, QBCore en Qbox installeren het vanzelf.

De makers van oxmysql raden een MariaDB-database aan. De meeste FiveM-scripts zijn gemaakt voor MySQL 5.7 en hebben met MySQL 8 nogal eens problemen (meer gereserveerde woorden, standaardwaarden bij JSON-kolommen).

De database aanmaken#

1. Open in je klantaccount Mijn diensten, klik op de server en ga naar het tabblad Databases.
2. Typ in het veld Databasenaam een naam, bijvoorbeeld fivem. Letters, cijfers en underscores zijn toegestaan.
3. Typ in het veld Toegang toegestaan vanaf % (de standaardwaarde).
4. Klik op Database aanmaken.

Bij de database zie je deze gegevens:

• Nieuw wachtwoord genereert een nieuw wachtwoord. Het oude werkt dan niet meer, je moet het dus ook in server.cfg wijzigen.
• Het aantal databases is beperkt door je pakket, de stand zie je als X van Y gebruikt.
• Zijn Host, Gebruiker of Toegang toegestaan vanaf afgedekt met een gearceerde balk, dan staat de streamermodus aan. Klik bovenaan op Gegevens tonen, of kopieer de waarde met het pictogram ernaast.

oxmysql installeren#

Heb je de server gedeployd met een txAdmin-recept voor een framework, dan heb je oxmysql al en kun je dit gedeelte overslaan.

1. Download de nieuwste release van de GitHub-pagina van oxmysql (opent in een nieuw venster) (het bestand oxmysql.zip, niet de broncode).
2. Pak het archief uit. Je krijgt een map oxmysql met het bestand fxmanifest.lua en de submappen dist, lib, web en logger.
3. Upload de hele map oxmysql naar resources op de server (submappen maak je aan met de knop Nieuwe map, de stappen staan in de handleiding FiveM resources).

Connection string#

oxmysql leest de inloggegevens uit de variabele mysql_connection_string in server.cfg. Je kunt die op twee manieren schrijven:

set mysql_connection_string "mysql://<USER>:<PASSWORD>@<DATABASE_IP>:<PORT>/<DATABASE_NAME>"

set mysql_connection_string "user=<USER>;password=<PASSWORD>;host=<DATABASE_IP>;port=<PORT>;database=<DATABASE_NAME>"

Gebruik maar één van de regels. Voor een wachtwoord van het tabblad Databases is de eerste vorm (URI) de juiste keuze, omdat die overweg kan met alle tekens die erin voorkomen (gedeelte “Speciale tekens in het wachtwoord”). Vervang de waarden tussen punthaken door de gegevens van het tabblad Databases, zonder de haken:

• set – de variabele blijft alleen op de server. Gebruik nooit setr of sets, want dan wordt het wachtwoord naar spelers gestuurd of openbaar gemaakt.
• mysql:// – geeft de eerste vorm (URI) aan. De tweede vorm bestaat uit paren sleutel=waarde, gescheiden door een puntkomma.

Speciale tekens in het wachtwoord#

oxmysql decodeert de string op geen enkele manier, dus een schrijfwijze als %40 in plaats van @ werkt niet. Plak het wachtwoord precies zoals het is. De makers van oxmysql raden in het algemeen aan om de tekens ; , / ? : @ & = + $ # in het wachtwoord te vermijden, of anders over te stappen op de tweede schrijfwijze. Op basis van hoe oxmysql de string in werkelijkheid opsplitst, geldt:

Wachtwoorden die het tabblad Databases aanmaakt, bevatten naast letters en cijfers alleen tekens waarmee de URI-vorm overweg kan (bijvoorbeeld @, =, +, !, .). Gebruik daarvoor dus de URI-vorm en pas het wachtwoord niet aan.

Waar je de regel zet#

De regel met set mysql_connection_string moet in server.cfg vóór de regel ensure oxmysql staan, en oxmysql moet starten vóór alle scripts die de database gebruiken:

set mysql_connection_string "mysql://<USER>:<PASSWORD>@<DATABASE_IP>:3306/<DATABASE_NAME>"

ensure oxmysql
ensure ox_lib
ensure es_extended

SQL importeren in HeidiSQL#

Scripts bevatten vaak een .sql-bestand dat de benodigde tabellen aanmaakt. Importeren via HeidiSQL:

1. Download en installeer HeidiSQL (opent in een nieuw venster).

2. Start het programma. Klik in het venster Session manager linksonder op New.

3. Vul het tabblad Settings in:

   Veld	Wat je invult
   Network type	MariaDB or MySQL (TCP/IP)
   Hostname / IP	Het IP-adres uit het veld Host (het deel vóór de dubbele punt)
   User	Gebruiker van het tabblad Databases
   Password	Wachtwoord van het tabblad Databases
   Port	De poort uit het veld Host (het deel na de dubbele punt), meestal 3306
   Databases	De naam van de database (optioneel, HeidiSQL toont dan alleen die database)

4. Klik op Open. Links zie je je database.

5. Klik op de database, zodat die geselecteerd (actief) is.

6. Kies in het menu File › Run SQL file… en selecteer het .sql-bestand.

7. Kies bij de optie Encoding voor UTF-8 en bevestig.

   HeidiSQL voert de commando's meteen uit. Druk na afloop op F5 en je ziet de nieuwe tabellen in de database.

Krijgt HeidiSQL geen verbinding, controleer dan of Toegang toegestaan vanaf op % staat (of op je openbare IP-adres).

Query's debuggen#

Back-up van de database#

Het tabblad Back-ups maakt alleen een back-up van de bestanden van de server. Maak van de database apart een back-up:

1. Klik in HeidiSQL met de rechtermuisknop op de database en kies Export database as SQL.
2. Vink de tabellen aan (allemaal) en laat Data op Insert staan.
3. Kies bij Output voor Single .sql file, selecteer een bestand en klik op Export.

Maak een back-up vóór een update van het framework, vóór de installatie van een groot script en regelmatig (bijvoorbeeld één keer per week). Herstellen doe je door het bestand te importeren volgens de stappen in “SQL importeren in HeidiSQL”.

Controle#

Na een herstart van de server vind je in de console deze regel:

[<DATABASE_VERSION>] Database server connection established!

Tussen de vierkante haken staat de versie van de databaseserver (bijvoorbeeld met de aanduiding MariaDB). Daarna melden frameworks dat ze zonder databasefouten zijn geladen.

Als iets niet werkt#

Unable to establish a connection to the database (ER_ACCESS_DENIED_ERROR)!#

Verkeerde gebruiker of verkeerd wachtwoord. Kopieer ze opnieuw van het tabblad Databases. Controleer of het wachtwoord niet in de puntkommavorm staat met het teken = (gebruik de URI-vorm, zie de tabel hierboven) en of je het niet op een of andere manier hebt gecodeerd (%40 in plaats van @). Ook Nieuw wachtwoord kan helpen.

Unable to establish a connection to the database (ECONNREFUSED)! of (ETIMEDOUT)#

Verkeerd adres of verkeerde poort. In de connection string horen het IP-adres en de poort uit het veld Host, niet localhost.

Unable to establish a connection to the database (ER_BAD_DB_ERROR)!#

Er bestaat geen database met deze naam. Neem de Databasenaam exact over uit de lijst.

mysql_connection_string structure was invalid#

De string in de URI-vorm kan niet worden ontleed. Controleer of hij begint met mysql:// en @ bevat, en of het wachtwoord geen /, ? of # bevat.

Table '….users' doesn't exist (of een andere tabel)#

De tabellen van het script of het framework ontbreken. Importeer het bijbehorende .sql-bestand.

Can't create table … (Foreign Key Constraint is incorrectly formed)#

De nieuwe tabel heeft een andere tekenset (collation) dan de bestaande tabellen. Voeg aan het einde van de CREATE TABLE-commando's in het .sql-bestand DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci toe en herhaal de import.

Na het herstellen van een back-up ontbreken de gegevens van spelers#

De back-ups op het tabblad Back-ups bevatten alleen de bestanden van de server, niet de database. Het herstellen van een back-up brengt de database daarom niet terug. De data uit de database herstel je vanuit je eigen .sql-export.

Meer bronnen#

• oxmysql: documentatie (opent in een nieuw venster)
• oxmysql op GitHub (opent in een nieuw venster)
• HeidiSQL: help (opent in een nieuw venster)