Databáza pre FiveM: oxmysql, pripojenie a import SQL

Frameworky a väčšina skriptov ukladajú postavy, peniaze, autá a inventáre do databázy. FiveM k nej pristupuje cez resource oxmysql. Ukážeme, ako databázu vytvoriť, správne pripojiť, naimportovať do nej SQL a zálohovať.

Prečo oxmysql#

oxmysql je knižnica, cez ktorú ostatné resources posielajú dopyty do databázy MySQL alebo MariaDB. Nahrádza staršie mysql-async a ghmattimysql a ovláda ich zápis, takže staršie skripty fungujú ďalej. Recepty txAdminu pre ESX, QBCore a Qbox ju inštalujú samy.

Autori oxmysql odporúčajú databázu MariaDB. Väčšina skriptov FiveM vznikla pre MySQL 5.7 a s MySQL 8 máva ťažkosti (viac rezervovaných slov, predvolené hodnoty pri stĺpcoch JSON).

Vytvorenie databázy#

1. V zákazníckom účte otvorte Moje služby, kliknite na server a prejdite na záložku Databázy.
2. Do poľa Názov databázy napíšte názov, napríklad fivem. Povolené sú písmená, číslice a podčiarkovník.
3. Do poľa Povolený prístup z napíšte % (predvolená hodnota).
4. Kliknite na Vytvoriť databázu.

Pri databáze uvidíte tieto údaje:

• Nové heslo vygeneruje nové heslo. Staré prestane fungovať, takže ho musíte zmeniť aj v server.cfg.
• Počet databáz je obmedzený podľa balíka, stav vidíte ako Využito X z Y.
• Keď sú Server, Používateľ alebo Povolený prístup z zakryté šrafovaným pruhom, je zapnutý režim streamu. Kliknite hore na Zobraziť údaje, alebo hodnotu skopírujte ikonou vedľa nej.

Inštalácia oxmysql#

Ak ste server nasadili receptom txAdminu pre framework, oxmysql už máte a túto časť preskočte.

1. Stiahnite najnovšie vydanie z GitHubu oxmysql (otvorí sa v novom okne) (súbor oxmysql.zip, nie zdrojový kód).
2. Archív rozbaľte. Vznikne priečinok oxmysql so súborom fxmanifest.lua a podpriečinkami dist, lib, web a logger.
3. Nahrajte celý priečinok oxmysql do resources na serveri (podpriečinky vytvorte tlačidlom Nový priečinok, postup v návode FiveM resources).

Connection string#

oxmysql číta prihlasovacie údaje z premennej mysql_connection_string v server.cfg. Dá sa zapísať dvoma spôsobmi:

set mysql_connection_string "mysql://<UZIVATEL>:<HESLO>@<IP_DATABAZE>:<PORT>/<NAZEV_DATABAZE>"

set mysql_connection_string "user=<UZIVATEL>;password=<HESLO>;host=<IP_DATABAZE>;port=<PORT>;database=<NAZEV_DATABAZE>"

Použite iba jeden z riadkov. Pre heslo zo záložky Databázy je správna voľba prvý (URI) tvar, pretože si poradí so všetkými znakmi, ktoré sa v ňom objavujú (časť „Špeciálne znaky v hesle“). Za hodnoty v špicatých zátvorkách dosaďte údaje zo záložky Databázy, bez zátvoriek:

• set – premenná zostane iba na serveri. Nikdy nepoužívajte setr ani sets, heslo by sa poslalo hráčom alebo zverejnilo.
• mysql:// – označuje prvý (URI) tvar. Druhý tvar sú dvojice kľúč=hodnota oddelené bodkočiarkou.

Špeciálne znaky v hesle#

oxmysql reťazec nijako nedekóduje, takže zápis typu %40 namiesto @ nefunguje. Heslo vložte presne tak, ako je. Autori oxmysql všeobecne radia vyhnúť sa v hesle znakom ; , / ? : @ & = + $ #, prípadne prepnúť na druhý tvar zápisu. Podľa toho, ako oxmysql reťazec skutočne delí, platí:

Heslá, ktoré vytvára záložka Databázy, obsahujú okrem písmen a číslic iba znaky, s ktorými si URI tvar poradí (napríklad @, =, +, !, .). Preto pri nich používajte URI tvar a heslo neupravujte.

Kam riadok dať#

