From b02ddfd5e24c18fea9b7cf12bc7b5ee67f36b9a7 Mon Sep 17 00:00:00 2001 From: Relintai Date: Mon, 12 May 2025 11:35:15 +0200 Subject: [PATCH] Added recommandations to PreparedStatement and QueryBuilder's docs. --- modules/database/doc_classes/PreparedStatement.xml | 3 ++- modules/database/doc_classes/QueryBuilder.xml | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/modules/database/doc_classes/PreparedStatement.xml b/modules/database/doc_classes/PreparedStatement.xml index 1a62d5bf1..d6d7196db 100644 --- a/modules/database/doc_classes/PreparedStatement.xml +++ b/modules/database/doc_classes/PreparedStatement.xml @@ -6,7 +6,8 @@ Represents a prepared statement for use with a [Database]. Prepared statements are compiled and parametrized sql statements which can be used repeatedly. - [PreparedStatement]s are an alternative to [QueryBuilder]. + [PreparedStatement]s are an alternative to [QueryBuilder]. [QueryBuilder] is better for simple queries as it makes them database backend agnostic. + If multiple database backend support is desired [method Database.get_backend_name] can help in deciding what sql to use. Prepared statements comes with a lot of added security, as SQL injection attacks doesn't work with them (as long as you use their parameters). However note that [QueryBuilder] will escape string parameters which expect to have user input in the for you too, so if you use [QueryBuilder] yuo should also be safe. Performance can differ compared to normal queries, but it seems like it depends on a lot of factors, so you will have to banchmark it yourself for heavy queries. It can be faster or slower. A prepared statement looks similar: diff --git a/modules/database/doc_classes/QueryBuilder.xml b/modules/database/doc_classes/QueryBuilder.xml index 7a6eea162..44e4a4152 100644 --- a/modules/database/doc_classes/QueryBuilder.xml +++ b/modules/database/doc_classes/QueryBuilder.xml @@ -1,10 +1,11 @@ - 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 agnostic sql safely. - 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 agnostic sql safely. + Recommended for relative simple queries. For more advanced use cases [PreparedStatement]s are better. 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: