Da mysql-async a oxmysql: Migrazione Sicura e Ottimizzazione delle Query…

Pubblico: Proprietari, programmatori e manutentori del server FiveM
Obiettivo: Sostituire mysql-async con oxmysql in modo sicuro, velocizzare le query e modernizzare l'utilizzo di SQL.

Leggi anche:

• Ottimizzazione del server FiveM: il manuale definitivo per il 2025 — https://fivemx.com/how-to-optimize-fivem-server-performance/
• Modelli di adattatore: esportazioni ESX↔QBCore↔QBOX, eventi e modelli di player — https://fivemx.com/adapter-patterns/

---

In breve

• Utilizzo oxmysql: istruzioni preparate, API promise/await, diagnostica migliore, prestazioni elevate.
• Modifiche minime al codice: scambio @param → ? (posizionale) o :name (nominati) parametri; sostituisci MySQL.Async.* chiamate con MySQL.*/exports.oxmysql:*.
• Eseguire gli script SQL "UP" di seguito (correzioni di charset/indice) e mantenere il rollback utile.
• Verificare con il cablaggio micro-benchmark alla fine per confermare le vittorie sul tuo hardware.

---

1) Lista di controllo di sicurezza pre-volo

1. Backup completo: mysqldump --single-transaction yourdb > backup.sql.
2. Ambiente di messa in scena schema di produzione speculare + sottoinsieme di dati.
3. Artefatto e dipendenze: Build FXServer attuale, ultima oxmysql.
4. Finestra di inattività per il cambio di produzione (solitamente < 5 minuti).
5. Sonde sanitarie pronto: /players, flusso di accesso, operazioni economiche, operazioni di garage, operazioni di inventario, controlli di ban.

2) Installazione e cablaggio oxmysql

2.1 server.cfg

# Stop using mysql-async
default_prio 500
# ensure mysql-async # ← comment out or remove

# Start oxmysql
default_prio 50
ensure oxmysql

# Connection string consumed by oxmysql
set mysql_connection_string "mysql://user:pass@127.0.0.1:3306/yourdb?charset=utf8mb4"

# Optional diagnostics
set mysql_slow_query_warning 200 # log queries slower than 200ms
set mysql_debug false # true for verbose logging during staging

Mantenere mysql-async disabilitato ma disponibile nella cartella delle risorse durante la fase di staging (per un rapido rollback).

3) Mappatura API: mysql‑async → oxmysql

mysql-async (eredità):

• Asincrono: MySQL.Async.fetchAll, MySQL.Async.fetchScalar, MySQL.Async.execute
• Sincronizzazione: MySQL.Sync.fetchAll, MySQL.Sync.fetchScalar, MySQL.Sync.execute
• Parametri: @param tabelle di stile come { ['@identifier']=identifier }

oxmysql (moderno):

• Stile di richiamata tramite esportare: exports.oxmysql:query|scalar|single|insert|update(sql, params, cb)
• Prometti/attendi tramite globale: MySQL.query|scalar|single|insert|update.await(sql, params) e callback non in attesa senza .await
• Parametri: posizionale ? tramite array, o nominato :name tramite oggetto

3.1 Sostituzioni comuni

SELEZIONA molti

-- mysql-async
MySQL.Async.fetchAll(
 'SELECT * FROM users WHERE identifier = @id',
 { ['@id'] = identifier },
 function(rows) ... end
)

-- oxmysql (callback via export)
exports.oxmysql:query(
 'SELECT * FROM users WHERE identifier = ?',
 { identifier },
 function(rows) ... end
)

-- oxmysql (await)
local rows = MySQL.query.await(
 'SELECT * FROM users WHERE identifier = ?',
 { identifier }
)

SELEZIONA riga singola

-- mysql-async (fetchAll + rows[1])

-- oxmysql
local row = MySQL.single.await(
 'SELECT * FROM users WHERE identifier = ?',
 { identifier }
)

SELEZIONA scalare (ad esempio, conteggio, id)

-- mysql-async

-- oxmysql
local count = MySQL.scalar.await(
 'SELECT COUNT(*) FROM owned_vehicles WHERE owner = ?',
 { owner }
)

INSERIRE (ottieni insertId)

-- mysql-async (execute)

-- oxmysql
local insertId = MySQL.insert.await(
 'INSERT INTO notes (owner, text) VALUES (?, ?)',
 { cid, text }
)

AGGIORNA/ELIMINA (righe interessate)

