Einleitung: Zielgruppe

Zielgruppe: FiveM-Server-Besitzer, Skripter, Maintainer Ziel: mysql-async sicher durch oxmysql ersetzen, Queries beschleunigen und SQL-Nutzung modernisieren.

Dieser Guide ist Teil unseres vollständigen FiveM-Frameworks-Guides, in dem wir ESX, QBCore und QBOX ausführlich vergleichen und dir bei der Wahl des richtigen Frameworks helfen.

Weitere Lektüre:

• FiveM Server-Optimierung: Das definitive Playbook 2026 — https://vertexmods.com/blog/how-to-optimize-fivem-server-performance
• Adapter-Muster: ESX↔QBCore↔QBOX Exports, Events & Player Models — https://vertexmods.com/blog/adapter-patterns

---

TL;DR

• oxmysql verwenden: Prepared Statements, Promise/Await-API, bessere Diagnosen, starke Performance.
• Minimale Code-Änderungen: @param → ? (positional) oder :name (benannte) Parameter tauschen; MySQL.Async.*-Aufrufe durch MySQL.*/exports.oxmysql:* ersetzen.
• Die SQL-„UP"-Skripte unten ausführen (Charset/Index-Korrekturen) und den Rollback bereithalten.
• Mit dem Micro-Benchmark-Harness am Ende verifizieren, um Gewinne auf deiner Hardware zu bestätigen.

---

1) Vorflug-Sicherheitscheckliste

1. Vollständiges Backup: mysqldump --single-transaction yourdb > backup.sql.
2. Staging-Umgebung, die das Produktionsschema + Datensubset spiegelt.
3. Artifact & Deps: Aktuelle FXServer-Build, neuestes oxmysql.
4. Wartungsfenster für den Prod-Wechsel (normalerweise < 5 Minuten).
5. Health-Probes bereit: /players, Login-Flow, Economy-Ops, Garage-Ops, Inventory-Ops, Ban-Checks.

2) oxmysql installieren & einbinden

2.1 server.cfg

# mysql-async deaktivieren default_prio 500

ensure mysql-async # ← auskommentieren oder entfernen

oxmysql starten

default_prio 50

```lua
```lua
ensure oxmysql

Connection-String für oxmysql

```lua
```lua
set mysql_connection_string "mysql://user:[email protected]:3306/yourdb?charset=utf8mb4"

Optionale Diagnosen

```lua
```lua
set mysql_slow_query_warning 200   # Queries langsamer als 200ms protokollieren
set mysql_debug false              # true für ausführliches Logging im Staging

mysql-async während der Staging-Phase deaktiviert aber im resources-Ordner verfügbar lassen (für schnellen Rollback).

3) API-Mapping: mysql‑async → oxmysql

mysql-async (Legacy):

mysql-async (Legacy):

• Async: MySQL.Async.fetchAll, MySQL.Async.fetchScalar, MySQL.Async.execute
• Sync: MySQL.Sync.fetchAll, MySQL.Sync.fetchScalar, MySQL.Sync.execute
• Parameter: @param-Style-Tabellen wie { ['@identifier']=identifier }

oxmysql (modern):

• Callback-Style via Export: exports.oxmysql:query|scalar|single|insert|update(sql, params, cb)
• Promise/Await via Global: MySQL.query|scalar|single|insert|update.await(sql, params) und Nicht-Await-Callbacks ohne .await
• Parameter: positional ? via Array, oder benannt :name via Objekt

3.1 Häufige Ersetzungen

SELECT viele

```lua
```lua
-- 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 }
)

SELECT einzelne Zeile

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

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

SELECT scalar (z. B. count, id)

```lua
```lua
-- mysql-async

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

INSERT (insertId erhalten)

```lua
```lua
-- mysql-async (execute)

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

UPDATE/DELETE (affectedRows)

```lua
```lua
-- mysql-async (execute)

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

Transaktionen (manuell)

```lua
```lua
-- oxmysql manuelle Transaktion
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

Einige Frameworks stellen Wrapper bereit (z. B. ox_lib)

Einige Frameworks stellen Wrapper bereit (z. B. ox_lib), die MySQL.ready, .transaction usw. hinzufügen. Die obigen Aufrufe sind ohne zusätzliche Wrapper sicher.

