Repository navigation
0.1.0 — Initial release
Initial release of Feather MySQL, a standalone MySQL/MariaDB resource for FiveM and RedM. It provides asynchronous database access through a plain Lua API, with no Feather framework dependency.
Features
- Native
DB.query,DB.one,DB.value,DB.insert,DB.execandDB.rawcalls with positional parameters. - Coroutine-based waiting: database calls yield the current coroutine while other server work continues, without requiring
.awaitsyntax. - Transactions using
DB.transaction(function(tx) ... end), with alltx.*calls sharing the connection that began the transaction. Returntrueto commit;falseor no return value requests rollback. - Bounded connection pooling, request deadlines, session reset before reuse and best-effort cancellation.
- Structured errors with write outcomes and rollback confirmation. Optional bounded deadlock and lock-wait retries require confirmed transaction rollback; provider stops cancel pending transaction retries.
- Readiness checks, health monitoring, configurable logging and the
feather_mysql_diagnosticsconsole command.
Installation
Requires an FXServer artifact with Node 22 and an existing MySQL/MariaDB database and database user.
-
Place the resource in
resources/[feather]/feather-mysql, keeping that folder name. -
Run
npm ci --omit=dev --ignore-scriptsinside the resource directory. -
Configure the connection before starting resources:
set mysql_connection_string "mysql://user:password@127.0.0.1:3306/database?charset=utf8mb4" ensure feather-mysql ensure your-resource -
Add the dependency and server import to each consumer's
fxmanifest.lua:dependency 'feather-mysql' server_scripts { '@feather-mysql/lib/DB.lua', 'server.lua', }
Run database calls in a yieldable coroutine, such as CreateThread:
CreateThread(function()
local ok, result = pcall(DB.value, 'SELECT ? AS message', 'Feather MySQL is ready')
print(result)
end)See the README and usage guide for configuration, error handling and transaction examples.
Validation and limits
The release commit passed the Node test suites, 65 Lua tests, 32 isolated MariaDB integration scenarios, the local benchmark and whitespace checks.
Live Cfx startup/restart behavior, FiveM, MySQL 8 and TLS still require deployment validation. Transaction rollback guarantees require transactional tables such as InnoDB; avoid implicit-commit statements inside callbacks. Cancellation is best effort, and an unknown write outcome must not be blindly retried.
Licensed under GPL v3.