Databáze pro FiveM: oxmysql, připojení a import SQL

Frameworky a většina skriptů ukládají postavy, peníze, auta a inventáře do databáze. FiveM k ní přistupuje přes resource oxmysql. Ukážeme, jak databázi vytvořit, správně připojit, naimportovat do ní SQL a zálohovat.

Proč oxmysql#

oxmysql je knihovna, přes kterou ostatní resources posílají dotazy do databáze MySQL nebo MariaDB. Nahrazuje starší mysql-async a ghmattimysql a umí jejich zápis, takže starší skripty fungují dál. Recepty txAdminu pro ESX, QBCore a Qbox ji instalují samy.

Autoři oxmysql doporučují databázi MariaDB. Většina skriptů FiveM vznikla pro MySQL 5.7 a s MySQL 8 mívá potíže (víc rezervovaných slov, výchozí hodnoty u sloupců JSON).

Vytvoření databáze#

1. V zákaznické zóně otevřete Moje služby, klikněte na server a přejděte na záložku Databáze.
2. Do pole Název databáze napište název, například fivem. Povolená jsou písmena, číslice a podtržítko.
3. Do pole Povolený přístup z napište % (výchozí hodnota).
4. Klikněte na Vytvořit databázi.

U databáze uvidíte tyto údaje:

• Nové heslo vygeneruje nové heslo. Staré přestane fungovat, takže ho musíte změnit i v server.cfg.
• Počet databází je omezený podle balíčku, stav vidíte jako Využito X z Y.
• Když jsou Server, Uživatel nebo Povolený přístup z zakryté šrafovaným pruhem, je zapnutý režim streamu. Klikněte nahoře na Zobrazit údaje, nebo hodnotu zkopírujte ikonou vedle ní.

Instalace oxmysql#

Pokud jste server nasadili receptem txAdminu pro framework, oxmysql už máte a tuto část přeskočte.

1. Stáhněte nejnovější vydání z GitHubu oxmysql (otevře se v novém okně) (soubor oxmysql.zip, ne zdrojový kód).
2. Archiv rozbalte. Vznikne složka oxmysql se souborem fxmanifest.lua a podsložkami dist, lib, web a logger.
3. Nahrajte celou složku oxmysql do resources na serveru (podsložky vytvořte tlačítkem Nová složka, postup v návodu FiveM resources).

Connection string#

oxmysql čte přihlašovací údaje z proměnné mysql_connection_string v server.cfg. Jde ji zapsat dvěma způsoby:

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žijte jen jeden z řádků. Pro heslo ze záložky Databáze je správná volba první (URI) tvar, protože si poradí se všemi znaky, které se v něm objevují (část „Speciální znaky v hesle“). Za hodnoty ve špičatých závorkách dosaďte údaje ze záložky Databáze, bez závorek:

• set – proměnná zůstane jen na serveru. Nikdy nepoužívejte setr ani sets, heslo by se poslalo hráčům nebo zveřejnilo.
• mysql:// – označuje první (URI) tvar. Druhý tvar jsou dvojice klíč=hodnota oddělené středníkem.

Speciální znaky v hesle#

oxmysql řetězec nijak nedekóduje, takže zápis typu %40 místo @ nefunguje. Heslo vložte přesně tak, jak je. Autoři oxmysql obecně radí vyhnout se v hesle znakům ; , / ? : @ & = + $ #, případně přepnout na druhý tvar zápisu. Podle toho, jak oxmysql řetězec skutečně dělí, platí:

Hesla, která vytváří záložka Databáze, obsahují kromě písmen a číslic jen znaky, se kterými si URI tvar poradí (například @, =, +, !, .). Proto u nich používejte URI tvar a heslo neupravujte.

Kam řádek dát#

Řádek s set mysql_connection_string musí být v server.cfg před řádkem ensure oxmysql a oxmysql musí startovat před všemi skripty, které databázi 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í soubor .sql, který vytvoří potřebné tabulky. Import přes HeidiSQL:

1. Stáhněte a nainstalujte HeidiSQL (otevře se v novém okně).

2. Spusťte ho. V okně Session manager klikněte vlevo dole na New.

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

   Pole	Co zadat
   Network type	MariaDB or MySQL (TCP/IP)
   Hostname / IP	IP adresa z pole Server (část před dvojtečkou)
   User	Uživatel ze záložky Databáze
   Password	Heslo ze záložky Databáze
   Port	Port z pole Server (část za dvojtečkou), obvykle 3306
   Databases	Název databáze (volitelné, HeidiSQL pak ukáže jen ji)

4. Klikněte na Open. Vlevo uvidíte svou databázi.

5. Klikněte na databázi, aby byla vybraná (aktivní).

6. V menu zvolte File › Run SQL file… a vyberte soubor .sql.

7. U volby Encoding zvolte UTF-8 a potvrďte.

   HeidiSQL příkazy rovnou provede. Po dokončení stiskněte F5 a v databázi uvidíte nové tabulky.

Když se HeidiSQL nepřipojí, zkontrolujte, že Povolený přístup z je % (nebo vaše veřejná IP adresa).

Ladění dotazů#

Záloha databáze#

Záložka Zálohy zálohuje jen soubory serveru. Databázi zálohujte zvlášť:

1. V HeidiSQL klikněte pravým tlačítkem na databázi a zvolte Export database as SQL.
2. Zaškrtněte tabulky (všechny), u Data nechte Insert.
3. U Output zvolte Single .sql file, vyberte soubor a klikněte na Export.

Zálohu dělejte před aktualizací frameworku, před instalací velkého skriptu a pravidelně (například jednou týdně). Obnova je import souboru postupem „Import SQL v HeidiSQL“.

Ověření#

Po restartu serveru najdete v konzoli řádek:

[<VERZE_DATABAZE>] Database server connection established!

V hranatých závorkách je verze databázového serveru (například s označením MariaDB). Pak už frameworky hlásí načtení bez chyb databáze.

Když něco nefunguje#

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

Špatný uživatel nebo heslo. Zkopírujte je znovu ze záložky Databáze. Zkontrolujte, že heslo nemáte ve středníkovém tvaru se znakem = (použijte URI tvar, tabulka výše), a že jste ho nijak nekódovali (%40 místo @). Pomůže i Nové heslo.

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

Špatná adresa nebo port. Do connection stringu patří IP adresa a port z pole Server, ne localhost.

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

Databáze s tímto názvem neexistuje. Opište Název databáze přesně ze seznamu.

mysql_connection_string structure was invalid#

Řetězec v URI tvaru nejde rozebrat. Zkontrolujte, že začíná mysql:// a obsahuje @, a že heslo nemá znaky /, ? nebo #.

Table '….users' doesn't exist (nebo jiná tabulka)#

Chybí tabulky skriptu nebo frameworku. Naimportujte jeho soubor .sql.

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

Nová tabulka má jinou znakovou sadu (collation) než stávající. Na konec příkazů CREATE TABLE v souboru .sql doplňte DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci a import zopakujte.

Po obnově zálohy chybí data hráčů#

Zálohy v záložce Zálohy obsahují jen soubory serveru, databázi ne. Obnova zálohy proto databázi nevrátí. Data z databáze obnovíte z vlastního exportu .sql.

Další zdroje#

• oxmysql: dokumentace (otevře se v novém okně)
• oxmysql na GitHubu (otevře se v novém okně)
• HeidiSQL: nápověda (otevře se v novém okně)