more docs for autocommit isolation level

this concept is not clear that we offer real
DBAPI autocommit everywhere.  backport 1.3 with edits
as well

Change-Id: I2e8328b7fb6e1cdc5453ab29c94276f60c7ca149

6 files changed, 25 insertions, 14 deletions

diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index 06ea80b9e..427dd0e1f 100644
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -342,11 +342,12 @@ Valid values for ``isolation_level`` include:
 * ``SERIALIZABLE``
 * ``SNAPSHOT`` - specific to SQL Server
 
-.. versionadded:: 1.1 support for isolation level setting on Microsoft
-   SQL Server.
-
 .. versionadded:: 1.2 added AUTOCOMMIT isolation level setting
 
+.. seealso::
+
+    :ref:`dbapi_autocommit`
+
 Nullability
 -----------
 MSSQL has support for three levels of column nullability. The default
diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index d3d7a8cce..d4ffcabd5 100644
--- a/lib/sqlalchemy/dialects/mysql/base.py
+++ b/lib/sqlalchemy/dialects/mysql/base.py
@@ -158,7 +158,9 @@ MySQLdb, MySQL-Client, MySQL-Connector Python, and PyMySQL.   Using it,
 the MySQL connection will return true for the value of
 ``SELECT @@autocommit;``.
 
-.. versionadded:: 1.1 - added support for the AUTOCOMMIT isolation level.
+.. seealso::
+
+    :ref:`dbapi_autocommit`
 
 AUTO_INCREMENT Behavior
 -----------------------
diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py
index 34c665fbe..6f4df8068 100644
--- a/lib/sqlalchemy/dialects/oracle/base.py
+++ b/lib/sqlalchemy/dialects/oracle/base.py
@@ -68,6 +68,10 @@ Valid values for ``isolation_level`` include:
    as well as the notion of a default isolation level, currently harcoded
    to "READ COMMITTED".
 
+.. seealso::
+
+    :ref:`dbapi_autocommit`
+
 Identifier Casing
 -----------------
 
diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index c2d9af4d2..5cef5d929 100644
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -117,6 +117,8 @@ Valid values for ``isolation_level`` include:
 
 .. seealso::
 
+    :ref:`dbapi_autocommit`
+
     :ref:`psycopg2_isolation_level`
 
     :ref:`pg8000_isolation_level`
diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py
index a203e786e..0475a397e 100644
--- a/lib/sqlalchemy/dialects/sqlite/base.py
+++ b/lib/sqlalchemy/dialects/sqlite/base.py
@@ -212,6 +212,10 @@ by *not even emitting BEGIN* until the first write operation.
     degree than is often feasible. See the section :ref:`pysqlite_serializable`
     for techniques to work around this behavior.
 
+.. seealso::
+
+    :ref:`dbapi_autocommit`
+
 SAVEPOINT Support
 ----------------------------
 
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 2d672099b..d60f14f31 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -212,16 +212,14 @@ class Connection(Connectable):
         :param autocommit: Available on: Connection, statement.
           When True, a COMMIT will be invoked after execution
           when executed in 'autocommit' mode, i.e. when an explicit
-          transaction is not begun on the connection. Note that DBAPI
-          connections by default are always in a transaction - SQLAlchemy uses
-          rules applied to different kinds of statements to determine if
-          COMMIT will be invoked in order to provide its "autocommit" feature.
-          Typically, all INSERT/UPDATE/DELETE statements as well as
-          CREATE/DROP statements have autocommit behavior enabled; SELECT
-          constructs do not. Use this option when invoking a SELECT or other
-          specific SQL construct where COMMIT is desired (typically when
-          calling stored procedures and such), and an explicit
-          transaction is not in progress.
+          transaction is not begun on the connection.   Note that this
+          is **library level, not DBAPI level autocommit**.  The DBAPI
+          connection will remain in a real transaction unless the
+          "AUTOCOMMIT" isolation level is used.
+
+          .. deprecated:: 1.4  The library-level "autocommit" feature is being
+             removed in favor of database driver "autocommit" which is
+             now widely available.  See the section :ref:`dbapi_autocommit`.
 
         :param compiled_cache: Available on: Connection.
           A dictionary where :class:`.Compiled` objects