IT

Server di gioco

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.

6 min di lettura, aggiornato il 18 novembre 2026

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 fivem e l'utente fivem creati 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:

Terminale
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:

Terminale
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)"
exit

Annota 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:

Terminale
sudo /usr/local/sbin/backup-fivem.sh
sudo apt install -y unzip
sudo systemctl stop fivem.service
sudo -iu fivem

Nella sessione fivem, scarica l'ultima versione e sostituisci la vecchia. Adatta TARGET se il percorso rilevato in precedenza è diverso:

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

La 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:

Testo
set mysql_connection_string "mysql://fivem:PASSWORD_GENERATA@127.0.0.1/fivem?charset=utf8mb4"

ensure oxmysql

Metti 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:

Testo
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:

Terminale
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:

Terminale
sudo systemctl start fivem.service
sudo grep -a 'Database server connection established' /home/fivem/fxserver.log

Se hai solo modificato server.cfg, riavvia piuttosto il server da txAdmin. Verifica infine che la risorsa sia attiva:

Terminale
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:

Testo
oxmysql_debug add es_extended
oxmysql_debug remove es_extended

Non attivare mysql_debug in modo permanente: le query mostrate possono contenere dati dei giocatori e riempiono i log.

Tornare alla versione precedente

Terminale
sudo systemctl stop fivem.service
sudo -iu fivem
Terminale
BASE=/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"
exit
Terminale
sudo systemctl start fivem.service

In 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:

Terminale
sudo grep -a -A2 'Unable to establish a connection' /home/fivem/fxserver.log

Unable 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, sostituisci localhost con 127.0.0.1 nella 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 comando mariadb.
  • 'root'@'localhost' (using password: NO): oxmysql non ha letto la tua stringa e usa il suo valore di ripiego. Verifica che la riga sia scritta set mysql_connection_string, che non sia commentata e che si trovi prima di ensure oxmysql.
  • 'fivem'@'127.0.0.1': MariaDB non collega questo indirizzo all'account localhost, cosa che accade in particolare con l'opzione skip_name_resolve. Crea un account per questo indirizzo in sudo mariadb:
SQL
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:

SQL
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:

SQL
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:

Terminale
sudo mariadb fivem < /percorso/del/file.sql

took 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.