Baza danych dla FiveM: oxmysql, połączenie i import SQL

Frameworki i większość skryptów przechowują postacie, pieniądze, samochody i ekwipunki w bazie danych. FiveM korzysta z niej przez zasób oxmysql. Pokażemy, jak utworzyć bazę danych, poprawnie się z nią połączyć, zaimportować do niej SQL i ją zarchiwizować.

Dlaczego oxmysql#

oxmysql to biblioteka, przez którą inne zasoby wysyłają zapytania do bazy danych MySQL lub MariaDB. Zastępuje starsze mysql-async i ghmattimysql i rozumie ich składnię, więc starsze skrypty nadal działają. Przepisy txAdmin dla ESX, QBCore i Qbox instalują ją za Ciebie.

Autorzy oxmysql zalecają bazę danych MariaDB. Większość skryptów FiveM została napisana pod MySQL 5.7 i często ma problemy z MySQL 8 (więcej słów zastrzeżonych, wartości domyślne kolumn JSON).

Tworzenie bazy danych#

1. W strefie klienta otwórz Moje usługi, kliknij swój serwer i przejdź do zakładki Baza danych.
2. W polu Nazwa bazy danych wpisz nazwę, na przykład fivem. Dozwolone są litery, cyfry i podkreślenia.
3. W polu Dozwolone połączenia z wpisz % (wartość domyślna).
4. Kliknij Utwórz bazę danych.

Baza danych pokazuje następujące dane:

• Nowe hasło generuje nowe hasło. Stare przestaje działać, więc musisz je zmienić także w server.cfg.
• Liczba baz danych jest ograniczona pakietem; bieżący stan widzisz jako Wykorzystano X z Y.
• Jeśli Host, Użytkownik lub Dozwolone połączenia z zakrywa kreskowany pasek, włączony jest tryb streamera. Kliknij Pokaż szczegóły u góry albo skopiuj wartość ikoną obok.

Instalacja oxmysql#

Jeśli serwer wdrożono z przepisu frameworka w txAdmin, oxmysql już masz i możesz pominąć tę sekcję.

1. Pobierz najnowsze wydanie z oxmysql na GitHubie (otwiera się w nowym oknie) (plik oxmysql.zip, nie kod źródłowy).
2. Rozpakuj archiwum. Otrzymasz folder oxmysql z plikiem fxmanifest.lua i podfolderami dist, lib, web i logger.
3. Prześlij cały folder oxmysql do resources na serwerze (podfoldery utwórz przyciskiem Nowy folder; procedura jest w artykule Zasoby FiveM).

Connection string#

oxmysql odczytuje dane logowania ze zmiennej mysql_connection_string w server.cfg. Możesz zapisać ją na dwa sposoby:

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>"

Użyj tylko jednej z tych linii. Dla hasła z zakładki Baza danych właściwym wyborem jest pierwsza forma (URI), bo radzi sobie ze wszystkimi znakami, które w nim występują (zobacz „Znaki specjalne w haśle”). Wartości w nawiasach ostrych zastąp danymi z zakładki Baza danych, bez nawiasów:

• set – zmienna zostaje tylko na serwerze. Nigdy nie używaj setr ani sets; hasło zostałoby wysłane graczom lub upublicznione.
• mysql:// – oznacza pierwszą formę (URI). Druga forma składa się z par klucz=wartość oddzielonych średnikami.

Znaki specjalne w haśle#

oxmysql w żaden sposób nie dekoduje ciągu, więc zapis typu %40 zamiast @ nie działa. Wklej hasło dokładnie takie, jakie jest. Autorzy oxmysql ogólnie radzą unikać w haśle znaków ; , / ? : @ & = + $ # albo przejść na drugą formę. Na podstawie tego, jak oxmysql faktycznie dzieli ciąg:

Hasła tworzone przez zakładkę Baza danych zawierają, oprócz liter i cyfr, tylko znaki, z którymi forma URI sobie radzi (na przykład @, =, +, !, .). Używaj więc dla nich formy URI i nie zmieniaj hasła.

Gdzie umieścić linię#

Linia set mysql_connection_string musi być w server.cfg przed linią ensure oxmysql, a oxmysql musi startować przed wszystkimi skryptami, które używają bazy danych:

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