-- mysql-async (execute)

-- oxmysql
local changed = MySQL.update.await(
 'UPDATE users SET job = ?, job_grade = ? WHERE identifier = ?',
 { job, grade, identifier }
)

Transazioni (manuale)

-- oxmysql manual transaction
MySQL.query.await('START TRANSACTION')
local ok = true

local r1 = MySQL.update.await('UPDATE users SET bank = bank - ? WHERE identifier = ? AND bank >= ?', { amount, fromId, amount })
local r2 = MySQL.update.await('UPDATE users SET bank = bank + ? WHERE identifier = ?', { amount, toId })

if r1 == 1 and r2 == 1 then
 MySQL.query.await('COMMIT')
else
 MySQL.query.await('ROLLBACK')
end

Alcuni framework espongono wrapper (ad esempio, ox_lib) che aggiungono MySQL.ready, .transaction, ecc. Le chiamate sopra sono sicure senza wrapper aggiuntivi.

4) Foglio riassuntivo delle dichiarazioni preparate

Stili dei parametri

• mysql‑async (legacy): @name segnaposto con una tabella: { ['@name']=value }
• oxmysql (posizionale): ? segnaposto con un vettore: { value1, value2 }
• oxmysql (denominato): :name segnaposto con un oggetto: { name = value }

Esempi

-- Named params (recommended for readability)
local row = MySQL.single.await(
 'SELECT * FROM users WHERE identifier = :id',
 { id = identifier }
)

-- IN (...) list
-- Build placeholders dynamically and pass a flat array
local ids = { 'cid1','cid2','cid3' }
local qs = ('?,' ):rep(#ids):sub(1,-2) -- "?, ?, ?"
local rows = MySQL.query.await('SELECT * FROM players WHERE citizenid IN ('..qs..')', ids)

-- JSON fields (MySQL 5.7+/MariaDB 10.2+)
local name = MySQL.scalar.await('SELECT JSON_UNQUOTE(JSON_EXTRACT(data, "$.name")) FROM players WHERE citizenid = ?', { cid })

Fare

• Utilizzo dichiarazioni preparate ovunque (non concatenare mai l'input dell'utente).
• Prefer parametri denominati per chiarezza in affermazioni complesse.
• Aggiungere LIMITE 1 quando si legge una singola entità.

Evitare

• Carattere jolly SELECT * nei percorsi attivi (colonne necessarie al progetto).
• Query N+1 per riga; batch con IN (...).

5) Script di migrazione del database "UP" (pronti per l'esecuzione)

Scegli i blocchi che corrispondono al tuo framework (ESX/QBCore) e al tuo server (MySQL 8+ o MariaDB 10.4+). Esegui prima in staging.

5.1 Normalizza set di caratteri e collazione (UTF‑8 ovunque)

(A) MySQL 8+ - sostituire yourdb una volta

-- Force database default to utf8mb4 (emoji‑safe)
ALTER DATABASE `yourdb` CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci;

-- Convert common tables (extend list as needed)
ALTER TABLE `users` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE `owned_vehicles` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE `players` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE `player_vehicles` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

(B) MariaDB 10.4+ — le stesse affermazioni sono valide.

Aggiungi altre tabelle hot (inventario, fatturazione, telefono, società, lavori) se presenti sul tuo server.

5.2 Indici ESX (vincitori di prestazioni sicure)

MySQL 8+

ALTER TABLE `users`
 ADD INDEX IF NOT EXISTS `idx_users_identifier` (`identifier`),
 ADD INDEX IF NOT EXISTS `idx_users_job` (`job`),
 ADD INDEX IF NOT EXISTS `idx_users_name` (`name`);

ALTER TABLE `owned_vehicles`
 ADD UNIQUE INDEX IF NOT EXISTS `ux_owned_vehicles_plate` (`plate`),
 ADD INDEX IF NOT EXISTS `idx_owned_vehicles_owner` (`owner`);

MariaDB 10.4+

-- Drop first to be idempotent where IF NOT EXISTS is unavailable
DROP INDEX IF EXISTS `idx_users_identifier` ON `users`;
DROP INDEX IF EXISTS `idx_users_job` ON `users`;
DROP INDEX IF EXISTS `idx_users_name` ON `users`;
CREATE INDEX `idx_users_identifier` ON `users` (`identifier`);
CREATE INDEX `idx_users_job` ON `users` (`job`);
CREATE INDEX `idx_users_name` ON `users` (`name`);

DROP INDEX IF EXISTS `ux_owned_vehicles_plate` ON `owned_vehicles`;
DROP INDEX IF EXISTS `idx_owned_vehicles_owner` ON `owned_vehicles`;
CREATE UNIQUE INDEX `ux_owned_vehicles_plate` ON `owned_vehicles` (`plate`);
CREATE INDEX `idx_owned_vehicles_owner` ON `owned_vehicles` (`owner`);

5.3 Indici QBCore/QBOX

MySQL 8+

ALTER TABLE `players`
 ADD UNIQUE INDEX IF NOT EXISTS `ux_players_citizenid` (`citizenid`),
 ADD INDEX IF NOT EXISTS `idx_players_license` (`license`),
 ADD INDEX IF NOT EXISTS `idx_players_steam` (`steam`),
 ADD INDEX IF NOT EXISTS `idx_players_last_name` (`lastname`);

ALTER TABLE `player_vehicles`
 ADD UNIQUE INDEX IF NOT EXISTS `ux_player_vehicles_plate` (`plate`),
 ADD INDEX IF NOT EXISTS `idx_player_vehicles_citizenid` (`citizenid`);

MariaDB 10.4+

DROP INDEX IF EXISTS `ux_players_citizenid` ON `players`;
DROP INDEX IF EXISTS `idx_players_license` ON `players`;
DROP INDEX IF EXISTS `idx_players_steam` ON `players`;
DROP INDEX IF EXISTS `idx_players_last_name` ON `players`;
CREATE UNIQUE INDEX `ux_players_citizenid` ON `players` (`citizenid`);
CREATE INDEX `idx_players_license` ON `players` (`license`);
CREATE INDEX `idx_players_steam` ON `players` (`steam`);
CREATE INDEX `idx_players_last_name` ON `players` (`lastname`);

DROP INDEX IF EXISTS `ux_player_vehicles_plate` ON `player_vehicles`;
DROP INDEX IF EXISTS `idx_player_vehicles_citizenid` ON `player_vehicles`;
CREATE UNIQUE INDEX `ux_player_vehicles_plate` ON `player_vehicles` (`plate`);
CREATE INDEX `idx_player_vehicles_citizenid` ON `player_vehicles` (`citizenid`);

5.4 Facoltativo: ox_inventory (se installato)

ALTER TABLE `ox_inventory`
 ADD INDEX IF NOT EXISTS `idx_inv_owner` (`owner`),
 ADD INDEX IF NOT EXISTS `idx_inv_type` (`type`);

ALTER TABLE `ox_inventory_items`
 ADD INDEX IF NOT EXISTS `idx_items_inv_owner_name` (`inventory`, `owner`, `name`);

Modifica i nomi delle tabelle se lo schema è diverso (alcune configurazioni utilizzano inventories / items).

6) Piano di rollback (Zero-Panic)

