DOC SQL placeholders

silverstripe · Jul 24, 2023 · cbcea6f · cbcea6f
1 parent 27bcf60
commit cbcea6f
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 0 deletions.
diff --git a/en/02_Developer_Guides/09_Security/08_SQL_Placeholders.md b/en/02_Developer_Guides/09_Security/08_SQL_Placeholders.md
@@ -0,0 +1,18 @@
+---
+title: SQL Placeholders
+summary: SQL placeholders in ORM queries
+icon: tachometer-alt
+---
+
+# SQL Placeholders
+
+SQL placeholders are `?` characters used as a placeholder for a value in a SQL query as a way to prevent SQL injection attacks. They are used by default extensively in queries created by the ORM.
+
+For increased performance, placeholders are not used when filtering by an array of integer only values on a column that is either a [`DBPrimarykey`](api:SilverStripe\ORM\FieldType\DBPrimaryKey) or a [`DBForiegnKey`](api:SilverStripe\ORM\FieldType\DBForiegnKey). An example of this type of ORM filter is `->filter(['ID' => $ids])` which will turn into a SQL containing `WHERE IN (<ids>)`. 
+
+There is no chance of SQL injection because of the exclusive use of integers for values. However, if you still wish for placeholders to be used for this type of query then you can enable them with the following config:
+
+```yml
+SilverStripe\ORM\Filters\ExactMatchFilter:
+  use_placeholders_for_integer_ids: true
+```
diff --git a/en/04_Changelogs/5.1.0.md b/en/04_Changelogs/5.1.0.md
@@ -11,6 +11,7 @@ title: 5.1.0 (unreleased)
   - [GraphQL schema can be stored in `silverstripe-cache`](#gql-schema-is-cache)
   - [Improvement to page search performance with Elemental](#cms-search-performance)
   - [New `InheritedPermissions` option - only these members](#only-these-members)
+  - [SQL placeholders disabled for WHERE IN ID queries](#placeholders-disabled)
   - [Other new features](#other-features)
 - [API changes](#api-changes)
 - [Dependency changes](#dependency-changes)
@@ -77,6 +78,20 @@ A new permission has been added to [`InheritedPermissions`](api:SilverStripe\Sec
 
 In the CMS, this new permission is available for files and pages by setting "Who can view/edit this page/file" to "Only these users".
 
+### Optimised queries when filtering against IDs {#filter-by-ids}
+
+`DataList` queries filtering against a list of IDs have been optimised when all of the following criteria are met:
+- the column being filtered is a [`DBPrimarykey`](api:SilverStripe\ORM\FieldType\DBPrimaryKey) or a [`DBForiegnKey`](api:SilverStripe\ORM\FieldType\DBForiegnKey)
+- the values being filtered are all either integers or valid integer strings
+- using placeholders for integer ids has been configured off, which is the default config value.
+
+If you want to disable this optimisation you can do so with this configuration:
+
+```yml
+SilverStripe\ORM\Filters\ExactMatchFilter:
+  use_placeholders_for_integer_ids: true
+```
+
 ### Other new features
 
 - You can now exclude specific `DataObject` models from the check and repair step of `dev/build` - see [ORM Performance](/developer_guides/performance/orm/#skip-check-and-repair) for more information.