- changelog for #3034, at this point we can mark fix #3034

diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index d15ca760c3a00d8c24dfb811e1ad052f099ee3cd..34466b9fe300dfb8cfa4f487a41b08a25d3a4b12 100644 (file)
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -14,4 +14,22 @@
         :start-line: 5
 
 .. changelog::
-       :version: 1.0.0
\ No newline at end of file
+       :version: 1.0.0
+
+       .. change::
+               :tags: feature, sql
+               :tickets: 3034
+
+               The :meth:`.Select.limit` and :meth:`.Select.offset` methods
+               now accept any SQL expression, in addition to integer values, as
+               arguments.  Typically this is used to allow a bound parameter to be
+               passed, which can be substituted with a value later thus allowing
+               Python-side caching of the SQL query.   The implementation
+               here is fully backwards compatible with existing third party dialects,
+               however those dialects which implement special LIMIT/OFFSET systems
+               will need modification in order to take advantage of the new
+               capabilities.  Work on this feature is courtesy of Dobes Vandermeer.
+
+               .. seealso::
+
+                       :ref:`feature_3034`.

diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst
index ac287af1a792162d7ada351aa410478da973aa0c..340f9b7ad71711d44f5cb09f1579d09b19e98eeb 100644 (file)
--- a/doc/build/changelog/migration_10.rst
+++ b/doc/build/changelog/migration_10.rst
@@ -36,6 +36,31 @@ Behavioral Changes - Core
 New Features
 ============
 
+.. _feature_3034:
+
+Select/Query LIMIT / OFFSET may be specified as an arbitrary SQL expression
+----------------------------------------------------------------------------
+
+The :meth:`.Select.limit` and :meth:`.Select.offset` methods now accept
+any SQL expression, in addition to integer values, as arguments.  The ORM
+:class:`.Query` object also passes through any expression to the underlying
+:class:`.Select` object.   Typically
+this is used to allow a bound parameter to be passed, which can be substituted
+with a value later::
+
+       sel = select([table]).limit(bindparam('mylimit')).offset(bindparam('myoffset'))
+
+Dialects which don't support non-integer LIMIT or OFFSET expressions may continue
+to not support this behavior; third party dialects may also need modification
+in order to take advantage of the new behavior.  A dialect which currently
+uses the ``._limit`` or ``._offset`` attributes will continue to function
+for those cases where the limit/offset was specified as a simple integer value.
+However, when a SQL expression is specified, these two attributes will
+instead raise a :class:`.CompileError` on access.  A third-party dialect which
+wishes to support the new feature should now call upon the ``._limit_clause``
+and ``._offset_clause`` attributes to receive the full SQL expression, rather
+than the integer value.
+
 
 Behavioral Improvements
 =======================