From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 23 May 2014 15:34:14 +0000 (-0400)
Subject: - changelog for #3034, at this point we can mark fix #3034
X-Git-Tag: rel_1_0_0b1~433
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0436538314b59a05c2f48294c4cf0793b000425b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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 d15ca760c3..34466b9fe3 100644
--- 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 ac287af1a7..340f9b7ad7 100644
--- 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
 =======================