Frameworks und die meisten Skripte speichern Charaktere, Geld, Autos und Inventare in einer Datenbank. FiveM greift darauf über die Resource oxmysql zu. Wir zeigen Ihnen, wie Sie die Datenbank anlegen, sich richtig verbinden, SQL importieren und sie sichern.
Was Sie brauchen
- Ein FiveM-Server bei StormHost (oder Ihr eigener FiveM-Server mit einer MariaDB-Datenbank)
- Die Berechtigung Datenbanken (der Inhaber hat sie immer)
- HeidiSQL (öffnet sich in einem neuen Fenster) unter Windows (für Import und Backups)
- Etwa 20 Minuten
Warum oxmysql#
oxmysql ist eine Bibliothek, über die andere Resources Abfragen an eine MySQL- oder MariaDB-Datenbank senden. Sie ersetzt die älteren mysql-async und ghmattimysql und versteht deren Syntax, sodass ältere Skripte weiter funktionieren. Die txAdmin-Rezepte für ESX, QBCore und Qbox installieren sie für Sie.
Die Autoren von oxmysql empfehlen eine MariaDB-Datenbank. Die meisten FiveM-Skripte wurden für MySQL 5.7 geschrieben und haben oft Probleme mit MySQL 8 (mehr reservierte Wörter, Standardwerte bei JSON-Spalten).
Datenbank anlegen#
- Öffnen Sie im Kundenbereich Meine Dienste, klicken Sie auf Ihren Server und wechseln Sie zur Registerkarte Datenbank.
- Geben Sie im Feld Datenbankname einen Namen ein, zum Beispiel
fivem. Erlaubt sind Buchstaben, Zahlen und Unterstriche. - Geben Sie im Feld Erlaubte Verbindungen von
%ein (der Standardwert). - Klicken Sie auf Datenbank erstellen.
Die Datenbank zeigt diese Daten:
| Angabe | Was sie bedeutet | Wo Sie sie verwenden |
|---|---|---|
| Datenbankname | Der tatsächliche Datenbankname. Er kann von Ihrer Eingabe abweichen, kopieren Sie ihn daher immer aus der Liste. | Connection String, HeidiSQL, txAdmin (Database Name). |
| Benutzer | Ein Datenbankbenutzer mit Berechtigungen nur für diese Datenbank. | Connection String, HeidiSQL. |
| Host | Die Adresse des Datenbankservers in der Form IP:Port, zum Beispiel 203.0.113.20:3306. | Der Teil vor dem Doppelpunkt ist der Host, der Teil danach der Port. |
| Passwort | Das Passwort des Benutzers. Anzeigen mit dem Augensymbol, kopieren mit dem Symbol daneben. | Connection String, HeidiSQL. |
| Erlaubte Verbindungen von | Von wo Verbindungen zur Datenbank erlaubt sind. % = überall, sonst eine einzelne IP-Adresse. | Sie brauchen %, wenn Sie sich auch von Ihrem Computer mit HeidiSQL verbinden möchten. |
- Neues Passwort erzeugt ein neues Passwort. Das alte funktioniert nicht mehr, Sie müssen es also auch in der
server.cfgändern. - Die Anzahl der Datenbanken ist durch Ihren Tarif begrenzt; den aktuellen Stand sehen Sie als
X von Y verwendet. - Wenn Host, Benutzer oder Erlaubte Verbindungen von von einem schraffierten Balken verdeckt sind, ist der Streamer-Modus eingeschaltet. Klicken Sie oben auf Details anzeigen oder kopieren Sie den Wert mit dem Symbol daneben.
Löschen löscht auch die Daten
Die Schaltfläche Löschen entfernt die Datenbank dauerhaft, samt aller Spielercharaktere und ihres Geldes. Backups in der Registerkarte Backups enthalten nur die Serverdateien, nicht die Datenbank. Exportieren Sie die Datenbank vor dem Löschen (siehe „Datenbank-Backup“).
oxmysql installieren#
Wenn Sie den Server mit einem Framework-Rezept von txAdmin deployt haben, haben Sie oxmysql bereits und können diesen Abschnitt überspringen.
- Laden Sie die neueste Version von oxmysql auf GitHub (öffnet sich in einem neuen Fenster) herunter (die Datei
oxmysql.zip, nicht den Quellcode). - Entpacken Sie das Archiv. Sie erhalten einen Ordner
oxmysqlmit einer Dateifxmanifest.luaund den Unterordnerndist,lib,webundlogger. - Laden Sie den gesamten Ordner
oxmysqlnachresourcesauf dem Server hoch (Unterordner legen Sie mit der Schaltfläche Neuer Ordner an; das Vorgehen steht in FiveM-Resources).
Connection String#
oxmysql liest die Zugangsdaten aus der Variable mysql_connection_string in der server.cfg. Sie können sie auf zwei Arten schreiben:
set mysql_connection_string "mysql://<BENUTZER>:<PASSWORT>@<DATENBANK_IP>:<PORT>/<DATENBANKNAME>"set mysql_connection_string "user=<BENUTZER>;password=<PASSWORT>;host=<DATENBANK_IP>;port=<PORT>;database=<DATENBANKNAME>"Verwenden Sie nur eine dieser Zeilen. Für ein Passwort aus der Registerkarte Datenbank ist die erste (URI-)Form die richtige Wahl, weil sie mit allen darin vorkommenden Zeichen zurechtkommt (siehe „Sonderzeichen im Passwort“). Ersetzen Sie die Werte in spitzen Klammern durch die Daten aus der Registerkarte Datenbank, ohne die Klammern:
| Teil | Woher |
|---|---|
<BENUTZER> | Benutzer |
<PASSWORT> | Passwort |
<DATENBANK_IP> | Host, der Teil vor dem Doppelpunkt (zum Beispiel 203.0.113.20) |
<PORT> | Host, der Teil nach dem Doppelpunkt (in der Regel 3306) |
<DATENBANKNAME> | Datenbankname, genau wie in der Liste angezeigt |
set– die Variable bleibt nur auf dem Server. Verwenden Sie niesetrodersets; das Passwort würde an Spieler gesendet oder veröffentlicht.mysql://– kennzeichnet die erste (URI-)Form. Die zweite Form besteht ausschlüssel=wert-Paaren, getrennt durch Semikolons.
Sonderzeichen im Passwort#
oxmysql dekodiert die Zeichenkette in keiner Weise, also funktioniert so etwas wie %40 statt @ nicht. Fügen Sie das Passwort genau so ein, wie es ist. Die Autoren von oxmysql raten allgemein, die Zeichen ; , / ? : @ & = + $ # im Passwort zu vermeiden oder auf die zweite Form zu wechseln. Basierend darauf, wie oxmysql die Zeichenkette tatsächlich zerlegt:
| Das Passwort enthält | Verwenden Sie |
|---|---|
nur Buchstaben, Zahlen und die Zeichen @ = + ! . ^ & $ , ; | Die URI-Form (mysql://…). Diese Zeichen stören sie nicht. Die Semikolon-Form hingegen trennt an = und ;. |
: / ? oder # | Die Semikolon-Form (user=…;password=…). Die URI-Form trennt an diesen Zeichen. |
" | Keine von beiden. Das Anführungszeichen beendet den Wert in der server.cfg. |
: / ? # zusammen mit = oder ; | Klicken Sie in der Registerkarte Datenbank auf Neues Passwort und verwenden Sie das neue Passwort. |
Von der Registerkarte Datenbank erzeugte Passwörter enthalten neben Buchstaben und Zahlen nur Zeichen, mit denen die URI-Form zurechtkommt (zum Beispiel @, =, +, !, .). Verwenden Sie für sie also die URI-Form und ändern Sie das Passwort nicht.
Wo die Zeile hingehört#
Die Zeile set mysql_connection_string muss in der server.cfg vor der Zeile ensure oxmysql stehen, und oxmysql muss vor allen Skripten starten, die die Datenbank verwenden:
set mysql_connection_string "mysql://<BENUTZER>:<PASSWORT>@<DATENBANK_IP>:3306/<DATENBANKNAME>"
ensure oxmysql
ensure ox_lib
ensure es_extendedSQL in HeidiSQL importieren#
Skripte enthalten oft eine .sql-Datei, die die benötigten Tabellen anlegt. So importieren Sie sie mit HeidiSQL:
Laden Sie HeidiSQL (öffnet sich in einem neuen Fenster) herunter und installieren Sie es.
Starten Sie es. Klicken Sie im Fenster Session manager unten links auf New.
Füllen Sie die Registerkarte Settings aus:
Feld Was eintragen Network type MariaDB or MySQL (TCP/IP)Hostname / IP Die IP-Adresse aus dem Feld Host (der Teil vor dem Doppelpunkt) User Benutzer aus der Registerkarte Datenbank Password Passwort aus der Registerkarte Datenbank Port Der Port aus dem Feld Host (der Teil nach dem Doppelpunkt), in der Regel 3306Databases Der Datenbankname (optional; HeidiSQL zeigt dann nur diese Datenbank) Klicken Sie auf Open. Ihre Datenbank erscheint links.
Klicken Sie auf die Datenbank, sodass sie ausgewählt (aktiv) ist.
Wählen Sie im Menü File › Run SQL file… und wählen Sie die
.sql-Datei aus.Wählen Sie bei der Option Encoding
UTF-8und bestätigen Sie.HeidiSQL führt die Anweisungen sofort aus. Wenn es fertig ist, drücken Sie F5, und Sie sehen die neuen Tabellen in der Datenbank.
Wenn HeidiSQL keine Verbindung herstellen kann, prüfen Sie, dass Erlaubte Verbindungen von auf % (oder Ihrer öffentlichen IP-Adresse) steht.
Abfragen optimieren#
| Einstellung | Was sie tut | Empfohlener Wert |
|---|---|---|
set mysql_slow_query_warning 300 | Warnt in der Konsole, wenn eine Abfrage länger als die angegebene Anzahl Millisekunden dauert. Der Standard ist 200. | Fügen Sie die Zeile nicht hinzu; der Standard reicht. Setzen Sie nur dann eine höhere Zahl, wenn die Warnungen Ihre Konsole fluten. Langsame Abfragen beim Serverstart sind in Ordnung. |
set mysql_debug true | Gibt alle Abfragen in der Konsole aus. Lässt sich auf ausgewählte Resources beschränken (die Syntax steht in der oxmysql-Dokumentation). | Nur während der Fehlersuche, danach wieder ausschalten. |
set mysql_ui true | Aktiviert den Spielbefehl /mysql mit einer Übersicht der Abfragen und ihrer Zeiten (erfordert die Berechtigung command.mysql). | Nur während der Entwicklung oder mit wenigen Spielern. |
Datenbank-Backup#
Die Registerkarte Backups sichert nur die Serverdateien. Sichern Sie die Datenbank separat:
- Klicken Sie in HeidiSQL mit der rechten Maustaste auf die Datenbank und wählen Sie Export database as SQL.
- Haken Sie die Tabellen an (alle) und lassen Sie Data auf
Insert. - Wählen Sie bei Output
Single .sql file, wählen Sie eine Datei und klicken Sie auf Export.
Erstellen Sie ein Backup vor dem Aktualisieren des Frameworks, vor der Installation eines großen Skripts und regelmäßig (zum Beispiel einmal pro Woche). Zum Wiederherstellen importieren Sie die Datei wie unter „SQL in HeidiSQL importieren“ beschrieben.
Überprüfung#
Nach dem Neustart des Servers finden Sie diese Zeile in der Konsole:
[<DATENBANK_VERSION>] Database server connection established!In den eckigen Klammern steht die Version des Datenbankservers (zum Beispiel mit MariaDB darin). Danach melden Frameworks das Laden ohne Datenbankfehler.
Fehlerbehebung#
Unable to establish a connection to the database (ER_ACCESS_DENIED_ERROR)! #
Falscher Benutzer oder falsches Passwort. Kopieren Sie beides erneut aus der Registerkarte Datenbank. Prüfen Sie, dass Sie das Passwort nicht in der Semikolon-Form mit einem =-Zeichen haben (verwenden Sie die URI-Form, siehe Tabelle oben) und dass Sie es nicht irgendwie kodiert haben (%40 statt @). Auch Neues Passwort kann helfen.
Unable to establish a connection to the database (ECONNREFUSED)! oder (ETIMEDOUT)#
Falsche Adresse oder falscher Port. Der Connection String braucht die IP-Adresse und den Port aus dem Feld Host, nicht localhost.
Unable to establish a connection to the database (ER_BAD_DB_ERROR)!#
Eine Datenbank mit diesem Namen existiert nicht. Kopieren Sie den Datenbanknamen genau aus der Liste.
mysql_connection_string structure was invalid#
Die Zeichenkette in URI-Form kann nicht geparst werden. Prüfen Sie, dass sie mit mysql:// beginnt und ein @ enthält, und dass das Passwort kein /, ? oder # enthält.
Table '….users' doesn't exist (oder eine andere Tabelle)#
Die Tabellen des Skripts oder Frameworks fehlen. Importieren Sie dessen .sql-Datei.
Can't create table … (Foreign Key Constraint is incorrectly formed)#
Die neue Tabelle hat einen anderen Zeichensatz (Collation) als die vorhandenen. Fügen Sie in der .sql-Datei am Ende der CREATE TABLE-Anweisungen DEFAULT CHARSET=utf8mb4 COLLATE= hinzu und führen Sie den Import erneut aus.
Nach der Wiederherstellung eines Backups fehlen Spielerdaten#
Backups in der Registerkarte Backups enthalten nur die Serverdateien, nicht die Datenbank. Die Wiederherstellung eines Backups bringt die Datenbank daher nicht zurück. Stellen Sie die Datenbankdaten aus Ihrem eigenen .sql-Export wieder her.
Zusammenfassung
- Legen Sie die Datenbank in der Registerkarte Datenbank an. Host und Port stehen im Feld Host; kopieren Sie den Namen aus der Liste.
set mysql_connection_string "…"gehört in dieserver.cfgvorensure oxmysql, immer mitset.- Ein Passwort aus der Registerkarte Datenbank kommt genau so, wie es ist, in die URI-Form (
mysql://…). Verwenden Sie die Semikolon-Form nur für Passwörter mit:/?#. URL-Kodierung funktioniert nicht. - Importieren Sie SQL in HeidiSQL mit File › Run SQL file… und sichern Sie die Datenbank mit Export database as SQL.