oxmysql

oxmysql

MySQL テーブルを通じた FiveM のサーバー側 MySQL/MariaDB アクセス機能です（mysql-async および ghmattimysql の代替）。

有効化の条件

ユーザーが FiveM リソース内のデータベースコードを記述または編集する場合に、このスキルを読み込みます。対象には SELECT／INSERT／UPDATE／DELETE、アップサート、トランザクション、MySQL.*、exports.oxmysql、mysql-async からの移行が含まれます。

厳守事項

• サーバー側専用です。他のサーバースクリプトより前に、fxmanifest.lua に server_script '@oxmysql/lib/MySQL.lua' を追加してください。
• mysql-async 互換レイヤーの MySQL.Sync.* と MySQL.Async.* は利用できません。MySQL.query、MySQL.scalar、MySQL.single、MySQL.insert、MySQL.update、MySQL.prepare、MySQL.transaction に置き換えてください。それぞれに .await 版があります。
• @named プレースホルダーは非推奨です。値の配列と位置指定の ? を使ってください。prepare が受け付けるのは ?（および列名用の ??）のみです。
• ユーザー入力を SQL に連結しないでください。すべての値をプレースホルダー経由で渡してください。
• すべての関数は (query, params, callback) を受け取ります。コールバックを入れ子にする代わりに .await を使って処理を待機してください。
• 複数の書き込みをまとめて成功または失敗させる必要がある場合は transaction を使ってください。失敗が発生するとロールバックされます。
• query／prepare の正規化済み結果の形式では不十分な場合に限り、rawExecute を使ってください。
• 互換性を重視する場合は、MySQL 8 より MariaDB を優先してください。

判断基準

必要な結果	呼び出し	戻り値
複数の行	MySQL.query.await(sql, params)	行の配列
1 行	MySQL.single.await(sql, params)	行または nil
1 つの値（COUNT、1 列）	MySQL.scalar.await(sql, params)	値または nil
挿入	MySQL.insert.await(sql, params)	挿入 ID
更新／削除件数	MySQL.update.await(sql, params)	影響を受けた行数
ホットパス、繰り返し実行するステートメント	MySQL.prepare.await(sql, params)	行／値
複数のステートメントをアトミックに実行	MySQL.transaction.await({ { query, values }, ... })	成功を示すブール値
生の未正規化結果	MySQL.rawExecute.await(sql, params)	生の結果

実行手順

1. マニフェストの行を確認し、リソースより前に oxmysql が起動することを確かめます。
2. 判断基準から、必要な結果の形式に合った関数を選びます。
3. バッククォートで識別子を囲み、すべての値に ? を使って SQL を記述します。
4. 複数の書き込みステートメントは transaction で囲みます。
5. 使用前に nil の結果（single、scalar）を処理します。

出力条件

位置指定プレースホルダーを使い、mysql-async の構文を使用しない、実行可能なサーバー側 Lua（または JS）を返します。MySQL.<fn>.await を使用してください。

参考資料

• rules/placeholders.md — ? プレースホルダー、非推奨の @named。
• rules/query.md — MySQL.query：行、または insertId／affectedRows。
• rules/single.md — MySQL.single：1 行、または nil。
• rules/scalar.md — MySQL.scalar：単一の値。
• rules/insert.md — MySQL.insert：挿入 ID を返します。
• rules/update.md — MySQL.update：影響を受けた行数を返します。
• rules/prepare.md — MySQL.prepare：プリペアドステートメント。
• rules/transaction.md — MySQL.transaction：複数のクエリをアトミックに実行します。
• rules/rawExecute.md — MySQL.rawExecute：生の結果。

上流のドキュメント：https://overextended.dev/oxmysql