Merge pull request piccolo-orm#57 from piccolo-orm/raw_sql_where_clause

Added WhereRaw

Author: dantownsend

docs/src/piccolo/query_clauses/where.rst

@@ -30,6 +30,8 @@ Equal / Not Equal
         b.name != 'Rustaceans'
     ).run_sync()
 
+-------------------------------------------------------------------------------
+
 Greater than / less than
 ------------------------
 
@@ -42,6 +44,8 @@ You can use the ``<, >, <=, >=`` operators, which work as you expect.
         b.popularity >= 100
     ).run_sync()
 
+-------------------------------------------------------------------------------
+
 like / ilike
 -------------
 
@@ -64,6 +68,8 @@ The percentage operator is required to designate where the match should occur.
 
 ``ilike`` is identical, except it's case insensitive.
 
+-------------------------------------------------------------------------------
+
 not_like
 --------
 
@@ -76,6 +82,8 @@ Usage is the same as ``like`` excepts it excludes matching rows.
         b.name.not_like('Py%')
     ).run_sync()
 
+-------------------------------------------------------------------------------
+
 is_in / not_in
 --------------
 
@@ -93,6 +101,8 @@ is_in / not_in
         b.name.not_in(['Rustaceans'])
     ).run_sync()
 
+-------------------------------------------------------------------------------
+
 Complex queries - and / or
 ---------------------------
 
@@ -151,3 +161,42 @@ Rather than using the ``|`` and ``&`` characters, you can use the ``And`` and
             b.name == 'Pythonistas'
         )
     ).run_sync()
+
+-------------------------------------------------------------------------------
+
+WhereRaw
+--------
+
+In certain situations you may want to have raw SQL in your where clause.
+
+.. code-block:: python
+
+    from piccolo.columns.combination import WhereRaw
+
+    Band.select().where(
+        WhereRaw("name = 'Pythonistas'")
+    ).run_sync()
+
+It's important to parameterise your SQL statements if the values come from an
+untrusted source, otherwise it could lead to a SQL injection attack.
+
+.. code-block:: python
+
+    from piccolo.columns.combination import WhereRaw
+
+    value = "Could be dangerous"
+
+    Band.select().where(
+        WhereRaw("name = {}", value)
+    ).run_sync()
+
+``WhereRaw`` can be combined into complex queries, just as you'd expect:
+
+.. code-block:: python
+
+    from piccolo.columns.combination import WhereRaw
+
+    b = Band
+    b.select().where(
+        WhereRaw("name = 'Pythonistas'") | (b.popularity > 1000)
+    ).run_sync()

piccolo/columns/combination.py

@@ -54,6 +54,27 @@ class Undefined:
 UNDEFINED = Undefined()
 
 
+class WhereRaw(CombinableMixin):
+    def __init__(self, sql: str, *args: t.Any) -> None:
+        """
+        Execute raw SQL queries in your where clause. Use with caution!
+
+        await Band.where(
+            WhereRaw("name = 'Pythonistas'")
+        )
+
+        Or passing in parameters:
+
+        await Band.where(
+            WhereRaw("name = {}", 'Pythonistas')
+        )
+        """
+        self.querystring = QueryString(sql, *args)
+
+    def __str__(self):
+        return self.querystring.__str__()
+
+
 class Where(CombinableMixin):
 
     __slots__ = ("column", "value", "values", "operator")

tests/table/test_select.py

@@ -1,6 +1,7 @@
 from unittest import TestCase
 
 from piccolo.apps.user.tables import BaseUser
+from piccolo.columns.combination import WhereRaw
 from piccolo.query.methods.select import Count
 
 from ..base import DBTestCase, postgres_only, sqlite_only
@@ -116,6 +117,59 @@ def test_where_less_equal_than(self):
             response, [{"name": "Pythonistas"}, {"name": "CSharps"}]
         )
 
+    def test_where_raw(self):
+        """
+        Make sure raw SQL passed in to a where clause works as expected.
+        """
+        self.insert_rows()
+
+        response = (
+            Band.select(Band.name)
+            .where(WhereRaw("name = 'Pythonistas'"))
+            .run_sync()
+        )
+
+        print(f"response = {response}")
+
+        self.assertEqual(response, [{"name": "Pythonistas"}])
+
+    def test_where_raw_with_args(self):
+        """
+        Make sure raw SQL with args, passed in to a where clause, works
+        as expected.
+        """
+        self.insert_rows()
+
+        response = (
+            Band.select(Band.name)
+            .where(WhereRaw("name = {}", "Pythonistas"))
+            .run_sync()
+        )
+
+        print(f"response = {response}")
+
+        self.assertEqual(response, [{"name": "Pythonistas"}])
+
+    def test_where_raw_combined_with_where(self):
+        """
+        Make sure WhereRaw can be combined with Where.
+        """
+        self.insert_rows()
+
+        response = (
+            Band.select(Band.name)
+            .where(
+                WhereRaw("name = 'Pythonistas'") | (Band.name == "Rustaceans")
+            )
+            .run_sync()
+        )
+
+        print(f"response = {response}")
+
+        self.assertEqual(
+            response, [{"name": "Pythonistas"}, {"name": "Rustaceans"}]
+        )
+
     def test_where_and(self):
         self.insert_rows()