Guía de consultas oxmysql: MySQL.query.await, single, scalar, insert

Necesitas leer o escribir en la base de datos desde un script de servidor, y los ejemplos en línea mezclan llamadas antiguas de MySQL.Async, callbacks y exports.oxmysql en diferentes estilos. Este artículo muestra las funciones MySQL actuales, cuál usar para cada resultado, y cómo mantener las consultas seguras y económicas.

#Cargar el objeto MySQL

Para usar el MySQL global, importa el wrapper Lua de oxmysql en el manifiesto del recurso, antes de tus propios scripts de servidor:

-- fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

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

dependency 'oxmysql'

Sin esa línea, MySQL es nil y obtendrás attempt to index a nil value (global 'MySQL'). El archivo solo funciona en el servidor. Si oxmysql en sí no puede conectarse, consulta errores de conexión de oxmysql.

#Las funciones y lo que devuelven

Cada función tiene una forma .await que espera el resultado y lo devuelve. Debe ejecutarse en un thread o un manejador de eventos, que es donde ya se ejecuta la mayoría de tu código.

-- all rows
local rows = MySQL.query.await('SELECT identifier, name FROM users WHERE job = ?', { 'police' })
for _, row in ipairs(rows) do
    print(row.identifier, row.name)
end

-- one row
local user = MySQL.single.await('SELECT * FROM users WHERE identifier = ?', { identifier })
if not user then return end

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

-- insert
local id = MySQL.insert.await('INSERT INTO my_logs (identifier, action) VALUES (?, ?)', { identifier, 'login' })

-- update or delete
local changed = MySQL.update.await('UPDATE users SET job = ? WHERE identifier = ?', { 'unemployed', identifier })

Verifica los resultados. Una consulta single o scalar que no encuentra nada devuelve nil, y usarla sin una comprobación es la fuente de muchos errores attempt to index a nil value.

#Parámetros con ?

Siempre pasa valores a través de placeholders ? y el segundo argumento, una tabla en el mismo orden:

-- safe
MySQL.query.await('SELECT * FROM users WHERE name = ?', { name })

-- dangerous: SQL injection
MySQL.query.await('SELECT * FROM users WHERE name = "' .. name .. '"')

Con la versión insegura, un nombre como x" OR 1=1 -- reescribe tu consulta. Con placeholders, oxmysql envía los valores por separado, así que nunca pueden convertirse en SQL. Esto se aplica a cada valor que viene de un jugador, un argumento de evento o un comando.

Cuidado: los placeholders solo funcionan para valores, no para nombres de tablas o columnas. Si un nombre de columna viene de fuera, compruébalo contra una lista fija de nombres permitidos en lugar de pegarlo.

#Estilo de callback

Las mismas funciones aceptan un callback si no quieres esperar. Esto es útil fuera de un thread:

MySQL.query('SELECT * FROM users WHERE job = ?', { 'police' }, function(rows)
    print(#rows)
end)

.await se lee mejor y está bien dentro de eventos. Usa el estilo de callback cuando quieras que el código que sigue siga ejecutándose sin esperar la base de datos.

#MySQL.prepare

MySQL.prepare ejecuta una sentencia preparada, que la base de datos puede reutilizar cuando ejecutas la misma consulta una y otra vez. Usa los mismos parámetros ?:

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

Lo que devuelve depende del resultado: una sola fila regresa como una tabla, y una consulta con una columna y una fila puede regresar como un valor. Para código donde la forma del resultado importa, single y scalar son más predecibles, así que recurre a prepare cuando tienes una consulta frecuente que se ejecuta a menudo.

#No consultes en un bucle

Cada consulta es un viaje de ida y vuelta a la base de datos. Un bucle que ejecuta una consulta por elemento se ralentiza rápidamente, y bloquea el thread mientras espera:

-- one query per player
for _, id in ipairs(ids) do
    local row = MySQL.single.await('SELECT * FROM users WHERE id = ?', { id })
end

Obtén todo en una única consulta, luego itera sobre el resultado en Lua:

local rows = MySQL.query.await('SELECT * FROM users WHERE job = ?', { 'police' })

Para muchos inserts, construye una sentencia con varias filas, o ejecútalos juntos en una transacción. También evita consultar en cada tick o cada frame: lee un valor una vez y mantenlo en una tabla Lua. Si una consulta es lenta, añade un índice en la columna que buscas. Las consultas lentas aparecen como advertencias de bloqueo de thread de servidor.

#Transacciones

Cuando varios escritos deben tener éxito o fallar juntos, como sacar dinero de una fila y darlo a otra, usa una transacción:

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

if not ok then
    print('transfer failed, nothing was changed')
end

Si alguna sentencia falla, la base de datos deshace todas ellas. Devuelve true cuando todo ha funcionado.

#Las tablas deben existir primero

Una consulta contra una tabla que no existe da Table 'x' doesn't exist. Crea la tabla con un archivo SQL cuando instales el script, o al inicio del recurso con MySQL.query.await('CREATE TABLE IF NOT EXISTS …'). Más en la tabla SQL no existe.

#Lista de verificación