Added note about backslashes and LIKE

Added note about the use of LIKE with strings containing
backslashes.  Addresses concern in issue #785.

1 files changed, 21 insertions, 0 deletions

diff --git a/doc/src/usage.rst b/doc/src/usage.rst
index db8674c..74715a3 100644
--- a/doc/src/usage.rst
+++ b/doc/src/usage.rst
@@ -221,7 +221,28 @@ argument of the `~cursor.execute()` method::
     >>> cur.execute(SQL, data) # Note: no % operator
 
 
+Values containing backslashes and LIKE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Unlike in Python, the **backslash** (`\`) is not used as an escape
+character *except* in patterns used with `LIKE` and `ILIKE` where they
+are needed to escape the `%` and `_` characters.
+
+This can lead to confusing situations::
+
+   >>> path = r'C:\Users\Bobby.Tables'
+   >>> cur.execute('INSERT INTO mytable(path) VALUES (%s)', (path,))
+   >>> cur.execute('SELECT * FROM mytable WHERE path LIKE %s', (path,))
+   >>> cur.fetchall()
+   []
+
+The solution is to specify an `ESCAPE` character of `''` (empty string)
+in your `LIKE` query::
+
+   >>> cur.execute("SELECT * FROM mytable WHERE path LIKE %s ESCAPE ''", (path,))
+
+
+  
 .. index::
     single: Adaptation
     pair: Objects; Adaptation