4) Prepared-Statements-Spickzettel

Param-Stile

• mysql‑async (Legacy): @name-Platzhalter mit einer Tabelle: { ['@name']=value }
• oxmysql (positional): ?-Platzhalter mit einem Array: { value1, value2 }
• oxmysql (benannt): :name-Platzhalter mit einem Objekt: { name = value }

Beispiele

```lua
```lua
-- Benannte Parameter (empfohlen für Lesbarkeit)
local row = MySQL.single.await(
  'SELECT * FROM users WHERE identifier = :id',
  { id = identifier }
)

-- IN (...) Liste
-- Platzhalter dynamisch aufbauen und ein flaches Array übergeben
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-Felder (MySQL 5.7+/MariaDB 10.2+)
local name = MySQL.scalar.await('SELECT JSON_UNQUOTE(JSON_EXTRACT(data, "$.name")) FROM players WHERE citizenid = ?', { cid })

Tun

• Prepared Statements überall verwenden (niemals Benutzereingaben per String-Verkettung einbauen).
• Benannte Parameter für Klarheit bei komplexen Statements bevorzugen.
• LIMIT 1 hinzufügen, wenn eine einzelne Entität gelesen wird.

Vermeiden

• Wildcard SELECT * in Hot Paths (nur benötigte Spalten projizieren).
• N+1-Queries pro Zeile; mit IN (...) batchen.

5) Datenbank-„UP"-Migrationsskripte (Ausführungsbereit)

Die Blöcke wählen, die zum Framework (ESX/QBCore) und Server (MySQL 8+ oder MariaDB 10.4+) passen. Zuerst im Staging ausführen.

5.1 Charset & Collation normalisieren (UTF‑8 überall)

(A) MySQL 8+ — yourdb einmalig ersetzen

```sql
```sql
-- Datenbank-Standard auf utf8mb4 setzen (Emoji-sicher)
ALTER DATABASE \`yourdb\` CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci;

-- Gängige Tabellen konvertieren (Liste bei Bedarf erweitern)
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+ — gleiche Anweisungen sind gültig.

(B) MariaDB 10.4+ — gleiche Anweisungen sind gültig.

Weitere Hot-Tabellen (Inventory, Billing, Phone, Society, Jobs) nach Vorhandensein auf dem Server hinzufügen.

5.2 ESX-Indizes (sichere Performance-Gewinne)

MySQL 8+

```sql
```sql
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`);

```sql
```sql
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+

```lua
```lua
-- Zuerst löschen für Idempotenz, wo IF NOT EXISTS nicht verfügbar ist
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 QBCore/QBOX-Indizes

MySQL 8+

