db_query

db_query(sql, [params]) executes a SELECT query on the SQLite database. Returns an array of row-tables with column-value pairs.

Signature

db_query(sql, [params])

async

Note

Available only on the SQL (SQLite) build variant. Integer/Real/Text/Null SQL types map to Lua number/string/nil. On the KV (redb) variant, calling this returns a clear error directing you to download the SQLite build.

Parameters

Param	Type	Description
sql	string	The SQL SELECT statement
params	table?	Optional array of positional parameters for prepared statements (? placeholders)

nil and SQL NULL

params is a positional array. Leading/interior nil holes bind as SQL NULL:

-- b is NULL
db_query("SELECT id FROM t WHERE a = ? AND b IS ? AND c = ?", { 1, nil, 3 })

Lua tables do not store a trailing nil — { 1, 2, nil } is the same as { 1, 2 }. Do not end the params table with nil. For a trailing SQL NULL, put NULL in the statement text or ensure a non-nil value comes after that slot:

db_query("SELECT id FROM t WHERE a = ? AND b = ? AND c IS NULL", { 1, 2 })

Returns

Value	Type	Description
rows	array	Array of row tables with column-value pairs

Example

local rows = db_query("SELECT json FROM records WHERE job_id = ? LIMIT 5", { "my-job" })
for _, row in ipairs(rows) do
    local data = json_decode(row.json)
    log("Title: " .. data.title)
end

See Also

• db_exec - Execute INSERT/UPDATE/DELETE statements