- 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 f7e033d85c4d6f4bb8caa8e1ee614cbe26d5b266..cab6c1daf88d0287803a1ac1e52f56162c06ddcd 100644 (file)
--- 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