```sql
```sql
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`);

```sql
```sql
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+

```lua
```lua
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 Optional: ox_inventory (falls installiert)

```sql
```sql
ALTER TABLE \`ox_inventory\`

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

```sql
```sql
ALTER TABLE \`ox_inventory_items\`

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

Tabellennamen anpassen, wenn das Schema abweicht

Tabellennamen anpassen, wenn das Schema abweicht (manche Setups verwenden inventories / items).

6) Rollback-Plan (Null Panik)

6.1 Code-Rollback

1. Ressource-Änderungen rückgängig machen (einen legacy-mysql-async-Branch bereithalten).
2. In server.cfg tauschen: # ensure oxmysql ensure mysql-async
3. FXServer oder betroffene Ressourcen in Abhängigkeitsreihenfolge neu starten.

6.2 SQL-Rollback

• Wenn nur Indizes hinzugefügt wurden: diese löschen (siehe die MariaDB-Blöcke oben — DROP INDEX IF EXISTS verwenden).
• Wenn Charset/Collation geändert wurde und rückgängig gemacht werden muss, DB und Tabellen zurücksetzen:

```sql
```sql
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;

Wenn möglich aus backup.sql wiederherstellen, anstatt massenhafte Charset-Rücksetzungen vorzunehmen.

7) End-to-End-Migrationsverfahren (Skriptierbar)

1. Deploys einfrieren, DB sichern.
2. Abschnitt 5 „UP"-SQL im Staging anwenden → verifizieren → Prod.
3. Code-Refactoring committen: Aufrufe ersetzen (Abschnitt 3) + Parameterstile (Abschnitt 4).
4. Deployen, ensure oxmysql, Server neu starten.
5. Smoke-Tests ausführen (Login, Gehaltsschecks, Inventory, Fahrzeug spawn/despawn, Bans, Society-Geld, Job-Duty-Toggles).
6. Protokolle 15–30 Minuten überwachen (mysql_slow_query_warning hilft); verpasste Parameter oder Schema-Diskrepanzen beheben.

8) Micro-Benchmarks (Eigene Zahlen mitbringen)

Eine kleine Ressource, die du einfügen kannst, um Hot-Path-Queries auf deiner Hardware und deinem Datensatz zu vergleichen.

fxmanifest.lua

fx_version 'cerulean'

```lua
```lua
game 'gta5'

server_script 'bench.lua'

bench.lua

```lua
```lua
local COUNT = 2000  -- für deinen Server anpassen

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))))

```lua
```lua
end

-- Hot Path 1: Eigentümer-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: Batch-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 mit 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)

Ausführen

Ausführen

1. Die Ressource in einen Ordner legen (z. B. ox-bench/), ensure ox-bench zur server.cfg hinzufügen.
2. Server-Konsole beobachten; Ergebnisse werden als Zeilen ausgegeben wie: [bench] SELECT single: 134.21 ms.
3. Für einen Vorher/Nachher-Vergleich einmal mit mysql-async ausführen (Aufrufe ggf. anpassen), dann mit oxmysql.

Worauf zu achten ist

• Niedrigere Gesamt-ms pro Abschnitt nach der Migration.
• Niedrigere P95/P99-Latenz bei Gameplay-Aktionen, die an Queries gebunden sind.
• Weniger Slow-Query-Warnungen über eine Stunde Live-Play.

9) Fehlerbehebung

F: Ich erhalte „no such export: query/single/…". A: oxmysql startet nicht früh genug. Sicherstellen, dass ensure oxmysql über den Ressourcen steht, die es verwenden.

F: Parameter-Fehler oder leere Ergebnisse. A: Wahrscheinlich wurden @param-Platzhalter beibehalten. Durch ? oder :name ersetzen und entsprechend ein Array/Objekt übergeben.

F: Deadlocks oder partielle Schreibvorgänge. A: Mehrstufige Geldbeträge/Transfers in einer Transaktion einwickeln (siehe Abschnitt 3), Indizes aus Abschnitt 5 hinzufügen.

F: JSON-Pfad gibt NULL zurück. A: Prüfen, ob die Engine JSON-Funktionen unterstützt (MySQL ≥5.7/MariaDB ≥10.2) und ob der Spaltentyp JSON ist (nicht LONGTEXT).

F: Nach der Migration langsamer. A: Fehlende Indizes prüfen, Query mit EXPLAIN analysieren, nur benötigte Spalten projizieren und das Server-Optimierungs-Playbook prüfen.

10) Code-Review-Checkliste (Kopieren/Einfügen)

• Kein per String-Verkettung erstelltes SQL; alle Queries parametrisiert.
• .single/.scalar mit LIMIT 1 verwenden, wenn nur eine Zeile/ein Wert benötigt wird.
• IN (...)-Reads für Kollektionen batchen.
• Transaktionen um mehrstufige Geld-/Inventory-Ops herum.
• Index vorhanden für jede heiße WHERE/JOIN-Spalte.
• SELECT * in Hot Paths vermeiden.
• Slow Queries protokollieren; wöchentlich die Top-Übeltäter verfolgen.

---

Interne Links

• FiveM Server-Optimierung: Das definitive Playbook 2026 — https://vertexmods.com/blog/how-to-optimize-fivem-server-performance
• Adapter-Muster: ESX↔QBCore↔QBOX Exports, Events & Player Models — https://vertexmods.com/blog/adapter-patterns

---

Credits: Gepflegt von vertexmods.com

Credits Gepflegt von vertexmods.com. Beiträge willkommen (Diffs zusätzlicher sicherer Indizes oder Wrapper-Helfer einsenden).