ACLClouds
ACLClouds

Come collegare un database MySQL a un server FiveM con oxmysql?

Creare il database nel pannello, installare oxmysql, scrivere mysql_connection_string in server.cfg, importare l’SQL di ESX o QBCore e correggere gli

oxmysql è la risorsa che collega un server FiveM o RedM a un database MySQL o MariaDB. ESX Legacy, QBCore e Qbox ne dipendono: senza connessione al database, il framework non si avvia. Su ACLClouds il database è ospitato su un server MariaDB separato ed è incluso nell’offerta: 1 database con Dev, 2 con City, 3 con Empire.

Procedura passo passo

  1. Crea il database

    In «Database», fai clic su «Nuovo database», dagli un nome breve come esx o qbcore e lascia vuoto «Connessioni da» per autorizzare il server di gioco e il tuo PC. Il pannello aggiunge un prefisso al nome: il database si chiama per esempio s12345_esx.

  2. Raccogli identificatori

    Apri il database nell’elenco: il pannello mostra l’«Endpoint» (host e porta), il «Nome utente», la «Password» e una stringa di connessione JDBC. L’host è l’indirizzo del server di database, mai localhost né 127.0.0.1.

  3. Installare oxmysql

    Scarica oxmysql.zip dall’ultima versione pubblicata nella pagina Releases del repository GitHub overextended/oxmysql, non il codice sorgente: solo l’archivio pubblicato contiene i file compilati. Estrailo in resources/[standalone]/oxmysql con «File». Le ricette ESX e QBCore di txAdmin lo installano già.

  4. Scrivere la connessione in server.cfg

    Aggiungi set mysql_connection_string con utente, password, host, porta e nome del database, poi ensure oxmysql prima del framework e di tutte le risorse che usano il database.

  5. Importare le tabelle

    I framework e molti script forniscono un file .sql. Importalo dal tuo PC con HeidiSQL, DBeaver o il client mariadb, usando le credenziali del pannello. Una ricetta txAdmin crea da sola le sue tabelle.

  6. Riavvia e controlla la console

    All’avvio, oxmysql indica nella console di essere connesso al database, con la versione di MariaDB. Un errore indica quasi sempre la causa: host, password o nome del database.

Connessione in server.cfg (formato URL)

set mysql_connection_string "mysql://u12345_AbCdEf:PASSWORD@HOST:3306/s12345_esx?charset=utf8mb4"

ensure oxmysql
ensure es_extended

Altro formato accettato da oxmysql

set mysql_connection_string "host=HOST;port=3306;user=u12345_AbCdEf;password=PASSWORD;database=s12345_esx"

Opzioni utili di oxmysql

set mysql_slow_query_warning 150
set mysql_ui true

Importare ed esportare da un PC

mariadb -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx < es_extended.sql
mariadb-dump -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx > backup.sql

Prima di iniziare

I database sono inclusi nelle offerte FiveM a pagamento, nel limite indicato in alto in «Database». Ogni database ha il proprio utente e i propri permessi. Tutti gli script di uno stesso server condividono di solito lo stesso database.

  • Arresta il server prima di modificare server.cfg.
  • Con txAdmin, modifica il server.cfg della ricetta, nella cartella txData, e non quello nella radice.
  • Non avviare mysql-async o ghmattimysql contemporaneamente: oxmysql fornisce le loro funzioni agli script più vecchi.

Caratteri speciali nella password

Nel formato URL, i caratteri @, :, /, #, ? e % della password rompono la stringa. Codificali (@ diventa %40), usa il formato key=value oppure riprendi la stringa JDBC del pannello, dove la password è già codificata, togliendo il prefisso jdbc:.

Il pulsante di rotazione della password ne genera una nuova: aggiorna subito server.cfg, altrimenti oxmysql non si connette più all’avvio successivo.

Fare il backup del database

I backup del pannello copiano i file del server, non il database. Esportalo regolarmente con mariadb-dump o con l’esportazione di HeidiSQL, soprattutto prima di ogni aggiornamento del framework, e conserva una copia fuori dal server.

Errori comuni e soluzioni

oxmysql scrive la causa dell’errore nella console all’avvio del server.

  • ECONNREFUSED o ETIMEDOUT: host o porta sbagliati. Ricopia l’«Endpoint»; localhost non funziona, il database non è nel container del gioco.
  • ER_ACCESS_DENIED_ERROR: utente o password sbagliati, spesso per un carattere speciale non codificato, oppure un valore di «Connessioni da» che esclude il server di gioco.
  • ER_BAD_DB_ERROR: nome del database sconosciuto. Indica il nome completo con il prefisso, per esempio s12345_esx.
  • ER_NO_SUCH_TABLE: il database è vuoto o incompleto. Importa il file .sql del framework o dello script interessato.
  • No such export su oxmysql al caricamento di uno script: oxmysql parte troppo tardi. Metti ensure oxmysql prima del framework.

Verifica rapida

  • La console mostra la connessione di oxmysql al database, senza errori.
  • ensure oxmysql è posizionato prima del framework.
  • Le tabelle del framework compaiono in HeidiSQL o DBeaver.
  • Un’esportazione .sql recente è conservata fuori dal server.

Domande frequenti

Bisogna installare MySQL sul server FiveM?

No. Il database è ospitato su un server MariaDB separato, incluso nell’offerta: lo crei in «Database» e oxmysql vi si connette via rete. MariaDB è compatibile con MySQL per ESX, QBCore e Qbox.

Come vedere e modificare le tabelle?

Connettiti dal tuo PC con HeidiSQL o DBeaver, usando host, porta, utente e password indicati nel pannello. Fai un’esportazione prima di qualsiasi modifica a mano.

Si può usare un database esterno?

Sì. oxmysql si connette a qualsiasi server MySQL o MariaDB raggiungibile dal server di gioco: indica host e credenziali in mysql_connection_string. Un database vicino al server di gioco risponde più in fretta, il che conta per gli script che lo interrogano spesso.

La console parla di query lente, cosa fare?

oxmysql segnala le query più lunghe di mysql_slow_query_warning (200 ms per impostazione predefinita) e indica la risorsa responsabile. Aggiungi un indice sulla colonna che filtra o sostituisci lo script: una risorsa che interroga il database in loop rallenta tutto il server.