Database

The DB global is the framework-owned boundary over shiva-db. All database access in modules goes through DB — never import shiva-db exports directly. DB provides raw SQL methods and a fluent query builder via DB.table().

Server-only

DB is a server-side global. It is not available in client scripts.

Query Builder (Recommended)

The primary way to interact with the database. Returns a chainable QueryBuilder instance.

local rows = DB.table('players')
    :where('online', true)
    :orderBy('name')
    :get()

See the Query Builder reference → for the full API.

Raw SELECT

local rows = DB.raw(sql, params?)

Execute a raw SELECT and return all matching rows.

local rows = DB.raw(
    'SELECT * FROM players WHERE job = ? AND grade >= ?',
    { 'police', 2 }
)

Execute (INSERT / UPDATE / DELETE / DDL)

local result = DB.execute(sql, params?)

For INSERT, returns the new row's insert ID. For UPDATE/DELETE, returns affected row count.

DB.execute('DELETE FROM logs WHERE created_at < ?', { cutoff })

Scalar

local value = DB.scalar(sql, params?)

Returns a single value from the first column of the first row.

local count = DB.scalar('SELECT COUNT(*) FROM players WHERE online = 1')

Transaction

DB.transaction(function)

Runs all queries inside the function in a single transaction. Automatically rolls back on error.

DB.transaction(function()
    DB.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', { amount, fromId })
    DB.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', { amount, toId })
end)

Ping

local ok = DB.ping()  -- boolean

Tests the database connection. Returns true on success.

Configuration

Convar / Config Key	Type	Default	Description
database.logQueries	boolean	false	Log every query via Log.debug
database.slowQueryThreshold	integer	500	Emit a Log.warn for queries exceeding this many milliseconds

API Reference

Method	Returns	Description
DB.table(tableName)	QueryBuilder	Create a fluent query builder for the table
DB.raw(sql, params?)	table[]	Execute a raw SELECT, return all rows
DB.execute(sql, params?)	integer	Execute any SQL statement
DB.scalar(sql, params?)	any	Return a single scalar value
DB.transaction(fn)	any	Run queries in a transaction, auto-rollback on error
DB.ping()	boolean	Test the database connection

See Also

• Query Builder →
• Models →
• Migrations →