6.1 Rollback del codice

1. Annulla le modifiche alle risorse (mantieni un legacy-mysql-async ramo).
2. In server.cfg scambio: # ensure oxmysql ensure mysql-async
3. Riavviare FXServer o le risorse interessate in ordine di dipendenza.

6.2 Rollback SQL

• Se solo tu indici aggiunti: lasciarli cadere (vedi il MariaDB blocchi sopra — usa DROP INDEX IF EXISTS).
• Se tu set di caratteri/collazione modificati e bisogna annullare, ripristinare il DB e le tabelle:

ALTER DATABASE `yourdb` CHARACTER SET = utf8 COLLATE = utf8_general_ci;
ALTER TABLE `users` CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;
ALTER TABLE `owned_vehicles` CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;
ALTER TABLE `players` CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;
ALTER TABLE `player_vehicles` CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;

Preferisco ripristinare da backup.sql invece di inversioni di massa dei set di caratteri, quando possibile.

7) Procedura di migrazione end-to-end (programmabile)

1. Distribuzioni di congelamento, esegui il backup del DB.
2. Fare domanda a Sezione 5 “UP” SQL in fase di staging → verifica → prod.
3. Refactoring del codice commit: sostituzione delle chiamate (Sezione 3) + stili dei parametri (Sezione 4).
4. Distribuire, ensure oxmysql, riavviare il server.
5. Correre test del fumo (accesso, stipendi, inventario, comparsa/scomparsa dei veicoli, divieti, denaro della società, cambi di mansioni).
6. Osservare i registri per 15–30 minuti (mysql_slow_query_warning aiuta); risolvere eventuali parametri mancanti o incongruenze nello schema.

