This function starts a database query using the supplied connection. Use the returned query handle with dbPoll to get the result, or dbFree if you don't want the result.

Tip

The server command debugdb 2 will output verbose information on each query to a logging file (usually logs/db.log).

Tip

It is usually good practice to surround table and column names with backticks (`) in case they contain spaces or SQL keywords (and therefore cause syntax errors). This is especially true when using variables for table and column names, as potential problems may not be apparent when the script is first written.

Important

It is strongly recommended to use this function asynchronously, as presented in the Example 4.

OOP Syntax Help! I don't understand this!

• Method:connection:query(...)

Syntax

db-query dbQuery ( [ function callbackFunction() = nil, table callbackArguments = nil ], db-connection databaseConnection, string query, var param1 [, var param2 ...] )

Required Arguments

• databaseConnection: A database connection element previously returned from dbConnect.
• query: An SQL query. Positions where parameter values will be inserted are marked with a ?.
• param1 [, var param2 ...]: A variable number of parameters. These must be strings or numbers - it is important to make sure they are of the correct type. Also, the number of parameters passed must be equal to the number of ? characters in the query string.

  String parameters are automatically quoted and escaped as required. (If you do not want a string quoted, use ??). Make sure that numbers are in number format as a string number is treated differently.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use.

• callbackFunction() (default: nil): An optional function to be called when a result is ready. The function will only be called if the result has not already been read with dbPoll. The function is called with the query handle as the first argument.
• callbackArguments (default: nil): An optional table containing extra arguments (excluding functions) to be sent to the callback function.

Returns

• db-query: query handle

Returns a query handle unless the connection is incorrect, in which case it return false.

Code Examples

Example 1 Example 2 (OOP) Example 3 Example 4 Example 5 Example 6

server

This example starts an INSERT query and frees the result.

local qh = dbQuery(connection, "INSERT INTO table_name VALUES (?,?,?)", "aaa", "bbb", 10)
dbFree(qh)

server

OOP Required

This example starts an INSERT query and frees the result.

local qh = connection:query("INSERT INTO table_name VALUES (?,?,?)", "aaa", "bbb", 10)
qh:free()

server

This example starts a select query and waits for the result: (server freeze included).

local qh = dbQuery(connection, "SELECT * FROM table_name")
local result = dbPoll(qh, -1)

server

This example starts a select query and processes the result in a callback function.

function aaa()
    dbQuery(myCallback, connection, "SELECT * FROM table_name")
end

function myCallback(qh)
    local result = dbPoll(qh, 0) -- Timeout doesn't matter here because the result will always be ready
end

server

This example starts a select query and processes the result in an inline callback function with custom arguments.

dbQuery(function(qh, tag, score)
    local result = dbPoll(qh, 0) -- Timeout doesn't matter here because the result will always be ready
    outputDebugString(tag) -- Prints "hello"
    outputDebugString(score) -- Prints 2000
end, {"hello", 2000}, connection, "SELECT * FROM table_name")

server

This example shows how to use backticks and ?? for parts of the query that are not column values.

dbExec(connection, "UPDATE `??` SET `??`=?", tableName, columnName, columnValue)

See Also

Database Functions

• dbConnect
• dbExec
• dbFree
• dbPoll
• dbPrepareString
• dbQuery
• executeSQLQuery

Reference

• Scripting Functions