API reference

Every name below is reachable as exports.tDB:<name>, exports.oxmysql:<name>, exports['mysql-async']:<name> and exports.ghmattimysql:<name>.

Exports marked async return a promise: use the _async name, or Citizen.Await.

Readiness

A record or collection call made too early can still throw PocketBase client not ready yet. Wrap the first one:

exports.tDB:onReady(function()
    local players = exports.tDB:getFullList('players')
end)

oxmysql exports

Each base name is registered three times: name, name_async and nameSync. All three behave identically.

Accepted call shapes: (sql), (sql, params), (sql, callback), (sql, params, callback). With a callback the export returns nothing and invokes it; without one it returns a promise.

mysql-async aliases

Query cache

Off by default. When on, row queries are cached and any write through tDB clears the cache.

lib/MySQL.lua

Add server_script '@tDB/lib/MySQL.lua' to your fxmanifest.lua. Every entry has an .await form and a callable callback form, and waits for the database before dispatching, so a script querying during its own startup gets rows.

local rows = MySQL.query.await('SELECT * FROM players')
local id   = MySQL.insert.await('INSERT INTO logs (msg) VALUES (?)', { 'joined' })

MySQL.ready(function() print('database up') end)

Legacy namespaces: MySQL.Sync.execute (affected rows), MySQL.Sync.insert, MySQL.Sync.fetchAll, MySQL.Sync.fetchSingle, MySQL.Sync.fetchScalar, MySQL.Sync.transaction, MySQL.Sync.prepare, and the matching MySQL.Async.* callback forms. Also MySQL.ready, MySQL.isReady, MySQL.awaitConnection and MySQL.store.

Records

Pass SQL as the first argument to update or delete and the call goes down the oxmysql path instead.

Build every filter with filter(), so values are bound rather than interpolated into the string:

local f    = exports.tDB:filter('score > {:min} && banned = {:banned}', { min = 100, banned = false })
local top  = exports.tDB:getFullList('players', { filter = f })
local one  = exports.tDB:getFirstListItem('players', f)

Collections

exports.tDB:createCollection({
    name = 'players',
    type = 'base',
    fields = {
        { name = 'username', type = 'text', required = true },
        { name = 'score',    type = 'number' },
        { name = 'banned',   type = 'bool' },
    },
})

Realtime

Subscribe, then handle the event tDB raises. The name is pocketbase:<collection>:<topic> for a collection and pocketbase:topic:<topic> for a custom one:

exports.tDB:subscribe('bans', '*')

AddEventHandler('pocketbase:bans:*', function(data)
    if data.action == 'create' then print(data.record.id) end
end)

Transactions and batches

runTransaction runs inside a real database transaction and needs no setting. The batch* exports are PocketBase's batch API and must be enabled in Admin → Settings → Batch API first.

Raw SQL

The same database the oxmysql exports use, with {:name} placeholders and no MySQL translation — write SQLite here. All async.

Integers arrive as numbers and NULL arrives as nil, not an empty string.

local row = exports.tDB:sqlSingle('SELECT * FROM players WHERE id = {:id}', { id = 1 })

exports.tDB:sqlTransaction({
    { sql = 'UPDATE accounts SET balance = balance - {:n} WHERE id = {:a}', params = { n = 100, a = 'a' } },
    { sql = 'UPDATE accounts SET balance = balance + {:n} WHERE id = {:b}', params = { n = 100, b = 'b' } },
})

Auth

All async. Every one takes the auth collection name first.

Files and mail

sendEmail needs mail configured in the admin UI — see Mail.

Commands

Server console only, all gated on the command.tdb ACE. See Importing .sql files for what each does in full.

Anything else prints usage: tdb sql status | import <file> [--force] | tables [match] | query <sql> | plan | adopt. Before the database is ready, every subcommand prints not ready yet - wait for the startup banner.

Events

All server-local. Use AddEventHandler.

Version facts