Warn when caching is disabled / document

This patch adds new warnings for all elements that
don't indicate their caching behavior, including user-defined
ClauseElement subclasses and third party dialects.
it additionally adds new documentation to discuss an apparent
performance degradation in 1.4 when caching is disabled as a
result in the significant expense incurred by ORM
lazy loaders, which in 1.3 used BakedQuery so were actually
cached.

As a result of adding the warnings, a fair degree of
lesser used SQL expression objects identified that they did not
define caching behavior so would have been producing
``[no key]``, including PostgreSQL constructs ``hstore``
and ``array``.  These have been amended to use inherit
cache where appropriate.  "on conflict" constructs in
PostgreSQL, MySQL, SQLite still explicitly don't generate
a cache key at this time.

The change also adds a test for all constructs via
assert_compile() to assert they will not generate cache
warnings.

Fixes: #7394
Change-Id: I85958affbb99bfad0f5efa21bc8f2a95e7e46981

1 files changed, 9 insertions, 0 deletions

diff --git a/examples/dogpile_caching/caching_query.py b/examples/dogpile_caching/caching_query.py
index dc007a760..4533dce00 100644
--- a/examples/dogpile_caching/caching_query.py
+++ b/examples/dogpile_caching/caching_query.py
@@ -130,10 +130,19 @@ class FromCache(UserDefinedOption):
         self.expiration_time = expiration_time
         self.ignore_expiration = ignore_expiration
 
+    # this is not needed as of SQLAlchemy 1.4.28;
+    # UserDefinedOption classes no longer participate in the SQL
+    # compilation cache key
     def _gen_cache_key(self, anon_map, bindparams):
         return None
 
     def _generate_cache_key(self, statement, parameters, orm_cache):
+        """generate a cache key with which to key the results of a statement.
+
+        This leverages the use of the SQL compilation cache key which is
+        repurposed as a SQL results key.
+
+        """
         statement_cache_key = statement._generate_cache_key()
 
         key = statement_cache_key.to_offline_string(