From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 8 May 2019 15:40:12 +0000 (-0400)
Subject: Add documentation for MySQL optimizer hints using prefix_with
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8f11e4222219405fd1e9941d11bde9c8f595ed2f;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Add documentation for MySQL optimizer hints using prefix_with

Fixes: #4667
Change-Id: Iac3345319dc7c5a20bc7a6520492d2f341b64807
(cherry picked from commit c608c3f2f8af0e4cd9e2ffbd3b6f7f487e785282)
---

diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index c540594f9d..bb12218643 100644
--- a/lib/sqlalchemy/dialects/mysql/base.py
+++ b/lib/sqlalchemy/dialects/mysql/base.py
@@ -323,14 +323,22 @@ available.
 * INSERT..ON DUPLICATE KEY UPDATE:  See
   :ref:`mysql_insert_on_duplicate_key_update`
 
-* SELECT pragma::
+* SELECT pragma, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`::
 
-    select(..., prefixes=['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
+    select(...).prefix_with(['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
 
 * UPDATE with LIMIT::
 
     update(..., mysql_limit=10)
 
+* optimizer hints, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`::
+
+    select(...).prefix_with("/*+ NO_RANGE_OPTIMIZATION(t4 PRIMARY) */")
+
+* index hints, use :meth:`.Select.with_hint` and :meth:`.Query.with_hint`::
+
+    select(...).with_hint(some_table, "USE INDEX xyz")
+
 .. _mysql_insert_on_duplicate_key_update:
 
 INSERT...ON DUPLICATE KEY UPDATE (Upsert)
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index aed2cb67d6..06a1cdb066 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1533,6 +1533,10 @@ class Query(object):
 
             :meth:`.Query.with_statement_hint`
 
+            :meth:.`.Query.prefix_with` - generic SELECT prefixing which also
+            can suit some database-specific HINT syntaxes such as MySQL
+            optimizer hints
+
         """
         if selectable is not None:
             selectable = inspect(selectable).selectable
@@ -2871,18 +2875,20 @@ class Query(object):
         ``Query``.
 
         :param \*prefixes: optional prefixes, typically strings,
-         not using any commas.   In particular is useful for MySQL keywords.
+         not using any commas.   In particular is useful for MySQL keywords
+         and optimizer hints:
 
         e.g.::
 
             query = sess.query(User.name).\
                 prefix_with('HIGH_PRIORITY').\
-                prefix_with('SQL_SMALL_RESULT', 'ALL')
+                prefix_with('SQL_SMALL_RESULT', 'ALL').\
+                prefix_with('/*+ BKA(user) */')
 
         Would render::
 
-            SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name
-            FROM users
+            SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL /*+ BKA(user) */
+            users.name AS users_name FROM users
 
         .. seealso::
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index db4ec98a73..566c5ce212 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -277,6 +277,9 @@ class HasPrefixes(object):
 
             stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")
 
+            # MySQL 5.7 optimizer hints
+            stmt = select([table]).prefix_with("/*+ BKA(t1) */", dialect="mysql")
+
         Multiple prefixes can be specified by multiple calls
         to :meth:`.prefix_with`.
 
@@ -3037,6 +3040,10 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
 
             :meth:`.Select.with_hint`
 
+            :meth:.`.Select.prefix_with` - generic SELECT prefixing which also
+            can suit some database-specific HINT syntaxes such as MySQL
+            optimizer hints
+
         """
         return self.with_hint(None, text, dialect_name)