Riadok so set mysql_connection_string musí byť v server.cfg pred riadkom ensure oxmysql a oxmysql musí štartovať pred všetkými skriptmi, ktoré databázu používajú:

set mysql_connection_string "mysql://<UZIVATEL>:<HESLO>@<IP_DATABAZE>:3306/<NAZEV_DATABAZE>"

ensure oxmysql
ensure ox_lib
ensure es_extended

Import SQL v HeidiSQL#

Skripty často obsahujú súbor .sql, ktorý vytvorí potrebné tabuľky. Import cez HeidiSQL:

1. Stiahnite a nainštalujte HeidiSQL (otvorí sa v novom okne).

2. Spustite ho. V okne Session manager kliknite vľavo dole na New.

3. Vyplňte záložku Settings:

   Pole	Čo zadať
   Network type	MariaDB or MySQL (TCP/IP)
   Hostname / IP	IP adresa z poľa Server (časť pred dvojbodkou)
   User	Používateľ zo záložky Databázy
   Password	Heslo zo záložky Databázy
   Port	Port z poľa Server (časť za dvojbodkou), zvyčajne 3306
   Databases	Názov databázy (voliteľné, HeidiSQL potom ukáže iba ju)

4. Kliknite na Open. Vľavo uvidíte svoju databázu.

5. Kliknite na databázu, aby bola vybraná (aktívna).

6. V menu zvoľte File › Run SQL file… a vyberte súbor .sql.

7. Pri voľbe Encoding zvoľte UTF-8 a potvrďte.

   HeidiSQL príkazy rovno vykoná. Po dokončení stlačte F5 a v databáze uvidíte nové tabuľky.

Keď sa HeidiSQL nepripojí, skontrolujte, že Povolený prístup z je % (alebo vaša verejná IP adresa).

Ladenie dopytov#

Záloha databázy#

Záložka Zálohy zálohuje iba súbory servera. Databázu zálohujte zvlášť:

1. V HeidiSQL kliknite pravým tlačidlom na databázu a zvoľte Export database as SQL.
2. Zaškrtnite tabuľky (všetky), pri Data nechajte Insert.
3. Pri Output zvoľte Single .sql file, vyberte súbor a kliknite na Export.

Zálohu robte pred aktualizáciou frameworku, pred inštaláciou veľkého skriptu a pravidelne (napríklad raz týždenne). Obnova je import súboru postupom „Import SQL v HeidiSQL“.

Overenie#

Po reštarte servera nájdete v konzole riadok:

[<VERZE_DATABAZE>] Database server connection established!

V hranatých zátvorkách je verzia databázového servera (napríklad s označením MariaDB). Potom už frameworky hlásia načítanie bez chýb databázy.

Keď niečo nefunguje#

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

Nesprávny používateľ alebo heslo. Skopírujte ich znova zo záložky Databázy. Skontrolujte, že heslo nemáte v bodkočiarkovom tvare so znakom = (použite URI tvar, tabuľka vyššie), a že ste ho nijako nekódovali (%40 namiesto @). Pomôže aj Nové heslo.

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

Nesprávna adresa alebo port. Do connection stringu patrí IP adresa a port z poľa Server, nie localhost.

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

Databáza s týmto názvom neexistuje. Odpíšte Názov databázy presne zo zoznamu.

mysql_connection_string structure was invalid#

Reťazec v URI tvare sa nedá rozobrať. Skontrolujte, že začína mysql:// a obsahuje @, a že heslo nemá znaky /, ? alebo #.

Table '….users' doesn't exist (alebo iná tabuľka)#

Chýbajú tabuľky skriptu alebo frameworku. Naimportujte jeho súbor .sql.

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

Nová tabuľka má inú znakovú sadu (collation) než existujúce. Na koniec príkazov CREATE TABLE v súbore .sql doplňte DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci a import zopakujte.

Po obnove zálohy chýbajú dáta hráčov#

Zálohy v záložke Zálohy obsahujú iba súbory servera, databázu nie. Obnova zálohy preto databázu nevráti. Dáta z databázy obnovíte z vlastného exportu .sql.

Ďalšie zdroje#

• oxmysql: dokumentácia (otvorí sa v novom okne)
• oxmysql na GitHube (otvorí sa v novom okne)
• HeidiSQL: pomocník (otvorí sa v novom okne)