Skip to content

0.1.0 — Initial release

Choose a tag to compare

@iseeyoucopy iseeyoucopy released this 23 Sep 17:14

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.exec and DB.raw calls with positional parameters.
  • Coroutine-based waiting: database calls yield the current coroutine while other server work continues, without requiring .await syntax.
  • Transactions using DB.transaction(function(tx) ... end), with all tx.* calls sharing the connection that began the transaction. Return true to commit; false or 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_diagnostics console command.

Installation

Requires an FXServer artifact with Node 22 and an existing MySQL/MariaDB database and database user.

  1. Place the resource in resources/[feather]/feather-mysql, keeping that folder name.

  2. Run npm ci --omit=dev --ignore-scripts inside the resource directory.

  3. 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
  4. 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.