diff --git a/modules/database/doc_classes/QueryBuilder.xml b/modules/database/doc_classes/QueryBuilder.xml index 379ba3160..4ea9231bf 100644 --- a/modules/database/doc_classes/QueryBuilder.xml +++ b/modules/database/doc_classes/QueryBuilder.xml @@ -1,8 +1,17 @@ + A class that helps you with building and running database backend specific sql safely. + A class that helps you with building and running database backend specific sql safely. + Methods by default use escape on their parameters that can normally contain user input. For performance reasons other variants that don't do this also exist. These are prefixed with 'n'. For example [method select] vs [method nselect]. Don't use these with raw user input, as it will make your application vulnerable to sql injection attacks. + It contains helper methods that lets you run the finished query directly See [method run] and [method run_query]. + You should not allocate this directly, instead get it from you active database connection, like: + [codeblock] + var conn : DatabaseConnection = DatabaseManager.ddb.get_connection() + var qb : QueryBuilder = conn.get_query_builder() + [/codeblock] @@ -11,71 +20,116 @@ + Equivalent to: + [codeblock] + if (col.empty()): + result += "ASC, " + else: + result += col + " ASC, " + [/codeblock] + Equivalent to: + [codeblock] + result += "BEGIN TRANSACTION;" + [/codeblock] + Equivalent to: + [codeblock] + result += "COMMIT;" + [/codeblock] + Closes the current [code]ORDER BY[/code] statement. (Usually by removing the last [code],[/code]). + Closes the current [code]SET[/code] statement. (Usually by removing the last [code],[/code]). + Closes the current string. (Usually by adding a [code]'[/code]). + Closes the current [code]VALUES[/code] statement. (Usually by replacing the last [code],[/code] with a [code])[/code]). + Equivalent to: + [codeblock] + result += "DELETE FROM " + escape(params) + " " + [/codeblock] + Equivalent to: + [codeblock] + if (col.empty()): + result += "DESC, " + else: + result += col + " DESC, " + [/codeblock] + Closes the current sql command. (Usually by adding a [code];[/code]). + Escapes the given string and returns it. (Using the database connector's escape method.) + (ew = escape write) + Equivalent to: + [codeblock] + result += escape(str) + [/codeblock] + Equivalent to: + [codeblock] + result += "FROM " + + if (!params.empty()): + result += escape(params) + result += " " + [/codeblock] @@ -83,62 +137,117 @@ + Equivalent to: + [codeblock] + result += "INSERT INTO "; + + if (!table_name.empty()): + result += table_name + result += " " + + if (!columns.empty()): + result += "(" + result += columns + result += ") " + [/codeblock] + (land = logical and) + Equivalent to: + [codeblock] + result += "AND " + [/codeblock] + Equivalent to: + [codeblock] + if (str.empty()): + result += "LIKE " + else: + result += "LIKE '" + escape(str) + "' " + [/codeblock] + Equivalent to: + [codeblock] + result += "LIMIT " + itos(num) + " " + [/codeblock] + (lor = logical or) + Equivalent to: + [codeblock] + result += "OR " + [/codeblock] + Equivalent to: + [codeblock] + result += "DELETE FROM " + params + " " + [/codeblock] + Closes the current [code]VALUES[/code] statement, and then open an another one. (Usually by replacing the last [code],[/code] with [code]"), ("[/code]). + Equivalent to: + [codeblock] + result += "FROM " + + if (!params.empty()): + result += params + " " + [/codeblock] + Adds a newline. This can help when debugging sql statements. (Usually [code]\n[/code]). + Equivalent to: + [codeblock] + result += "LIKE '" + str + "' " + [/codeblock] + Equivalent to: + [codeblock] + result += "SELECT " + params + " " + [/codeblock] @@ -146,30 +255,61 @@ + Add parameters to [code]UPDATE[/code] statements. + Equivalent to: + [codeblock] + result += col + "='" + params + "', " + [/codeblock] + Start an [code]UPDATE[/code] statement. + Equivalent to: + [codeblock] + result += "UPDATE " + params + " " + [/codeblock] + Add parameters to [code]INSERT INTO[/code] statements. + Equivalent to: + [codeblock] + result += "'" + param + "', " + [/codeblock] + Adds an unescaped [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + result += "VALUES(" + + if (!params_str.empty()): + result += params_str + ") " + [/codeblock] + Adds an unescaped [code]WHERE[/code] statement. + Equivalent to: + [codeblock] + result += "WHERE " + + if (!params.empty()): + result += params + " " + [/codeblock] @@ -177,67 +317,112 @@ + Add an unescaped parameter to [code]WHERE[/code] statements. + Equivalent to: + [codeblock] + result += col + "='" + params + "' " + [/codeblock] + Adds an [code]OFFSET[/code] statement. + Equivalent to: + [codeblock] + result += "OFFSET " + str(num) + " " + [/codeblock] + Adds an [code]ORDER BY[/code] statement. + Equivalent to: + [codeblock] + if (col.empty()): + result += "ORDER BY " + else: + result += "ORDER BY " + col + ", " + [/codeblock] + Adds a column to an [code]ORDER BY[/code] statement. + Equivalent to: + [codeblock] + result += col + ", " + [/codeblock] + Adds an [code]ORDER BY ASC[/code] statement. + Equivalent to: + [codeblock] + result += "ORDER BY " + col + " ASC, "; + [/codeblock] + Adds an [code]ORDER BY DESC[/code] statement. + Equivalent to: + [codeblock] + result += "ORDER BY " + col + " DESC, "; + [/codeblock] + Part of the unfinished prepared statement api. + Resets the QueryBuilder. + Run the query currently stored in the result property. + Use this if your query returns values from the database (an you want to read them). + Run the query currently stored in the result property. + Use this if your query doesn't return values from the database (or you don't want to read them if it does). + Adds a [code]SELECT[/code] statement. + Equivalent to: + [codeblock] + result += SELECT " + escape(params) + " " + [/codeblock] + Adds a statement to select and return the last inserted row's id. @@ -245,6 +430,7 @@ + Part of the unfinished prepared statement api. @@ -252,6 +438,7 @@ + Part of the unfinished prepared statement api. @@ -259,6 +446,7 @@ + Part of the unfinished prepared statement api. @@ -266,6 +454,14 @@ + Add a bool parameter to [code]UPDATE[/code] statements. + Equivalent to: + [codeblock] + if (param): + result += col + "=1, " + else: + result += col + "=0, " + [/codeblock] @@ -273,6 +469,11 @@ + Add a double parameter to [code]UPDATE[/code] statements. + Equivalent to: + [codeblock] + result += col + "=" + str(param) + ", " + [/codeblock] @@ -280,6 +481,11 @@ + Add a float parameter to [code]UPDATE[/code] statements. + Equivalent to: + [codeblock] + result += col + "=" + str(param) + ", " + [/codeblock] @@ -287,6 +493,11 @@ + Add an int parameter to [code]UPDATE[/code] statements. + Equivalent to: + [codeblock] + result += col + "=" + str(param) + ", " + [/codeblock] @@ -294,80 +505,151 @@ + Add an escaped string parameter to [code]UPDATE[/code] statements. + Equivalent to: + [codeblock] + result += col + "=" + escape(param) + ", " + [/codeblock] + Starts a [code]SET[/code] statement. + Equivalent to: + [codeblock] + result += "SET " + [/codeblock] + Starts a string. (Usually by adding a [code]'[/code]). + Starts an [code]UPDATE[/code] statement. + Equivalent to: + [codeblock] + result += "UPDATE " + escape(params) + " " + [/codeblock] + Adds [code]DEFAULT[/code] to a [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + result += "DEFAULT, " + [/codeblock] + Add a bool parameter to a [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + if (param): + result += "1, " + else: + result += "0, " + [/codeblock] + Add a double parameter to a [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + result += str(param) + ", " + [/codeblock] + Add a float parameter to a [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + result += str(param) + ", " + [/codeblock] + Add an int parameter to a [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + result += str(param) + ", " + [/codeblock] + Add an escaped string parameter to a [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + result += escape(param) + ", " + [/codeblock] + Adds an escaped [code]VALUES[/code] statement. + Equivalent to: + [codeblock] + result += "VALUES(" + + if (!params_str.empty()): + result += escape(params_str) + ") " + [/codeblock] + (w = write) + Equivalent to: + [codeblock] + result += str + [/codeblock] + Adds an escaped [code]WHERE[/code] statement. + Equivalent to: + [codeblock] + result += "WHERE " + + if (!params.empty()): + result += escape(params) + " " + [/codeblock] + Gets the wildcard character for the given database backend. (Usually [code]%[/code].) @@ -375,6 +657,14 @@ + Add a bool parameter to a [code]WHERE[/code] statement. (wpb = where param bool) + Equivalent to: + [codeblock] + if (param): + result += col + "=1 " + else: + result += col + "=0 " + [/codeblock] @@ -382,6 +672,11 @@ + Add an int parameter to a [code]WHERE[/code] statement. (wpi = where param int) + Equivalent to: + [codeblock] + result += col + "=" + str(param) + " " + [/codeblock] @@ -389,11 +684,17 @@ + Add an escaped string parameter to a [code]WHERE[/code] statement. (wps = where param string) + Equivalent to: + [codeblock] + result += col + "='" + escape(param) + "' " + [/codeblock] + The current (resulting) sql statement.