ensure oxmysql
ensure ox_lib
ensure es_extended

Import SQL w HeidiSQL#

Skrypty często zawierają plik .sql, który tworzy potrzebne im tabele. Aby zaimportować go przez HeidiSQL:

1. Pobierz i zainstaluj HeidiSQL (otwiera się w nowym oknie).

2. Uruchom program. W oknie Session manager kliknij New w lewym dolnym rogu.

3. Wypełnij zakładkę Settings:

   Pole	Co wpisać
   Network type	MariaDB or MySQL (TCP/IP)
   Hostname / IP	Adres IP z pola Host (część przed dwukropkiem)
   User	Użytkownik z zakładki Baza danych
   Password	Hasło z zakładki Baza danych
   Port	Port z pola Host (część po dwukropku), zwykle 3306
   Databases	Nazwa bazy danych (opcjonalnie; HeidiSQL pokaże wtedy tylko tę bazę)

4. Kliknij Open. Po lewej stronie pojawi się Twoja baza danych.

5. Kliknij bazę danych, aby ją zaznaczyć (aktywować).

6. W menu wybierz File › Run SQL file… i wskaż plik .sql.

7. W opcji Encoding wybierz UTF-8 i potwierdź.

   HeidiSQL od razu wykona polecenia. Po zakończeniu naciśnij F5, a w bazie zobaczysz nowe tabele.

Jeśli HeidiSQL nie może się połączyć, sprawdź, czy Dozwolone połączenia z ma wartość % (albo Twój publiczny adres IP).

Strojenie zapytań#

Kopia zapasowa bazy danych#

Zakładka Kopie zapasowe archiwizuje tylko pliki serwera. Bazę danych archiwizuj osobno:

1. W HeidiSQL kliknij bazę danych prawym przyciskiem i wybierz Export database as SQL.
2. Zaznacz tabele (wszystkie) i zostaw Data na Insert.
3. W Output wybierz Single .sql file, wskaż plik i kliknij Export.

Kopię zapasową rób przed aktualizacją frameworka, przed instalacją dużego skryptu i regularnie (na przykład raz w tygodniu). Aby przywrócić, zaimportuj plik zgodnie z sekcją „Import SQL w HeidiSQL”.

Weryfikacja#

Po restarcie serwera znajdziesz w konsoli tę linię:

[<DATABASE_VERSION>] Database server connection established!

W nawiasach kwadratowych jest wersja serwera bazy danych (na przykład z MariaDB w nazwie). Potem frameworki zgłaszają wczytanie bez błędów bazy danych.

Rozwiązywanie problemów#

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

Błędny użytkownik lub hasło. Skopiuj je ponownie z zakładki Baza danych. Sprawdź, czy hasła nie masz w formie ze średnikami ze znakiem = (użyj formy URI, zobacz tabelę wyżej) i czy w żaden sposób go nie zakodowano (%40 zamiast @). Pomóc może też Nowe hasło.

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

Błędny adres lub port. Connection string potrzebuje adresu IP i portu z pola Host, nie localhost.

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

Baza danych o tej nazwie nie istnieje. Skopiuj Nazwę bazy danych dokładnie z listy.

mysql_connection_string structure was invalid#

Ciągu w formie URI nie da się sparsować. Sprawdź, czy zaczyna się od mysql:// i zawiera @, oraz czy hasło nie zawiera /, ? ani #.

Table '….users' doesn't exist (lub inna tabela)#

Brakuje tabel skryptu lub frameworka. Zaimportuj jego plik .sql.

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

Nowa tabela ma inny zestaw znaków (collation) niż istniejące. Dodaj DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci na końcu poleceń CREATE TABLE w pliku .sql i uruchom import ponownie.

Po przywróceniu kopii zapasowej brakuje danych graczy#

Kopie zapasowe w zakładce Kopie zapasowe zawierają tylko pliki serwera, nie bazę danych. Przywrócenie kopii nie przywraca więc bazy danych. Dane bazy przywróć z własnego eksportu .sql.

Dalsza lektura#

• oxmysql: dokumentacja (otwiera się w nowym oknie)
• oxmysql na GitHubie (otwiera się w nowym oknie)
• HeidiSQL: pomoc (otwiera się w nowym oknie)