Getting started

The fast path to a working install. For the full walkthrough - prerequisites, prebuilt vs source, troubleshooting - see Installation; for every setting, see Configuration.

1. Add the resource

Drop a release zip into resources/ as vSQL, or build from source:

cd resources
git clone https://github.com/valerisn/vSQL
cd vSQL && npm install && npm run build

TIP

dist/ is generated, not committed. Build once after cloning, or use a prebuilt release zip that already includes it.

2. Configure & start

set vsql_connection_string "mysql://root:password@localhost:3306/fivem"
ensure vSQL

Put ensure vSQL before any resource that queries the database.

3. First query

From JavaScript, call the exports directly - Promise or callback:

// Promise
const players = await exports.vSQL.query('SELECT * FROM players WHERE money > ?', [1000]);

// Callback
exports.vSQL.single('SELECT * FROM players WHERE id = ?', [1], (row) => {
  print(row?.name);
});

From Lua, load the wrapper in your fxmanifest.lua first:

dependency 'vSQL'
shared_script '@vSQL/lib/MySQL.lua'

local row = MySQL.single.await('SELECT * FROM players WHERE id = ?', { 1 })
print(row and row.name)

Where to next

• Recipes - copy-paste solutions for inserts, transactions, pagination, upserts, and more.
• Architecture - how a query flows through vSQL and what each module owns.
• Configuration - the full convar reference and per-call options.
• Compatibility - drop-in mode for oxmysql / ghmattimysql / mysql-async.

Console commands

vSQL registers a single vsql command with subcommands:

vsql              # profiler stats (queries, latency percentiles, busiest resources)
vsql top          # heaviest query shapes by total time
vsql resources    # per-resource query breakdown
vsql debug        # full diagnostics dump (password-redacted)
vsql cache clear  # empty the result cache
vsql migrate      # apply pending migrations (also :status, :rollback, :dry)