/datum/database/database/query proc

This adds the command text - the actual SQL query - to a database datum. Existing command text will be removed automatically - this is equivalent to running /database/query/proc/Clear().

var/database/my_db = new("sqlite.db")
var/database/query/my_query = new()
my_query.Add("CREATE TABLE my_table (id int, name string)")
my_query.Execute(my_db)

When additional arguments are given to this proc, they will be used to substitute ? in the command text. This is functionally equivalent to prepared statements.

var/database/query/my_other_query = new()
my_other_query.Add("INSERT INTO my_table (name) VALUES (?)", "Barry")

This is equivalent to the following:

INSERT INTO my_table (name) VALUES ("Barry")

Removes the current command text. This is invoked when you call /database/query/proc/Add(), so does not typically need to be called manually.

This terminates the "reading" of the results of the query. This is handled automatically when the query datum is deleted.

Once a query has started being read (after /database/query/proc/Execute() has been called), the column names can be retrieved using this proc.

query.Add("CREATE TABLE example (id int, name string, foo string, bar string)")
query.Execute(db)

query.Add("SELECT * FROM example")
query.Execute(db)

var/columns = query.Columns() // "id", "name", "foo", "bar"
var/specific_column = query.Columns(0) // "id"

This provides the error code last encountered by this query.

This provides the error message last encountered by this query.

Runs the generated query against the provided database. If the query is expected to return data, you can increment the row being read with /database/query/proc/NextRow().

var/database/db = new("mydb.db")
var/database/query/query = new("SELECT user FROM leaderboard ORDER BY score ASC")
query.Execute(db)

var/list/top_scorers = list()

while(query.NextRow())
    top_scorers += query.GetColumn(0)

Once the query has been run with /database/query/proc/Execute() and we have started to read rows with /database/query/proc/NextRow(), we can retrieve the data stored in a specific column with this proc. To get the names of the columns, /database/query/proc/Columns() can be used.

This retrieves the information of the current row presented in an associated list. This can only be run after the query has been executed with /database/query/proc/Execute() and started being read with /database/query/proc/NextRow().

var/database/db = new("database.db")
var/database/query/query = new("SELECT * FROM players")
query.Execute()
query.NextRow()

var/row = query.GetRowData()
for(var/key in row)
    world.log << "[key]: [row[key]]" // 'username: "Barry"', 'score: 500', 'admin: 0'

This will create a new query. If the arguments to the proc are provided, /database/query/proc/Add() will automatically be called.

This will shift the reading to the next row of results. It must also be called before reading the first result. After this has been called, you can use /database/query/proc/GetRowData() or /database/query/proc/GetColumn() to retrieve the data from this row.

After running a query that makes changes to the database, this can be used to determine if the operation has succeeded.

var/database/db = new("db.db")
var/database/query/query = new("UPDATE players SET upgraded = 1 WHERE score > 500")
query.Execute(db)

var/affected = query.RowsAffected()
if(affected)
    world.log << "[affected] players have been upgraded."