oxmysql
Server-side MySQL/MariaDB access for FiveM through the MySQL table (replacement for mysql-async and ghmattimysql).
Activation Contract
Load this skill when the user writes or edits database code in a FiveM resource: SELECT/INSERT/UPDATE/DELETE, upserts, transactions, MySQL.*, exports.oxmysql, or migrating from mysql-async.
Hard Rules
- Server only. Add
server_script '@oxmysql/lib/MySQL.lua' to fxmanifest.lua above other server scripts.
MySQL.Sync.* and MySQL.Async.* (mysql-async compatibility layer) are NOT available. Replace them with MySQL.query, MySQL.scalar, MySQL.single, MySQL.insert, MySQL.update, MySQL.prepare, MySQL.transaction, each with a .await variant.@named placeholders are deprecated: use positional ? with an array of values. prepare accepts only ? (and ?? for column names).- Never concatenate user input into SQL; every value goes through a placeholder.
- Every function takes
(query, params, callback); use .await to yield instead of nesting callbacks.
- Use
transaction when several writes must succeed or fail together; it rolls back on any failure.
- Use
rawExecute only when the normalized result shape of query/prepare is insufficient.
- Prefer MariaDB over MySQL 8 for compatibility.
Decision Gates
| Need |
Call |
Returns |
| Many rows |
MySQL.query.await(sql, params) |
array of rows |
| One row |
MySQL.single.await(sql, params) |
row or nil |
| One value (COUNT, one column) |
MySQL.scalar.await(sql, params) |
value or nil |
| Insert |
MySQL.insert.await(sql, params) |
insert id |
| Update / delete count |
MySQL.update.await(sql, params) |
affected rows |
| Hot path, repeated statement |
MySQL.prepare.await(sql, params) |
rows / value |
| Several statements atomically |
MySQL.transaction.await({ { query, values }, ... }) |
success boolean |
| Raw, unnormalized result |
MySQL.rawExecute.await(sql, params) |
raw result |
Execution Steps
- Confirm the manifest line and that
oxmysql starts before the resource.
- Pick the function by result shape from Decision Gates.
- Write the SQL with backticked identifiers and
? for every value.
- Wrap multi-statement writes in
transaction.
- Handle nil results (
single, scalar) before use.
Output Contract
Return runnable server-side Lua (or JS) using MySQL.<fn>.await with positional placeholders and no mysql-async syntax.
References
- rules/placeholders.md —
? placeholders, deprecated @named.
- rules/query.md — MySQL.query: rows or insertId/affectedRows.
- rules/single.md — MySQL.single: one row or nil.
- rules/scalar.md — MySQL.scalar: single value.
- rules/insert.md — MySQL.insert: returns insert id.
- rules/update.md — MySQL.update: returns affected rows.
- rules/prepare.md — MySQL.prepare: prepared statements.
- rules/transaction.md — MySQL.transaction: atomic multi-query.
- rules/rawExecute.md — MySQL.rawExecute: raw result.
Upstream docs: https://overextended.dev/oxmysql
1---2name: oxmysql3description: Trigger: oxmysql, MySQL.query, MySQL.insert, MySQL.update, MySQL.single, MySQL.scalar, MySQL.prepare, MySQL.transaction, rawExecute, SQL, database, mysql-async. Write server-side SQL with oxmysql.4license: MIT5---67# oxmysql89Server-side MySQL/MariaDB access for FiveM through the `MySQL` table (replacement for mysql-async and ghmattimysql).1011## Activation Contract1213Load this skill when the user writes or edits database code in a FiveM resource: SELECT/INSERT/UPDATE/DELETE, upserts, transactions, `MySQL.*`, `exports.oxmysql`, or migrating from mysql-async.1415## Hard Rules1617- Server only. Add `server_script '@oxmysql/lib/MySQL.lua'` to `fxmanifest.lua` above other server scripts.18- `MySQL.Sync.*` and `MySQL.Async.*` (mysql-async compatibility layer) are NOT available. Replace them with `MySQL.query`, `MySQL.scalar`, `MySQL.single`, `MySQL.insert`, `MySQL.update`, `MySQL.prepare`, `MySQL.transaction`, each with a `.await` variant.19- `@named` placeholders are deprecated: use positional `?` with an array of values. `prepare` accepts only `?` (and `??` for column names).20- Never concatenate user input into SQL; every value goes through a placeholder.21- Every function takes `(query, params, callback)`; use `.await` to yield instead of nesting callbacks.22- Use `transaction` when several writes must succeed or fail together; it rolls back on any failure.23- Use `rawExecute` only when the normalized result shape of `query`/`prepare` is insufficient.24- Prefer MariaDB over MySQL 8 for compatibility.2526## Decision Gates2728| Need | Call | Returns |29|---|---|---|30| Many rows | `MySQL.query.await(sql, params)` | array of rows |31| One row | `MySQL.single.await(sql, params)` | row or nil |32| One value (COUNT, one column) | `MySQL.scalar.await(sql, params)` | value or nil |33| Insert | `MySQL.insert.await(sql, params)` | insert id |34| Update / delete count | `MySQL.update.await(sql, params)` | affected rows |35| Hot path, repeated statement | `MySQL.prepare.await(sql, params)` | rows / value |36| Several statements atomically | `MySQL.transaction.await({ { query, values }, ... })` | success boolean |37| Raw, unnormalized result | `MySQL.rawExecute.await(sql, params)` | raw result |3839## Execution Steps40411. Confirm the manifest line and that `oxmysql` starts before the resource.422. Pick the function by result shape from Decision Gates.433. Write the SQL with backticked identifiers and `?` for every value.444. Wrap multi-statement writes in `transaction`.455. Handle nil results (`single`, `scalar`) before use.4647## Output Contract4849Return runnable server-side Lua (or JS) using `MySQL.<fn>.await` with positional placeholders and no mysql-async syntax.5051## References5253- rules/placeholders.md — `?` placeholders, deprecated `@named`.54- rules/query.md — MySQL.query: rows or insertId/affectedRows.55- rules/single.md — MySQL.single: one row or nil.56- rules/scalar.md — MySQL.scalar: single value.57- rules/insert.md — MySQL.insert: returns insert id.58- rules/update.md — MySQL.update: returns affected rows.59- rules/prepare.md — MySQL.prepare: prepared statements.60- rules/transaction.md — MySQL.transaction: atomic multi-query.61- rules/rawExecute.md — MySQL.rawExecute: raw result.6263Upstream docs: https://overextended.dev/oxmysql
germanfndez