oxmysql

oxmysql

通过 MySQL 表在 FiveM 中进行服务端 MySQL/MariaDB 访问（替代 mysql-async 和 ghmattimysql）。

激活条件

当用户在 FiveM 资源中编写或修改数据库代码时加载此技能：SELECT/INSERT/UPDATE/DELETE、upsert、事务、MySQL.*、exports.oxmysql，或从 mysql-async 迁移。

硬性规则

• 仅限服务端。在 fxmanifest.lua 中，其他服务端脚本之前添加 server_script '@oxmysql/lib/MySQL.lua'。
• MySQL.Sync.* 和 MySQL.Async.*（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。
• 为保证兼容性，优先使用 MariaDB 而非 MySQL 8。

决策指南

需求	调用	返回值
多行	MySQL.query.await(sql, params)	行数组
单行	MySQL.single.await(sql, params)	行或 nil
单个值（COUNT、单列）	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）。

输出约定

返回可运行的服务端 Lua（或 JS），使用 MySQL.<fn>.await 和位置占位符，不使用 mysql-async 语法。

参考资料

• rules/placeholders.md — ? 占位符、已弃用的 @named。
• rules/query.md — MySQL.query：行或 insertId/affectedRows。
• rules/single.md — MySQL.single：单行或 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