Come installare e configurare oxmysql su FiveM
Installa o aggiorna oxmysql sul tuo server FiveM Linux, scrivi una stringa di connessione MariaDB corretta, verifica la connessione e correggi gli errori più comuni.
In questa pagina
oxmysql è la risorsa che collega il tuo server FiveM al suo database. ESX Legacy, QBCore e molti script ne dipendono. Questa guida ti spiega come installarla o aggiornarla, scrivere la stringa di connessione, verificare che funzioni e risolvere gli errori frequenti.
Prerequisiti
- Un server installato con la guida Creare un server FiveM
- MariaDB installata, con il database
fiveme l'utentefivemcreati in quella guida - Un accesso a txAdmin, per CFG Editor e Live Console
Verificare cosa è già installato
Le recipe ESX Legacy e QBCore installano già oxmysql. Individua prima la cartella del tuo server, il cui nome termina con .base:
sudo find /home/fivem/txData -maxdepth 1 -type d -name '*.base'Se compaiono più cartelle, quella giusta è quella di Server Data Folder, in Settings, scheda FXServer. Apri poi una sessione fivem e cerca la risorsa, sostituendo NOME_CARTELLA:
sudo -iu fivem
BASE=/home/fivem/txData/NOME_CARTELLA.base
find "$BASE/resources" -type d -name oxmysql
grep -E "^version" "$(find "$BASE/resources" -type f -path '*/oxmysql/fxmanifest.lua' | head -n 1)"
exitAnnota il percorso mostrato. Con le recipe ESX Legacy e QBCore, si tratta di resources/[standalone]/oxmysql. Se find non restituisce alcun percorso, oxmysql non è installato e grep segnala un errore senza conseguenze.
Installare o aggiornare oxmysql
Fai il backup del server, installa unzip, poi arresta il servizio:
sudo /usr/local/sbin/backup-fivem.sh
sudo apt install -y unzip
sudo systemctl stop fivem.service
sudo -iu fivemNella sessione fivem, scarica l'ultima versione e sostituisci la vecchia. Adatta TARGET se il percorso rilevato in precedenza è diverso:
BASE=/home/fivem/txData/NOME_CARTELLA.base
TARGET="$BASE/resources/[standalone]/oxmysql"
TMP=$(mktemp -d "$HOME/oxmysql.XXXXXX")
curl -fL -o "$TMP/oxmysql.zip" https://github.com/overextended/oxmysql/releases/latest/download/oxmysql.zip
unzip -q "$TMP/oxmysql.zip" -d "$TMP"
grep -E "^version" "$TMP/oxmysql/fxmanifest.lua"
rm -rf "$HOME/oxmysql.previous"
[ -d "$TARGET" ] && mv "$TARGET" "$HOME/oxmysql.previous"
mkdir -p "$(dirname "$TARGET")"
mv "$TMP/oxmysql" "$TARGET"
rm -rf "$TMP"
ls "$TARGET"
exitLa cartella deve contenere fxmanifest.lua, dist e lib. La vecchia versione resta in /home/fivem/oxmysql.previous, fuori da resources perché FXServer non la carichi.
Configurare server.cfg
In txAdmin, apri CFG Editor. La stringa di connessione deve essere definita prima dell'avvio delle risorse:
set mysql_connection_string "mysql://fivem:PASSWORD_GENERATA@127.0.0.1/fivem?charset=utf8mb4"
ensure oxmysqlMetti ensure oxmysql prima del framework e delle risorse che usano il database. La recipe QBCore non ha questa riga: avvia l'intera cartella [standalone], e qb-core lancia oxmysql come dipendenza. In questo caso non serve aggiungerla.
I due formati della stringa
oxmysql accetta due scritture equivalenti:
set mysql_connection_string "mysql://fivem:PASSWORD_GENERATA@127.0.0.1:3306/fivem?charset=utf8mb4"
set mysql_connection_string "user=fivem;password=PASSWORD_GENERATA;host=127.0.0.1;port=3306;database=fivem;charset=utf8mb4"Tieni una sola di queste righe.
| Elemento | Valore | Nota |
|---|---|---|
| Utente | fivem |
Non usare root |
| Password | Valore generato | Solo lettere e cifre, con openssl rand -hex 16 |
| Host | 127.0.0.1 |
Evita che localhost venga risolto in IPv6 mentre MariaDB è in ascolto in IPv4 |
| Porta | 3306 |
Facoltativa se è la porta predefinita |
| Database | fivem |
Oppure fivem_rp se ne hai creato un altro |
charset |
utf8mb4 |
Conserva gli accenti e le emoji |
La documentazione di oxmysql sconsiglia questi caratteri nei valori: ; , / ? : @ & = + $ #. La cosa più semplice è non inserirne nella password.
Verificare la connessione
Prova prima le credenziali direttamente con MariaDB. Il comando chiede la password:
mariadb -h 127.0.0.1 -P 3306 -u fivem -p fivem -e "SELECT VERSION();"Se la versione viene mostrata, avvia il server e cerca il messaggio di successo di oxmysql:
sudo systemctl start fivem.service
sudo grep -a 'Database server connection established' /home/fivem/fxserver.logSe hai solo modificato server.cfg, riavvia piuttosto il server da txAdmin. Verifica infine che la risorsa sia attiva:
curl -fsS http://127.0.0.1:30120/info.json | grep -o '"oxmysql"'Impostazioni utili
Queste variabili si mettono in server.cfg, prima di ensure oxmysql, sempre con set:
| Variabile | Effetto | Valore predefinito |
|---|---|---|
mysql_slow_query_warning |
Soglia, in millisecondi, oltre la quale una query viene segnalata come lenta | 200 |
mysql_debug |
Mostra le query nella console | false |
mysql_ui |
Attiva l'interfaccia di monitoraggio in gioco, aperta con il comando /mysql |
false |
L'interfaccia /mysql richiede inoltre il permesso command.mysql: consulta Gestire i permessi ACE su FiveM. La documentazione di oxmysql la riserva allo sviluppo o ai server con pochi giocatori.
Per monitorare una sola risorsa senza riavviare, digita in Live Console, poi rimuovila al termine dell'analisi:
oxmysql_debug add es_extended
oxmysql_debug remove es_extendedNon attivare mysql_debug in modo permanente: le query mostrate possono contenere dati dei giocatori e riempiono i log.
Tornare alla versione precedente
sudo systemctl stop fivem.service
sudo -iu fivemBASE=/home/fivem/txData/NOME_CARTELLA.base
TARGET="$BASE/resources/[standalone]/oxmysql"
rm -rf "$HOME/oxmysql.failed"
mv "$TARGET" "$HOME/oxmysql.failed"
mv "$HOME/oxmysql.previous" "$TARGET"
exitsudo systemctl start fivem.serviceIn caso di problemi
Quando la connessione fallisce, oxmysql mostra Unable to establish a connection to the database, seguito da un codice tra parentesi. Trovalo con:
sudo grep -a -A2 'Unable to establish a connection' /home/fivem/fxserver.logUnable to establish a connection to the database (ECONNREFUSED)
MariaDB non risponde all'indirizzo indicato.
- Verifica il servizio con
sudo systemctl status mariadb. - Verifica la porta in ascolto con
sudo ss -ltnp | grep ':3306'. - Se l'errore menziona
::1, sostituiscilocalhostcon127.0.0.1nella stringa.
ER_ACCESS_DENIED_ERROR
Leggi bene l'account citato nel messaggio:
'fivem'@'localhost' (using password: YES): la password non è corretta. Confrontala con quella provata dal comandomariadb.'root'@'localhost' (using password: NO): oxmysql non ha letto la tua stringa e usa il suo valore di ripiego. Verifica che la riga sia scrittaset mysql_connection_string, che non sia commentata e che si trovi prima diensure oxmysql.'fivem'@'127.0.0.1': MariaDB non collega questo indirizzo all'accountlocalhost, cosa che accade in particolare con l'opzioneskip_name_resolve. Crea un account per questo indirizzo insudo mariadb:
CREATE USER 'fivem'@'127.0.0.1' IDENTIFIED BY 'PASSWORD_GENERATA';
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'127.0.0.1';
FLUSH PRIVILEGES;ER_BAD_DB_ERROR
Il messaggio Unknown database indica che il database non esiste. Confronta il nome nella stringa con l'elenco restituito da sudo mariadb -e "SHOW DATABASES;".
ER_DBACCESS_DENIED_ERROR
L'utente esiste ma non ha permessi su questo database. Concedili in sudo mariadb:
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;La password contiene caratteri speciali
Un : o un / nella password spezza la stringa nel punto sbagliato, e l'errore segnala allora un host o un utente inatteso. Genera una nuova password con openssl rand -hex 16, applicala in sudo mariadb, poi aggiorna server.cfg:
ALTER USER 'fivem'@'localhost' IDENTIFIED BY 'PASSWORD_GENERATA';Could not find dependency oxmysql for resource
La risorsa citata ha bisogno di oxmysql, che non viene trovato. Verifica che la cartella contenga direttamente fxmanifest.lua, e non una sottocartella oxmysql/oxmysql. Digita poi refresh e ensure oxmysql in Live Console.
Resource 'oxmysql' can't run
Se la riga successiva indica server needs to be 12913 or higher, segui Aggiornare gli artifact di FXServer, oppure torna nel frattempo alla versione precedente di oxmysql.
Table 'fivem.xxx' doesn't exist
Una risorsa si aspetta una tabella che non è stata creata. Importa il file .sql fornito con questa risorsa, dopo un backup:
sudo mariadb fivem < /percorso/del/file.sqltook 350.0000ms to execute a query
Questo messaggio segnala una query lenta, con il nome della risorsa che l'ha lanciata. È normale all'avvio e può anche derivare da un rallentamento generale del server. Se ricompare spesso in gioco per la stessa risorsa, segui Diagnosticare crash e rallentamenti di un server FiveM.
Conflitto con mysql-async o ghmattimysql
oxmysql sostituisce queste due risorse e risponde al posto loro. Rimuovi la loro riga ensure ed elimina la loro cartella, dopo un backup.