From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 21 Aug 2014 00:18:30 +0000 (-0400)
Subject: - upgrade the note about inline=True to a warning, and make it clear that
X-Git-Tag: rel_0_9_8~55
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d3dea559e1808c64f6e190f95f89c481919cad20;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- upgrade the note about inline=True to a warning, and make it clear that
this flag should really be set all the time. ref #3169
---

diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index f7e033d85c..cab6c1daf8 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -495,18 +495,25 @@ class Insert(ValuesBase):
          would normally raise an exception if these column lists don't
          correspond.
 
-        .. note::
+        .. warning::
+
+           The ``inline=True`` flag should be set to True when using
+           backends that support RETURNING, including Postgresql, Oracle,
+           and SQL Server.   This will prevent the implicit ``RETURNING``
+           clause from being appended to the statement, which is normally
+           used to fetch the "last inserted primary key" value.  This feature
+           will raise an error if the statement inserts zero rows, and
+           on some backends (e.g. Oracle) it will raise an error if the
+           statement inserts more than one row.
 
-           Depending on backend, it may be necessary for the :class:`.Insert`
-           statement to be constructed using the ``inline=True`` flag; this
-           flag will prevent the implicit usage of ``RETURNING`` when the
-           ``INSERT`` statement is rendered, which isn't supported on a
-           backend such as Oracle in conjunction with an ``INSERT..SELECT``
-           combination::
+           :paramref:`.Insert.inline` is set to True as follows::
 
              sel = select([table1.c.a, table1.c.b]).where(table1.c.c > 5)
              ins = table2.insert(inline=True).from_select(['a', 'b'], sel)
 
+           Version 1.0 of SQLAlchemy will set this flag to True in **all**
+           cases.
+
         .. note::
 
            A SELECT..INSERT construct in SQL has no VALUES clause.  Therefore