oxmysql user manual

oxmysql is a MySQL resource for FiveM designed to be faster and more modern than the old mysql-async.

Why use oxmysql?

• 2-3x faster mysql-async
• Supports async/await pattern.
• Promise-based API
• Prepared statements Prevent SQL injection
• Supports transactions

Installation

ensure oxmysql

In fxmanifest.lua:

server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server.lua'
}

API Methods

MySQL.query — general query

-- Async (callback)
MySQL.query('SELECT * FROM users WHERE identifier = ?', 
    { identifier }, 
    function(result)
        print(json.encode(result))
    end
)

-- Sync (stop waiting)
local result = MySQL.query.await('SELECT * FROM users WHERE identifier = ?', 
    { identifier }
)

MySQL.single — retrieve a single row

local user = MySQL.single.await(
    'SELECT * FROM users WHERE identifier = ? LIMIT 1',
    { identifier }
)

if user then
    print('Found:', user.name)
end

MySQL.scalar — Retrieve a single value.

local count = MySQL.scalar.await(
    'SELECT COUNT(*) FROM users WHERE job = ?',
    { 'police' }
)
print('Police count:', count)

MySQL.insert — INSERT and get back the ID.

local insertId = MySQL.insert.await(
    'INSERT INTO custom_data (identifier, data) VALUES (?, ?)',
    { identifier, json.encode(data) }
)
print('New ID:', insertId)

MySQL.update — UPDATE and get rows affected

local affected = MySQL.update.await(
    'UPDATE users SET money = money + ? WHERE identifier = ?',
    { amount, identifier }
)

if affected > 0 then
    print('Updated successfully')
end

MySQL.transaction — multiple queries in a single transaction

local success = MySQL.transaction.await({
    { query = 'UPDATE accounts SET balance = balance - ? WHERE identifier = ?', values = { amount, fromId } },
    { query = 'UPDATE accounts SET balance = balance + ? WHERE identifier = ?', values = { amount, toId } }
})

if success then
    print('Transfer complete')
else
    print('Transfer failed — rolled back')
end

Real-World Pattern

-- Create a new character
local function CreateCharacter(identifier, name, dob)
    -- Check if it already exists.
    local existing = MySQL.single.await(
        'SELECT id FROM characters WHERE identifier = ?',
        { identifier }
    )
    
    if existing then
        return false, 'Character already exists'
    end
    
    local id = MySQL.insert.await(
        'INSERT INTO characters (identifier, name, dob, created_at) VALUES (?, ?, ?, NOW())',
        { identifier, name, dob }
    )
    
    return true, id
end

Performance Tips

1. Use .await only when necessary — the callback is faster in some cases.
2. Index columns always used in WHERE
3. Use MySQL.scalar instead of MySQL.query when a single value is required.
4. Transaction for operations that must be atomic

Summary

oxmysql is a worthwhile upgrade from the mysql-async API that is cleaner, faster, and has better error handling. You should move to it if you haven't already.