8) Micro-Benchmark (porta i tuoi numeri)

Una piccola risorsa a cui puoi accedere per confrontare le query hot-path su tuo hardware e set di dati.

fxmanifest.lua

fx_version 'cerulean'
game 'gta5'
server_script 'bench.lua'

bench.lua

local COUNT = 2000 -- adjust for your server

local function bench(name, fn)
 local t0 = os.clock()
 local ok, err = pcall(fn)
 local dt = (os.clock() - t0) * 1000.0
 print(('[bench] %s: %.2f ms %s'):format(name, dt, ok and '' or ('ERR: '..tostring(err))))
end

-- Hot path 1: ownership lookup
bench('SELECT single', function()
 for i=1,COUNT do
 local row = MySQL.single.await('SELECT owner FROM owned_vehicles WHERE plate = :p LIMIT 1', { p = ('TEST%04d'):format(i % 500) })
 end
end)

-- Hot path 2: batched fetch
bench('SELECT batch IN', function()
 local ids = {}
 for i=1,100 do ids[#ids+1] = ('cid%04d'):format(i) end
 local qs = ('?,' ):rep(#ids):sub(1,-2)
 local rows = MySQL.query.await('SELECT citizenid, firstname, lastname FROM players WHERE citizenid IN ('..qs..')', ids)
end)

-- Hot path 3: update with guard
bench('UPDATE guarded', function()
 for i=1,COUNT do
 local changed = MySQL.update.await('UPDATE users SET bank = bank + :d WHERE identifier = :id AND bank >= 0', { d = 1, id = ('lic:%04d'):format(i % 500) })
 end
end)

Come correre

1. Metti la risorsa in una cartella (ad esempio, ox-bench/), aggiungere ensure ox-bench A server.cfg.
2. Console del server di coda; i risultati vengono stampati come righe come: [bench] SELECT single: 134.21 ms.
3. Per un prima/dopo confronto, esegui una volta con mysql-async (regolare le chiamate se necessario), quindi con oxmysql.

Cosa cercare

• Riduzione del numero totale di ms per sezione dopo la migrazione.
• Minore latenza P95/P99 nelle azioni di gioco legate alle query.
• Meno avvisi di query lente dopo un'ora di riproduzione in diretta.

9) Risoluzione dei problemi

D: Ricevo il messaggio "nessuna esportazione: query/singola/...".
UN: oxmysql non è iniziato abbastanza presto. Assicurarsi ensure oxmysql è al di sopra delle risorse che lo utilizzano.

D: Errori nei parametri o risultati vuoti.
A: Probabilmente hai continuato @param segnaposto. Sostituisci con ? O :name e passare un array/oggetto di conseguenza.

D: Deadlock o scritture parziali.
A: Inserire saldi/trasferimenti multi-step in una transazione (vedere Sezione 3), aggiungere indici dalla Sezione 5.

D: Il percorso JSON restituisce NULL.
A: Verifica che il tuo motore supporti le funzioni JSON (MySQL ≥5.7/MariaDB ≥10.2) e che il tipo di colonna sia JSON (non LONGTEXT).

D: Lento dopo la migrazione.
A: Controlla gli indici mancanti, EXPLAIN la tua query, le colonne necessarie al progetto e rivedi il Server Optimization Playbook.

10) Lista di controllo per la revisione del codice (copia/incolla)

• Nessun SQL concatenato tramite stringhe; tutte le query sono parametrizzate.
• Utilizzo .single/.scalar con LIMIT 1 quando è richiesta solo una riga/valore.
• Lotto IN (...) letture per collezioni.
• Transazioni relative a operazioni di inventario/denaro in più fasi.
• Indice presente per ogni caldo WHERE/JOIN colonna.
• Evitare SELECT * nei percorsi caldi.
• Registra le query lente; monitora settimanalmente i principali trasgressori.

---

Link interni

• Ottimizzazione del server FiveM: il manuale definitivo per il 2025 — https://fivemx.com/how-to-optimize-fivem-server-performance/
• Modelli di adattatore: esportazioni ESX↔QBCore↔QBOX, eventi e modelli di player — https://fivemx.com/adapter-patterns/

---

Crediti
Gestito da fivemx.com. I contributi sono benvenuti (inviare differenze di indici sicuri aggiuntivi o wrapper helper).