DB

Database Handling Class. The DB class handles top level abstraction, implementing features which tmysql doesn't provide natively, wrapping a single connection.

DB:Cache(query, cb)Source ☍

Add a query and callback to the cache.

Parameters

• querystringThe cached query.
• cbfunction?The cached callback.

DB:CallbackTime(time)Source ☍

Record how long a callback took.

Parameters

• timenumberTime taken to run the callback.

DB:Connect(cb)Source ☍

Initialize the internal database object.

Parameters

• cbfun()?Called once the connection is established and startup queries have been queued.

DB:Disconnect()Source ☍

Close the connection and stop polling it; the next query connects again. Never call self.Connection:Disconnect() directly: tmysql4 frees the connection, and the Tick hook's next Poll crashes the server.

DB:Escape(str) → stringSource ☍

Escape a string using the DB's inbuilt methods, or in Lua while no database can be reached, so the query can still be queued. The Lua escape matches MySQL's only because the connection is utf8mb4, where no multibyte character holds an escaped byte.

Parameters

• strstringThe input string.

Returns

1. stringThe escaped string.

DB:FRun(query, _)Source ☍

Run a query with formatted data. If the final argument is a function, it is treated as the callback. Re-check IsValid on any player/entity inside that callback — this fires asynchronously.

Parameters

• querystringThe unformatted query to run (string.format pattern).
• anyFormatter arguments, optionally ending with a callback.

DB:IsConnected() → booleanSource ☍

Check if the database is connected.

Returns

1. booleanWhether the DB is connected.

DB:LostConnection(result) → booleanSource ☍

Whether a failed result means the connection it ran on is gone, so the query should be retried on a new one. tmysql4 4.x keeps IsConnected true after the server drops it, retrying the query once itself, so the error number is the only signal once that retry fails too.

Parameters

• resulttableThe failed result set.

Returns

1. boolean

DB:New(cfg) → DBSource ☍

Create a new DB instance.

Parameters

• cfgtableA cityrpserver configuration table.

Returns

1. DBThe new instance.

DB:Poll()Source ☍

Polls one instance's connection, so its finished queries call back.

DB:QueryParams(query, params, cb)Source ☍

Run a query with positional parameters using ? placeholders. Each parameter will be escaped and quoted automatically unless it's a table with _raw field. WARNING: The _raw field feature allows bypassing escaping - use with extreme caution! Only use _raw for trusted, non-user-controlled SQL fragments like column names or operators. Example: DB:QueryParams("INSERT INTO t (a,b) VALUES (?, ?)", {val1, val2}, cb)

Parameters

• querystringSQL query with ? placeholders.
• paramstableParameters to bind.
• cbfunction|nilCallback.

DB:QueryParamsChecked(query, params, cb)Source ☍

Like @{DB:QueryParams}, but reports success via cb(ok, result, err).

Parameters

• querystringSQL query with ? placeholders.
• paramstableParameters to bind.
• cbfunction|nilCallback cb(ok, result, err).

DB:ReconnectIfDown()Source ☍

Reconnect the DB if it is down.

DB:Run(query, cb)Source ☍

Run a query on the DB with an optional callback. Re-check IsValid on any player/entity inside cb — this fires asynchronously.

Parameters

• querystringSQL query to run.
• cbfun(result: any)?Callback. Receives last insert ID for INSERT queries, otherwise retrieved rows.

DB:RunChecked(query, cb)Source ☍

Run a query and report success explicitly to the callback. Unlike @{DB:Run}, the callback is not invoked with a successful payload when MySQL reports failure — callers must handle ok == false (e.g. migrations).

Parameters

• querystringSQL query to run.
• cbfunction|nilCallback cb(ok, result, err) where result is lastid for INSERT else rows.

DB.connectionLostSource ☍

Error numbers that mean the server connection is gone rather than the query being wrong: CR_SERVER_GONE_ERROR and CR_SERVER_LOST.

DB.escapesSource ☍

What mysql_real_escape_string replaces, and with what.

DBSource ☍

Kept across a reload of this file: DB_MAIN's metatable is this table, and the poll hook below finds connections through DB.instances, so starting over from {} would silently stop DB_MAIN being polled.

DB.__callSource ☍

Alias of DB:New

DB.__indexSource ☍

Lookup table.

DB.ConnectionSource ☍

DB.instancesSource ☍

Every instance that has connected, polled by the Tick hook below. Weakly keyed, so a dropped instance stops being polled.