Move a resource from mysql-async to oxmysql by changing its driver setup and reviewing each query’s parameters, return value and error handling. A driver migration does not require rewriting your database schema, and it does not guarantee faster gameplay.
Prepare a recoverable test
Back up the database and matching resources, then work on an isolated copy. Inventory every resource using mysql-async and check whether your framework already requires oxmysql. Record the installed driver release. Review the oxmysql source and installation instructions for that release before switching drivers.
Load the connection before the driver
In the active server.cfg, keep the existing private mysql_connection_string setting above ensure oxmysql. Start dependent resources afterwards. Do not publish connection credentials in support logs. Remove the old driver startup only after every dependent resource has been accounted for.
In each Lua resource that uses the MySQL global, load the library before its server scripts:
server_scripts {
'@oxmysql/lib/MySQL.lua',
'server/*.lua'
}
dependency 'oxmysql'Choose the result you need
Use MySQL.query.await for a set of rows, MySQL.single.await for one row, MySQL.scalar.await for one value, MySQL.insert.await for an insert ID and MySQL.update.await for affected rows. Check the documented return for your query; an empty result is different from an error.
This server-side example tests a parameterized round trip without touching a gameplay table. Run it from a resource after oxmysql has started:
CreateThread(function()
local ok, value = pcall(function()
return MySQL.scalar.await('SELECT ?', { 'connection-ok' })
end)
if ok and value == 'connection-ok' then
print('Database parameter check passed.')
else
print('Database parameter check failed; inspect the server log privately.')
end
end)Review every converted call
Replace interpolated user values with positional ? placeholders and an ordered parameter table. Table and column identifiers require a fixed allowlist; value placeholders cannot select arbitrary SQL identifiers.
Await changes control flow: use the result after the await returns, handle missing rows and exceptions, and check whether the player is still connected before acting. A successful SQL write does not automatically update a framework’s in-memory player state.
Keep transactions on one connection
Use the driver’s documented transaction API for grouped SQL work. Separate START TRANSACTION, query and COMMIT calls through a connection pool do not guarantee that all statements use the same connection.
A transaction succeeding means its SQL statements did not fail. An UPDATE affecting zero rows can still be valid SQL. Payment and inventory logic must enforce business conditions explicitly; do not copy a generic balance-transfer snippet into a live economy.
Verify correctness before speed
- Search for remaining mysql-async imports, exports and callback patterns. Verify each caller receives the shape it expects.
- Test login, character creation, saving, reconnect, inventory, garages and relevant job actions using known records. Test unavailable database and rejected input.
- Compare expected row changes and persisted balances. Keep schema/index changes separate from this driver migration.
- For performance, measure the same gameplay action and workload before and after. Investigate slow queries with their execution plans; add indexes only after inspecting the actual schema and query.
Release and rollback
Schedule a maintenance window, deploy the matched driver/resource set and run the same checks. Keep the old set private for rollback. Restore a database backup only if needed for changed data or schema, and account for all writes since that backup. Converting text back to a smaller character set is not a safe generic rollback.