- document how to use autocommit isolation level for CONCURRENTLY,

fixes #3887

Change-Id: I6d1a13b7bb4169204105c7a100d17cfed3ded9d1

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 8bf6e10c1233f8d0921a27b346d3f03945e802c0..b436b934fb2ecaeb0ae4ec313e90da70a90b2390 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -644,6 +644,25 @@ a connection-less dialect, it will emit::
    of PostgreSQL is detected on the connection (or for a connection-less
    dialect).
 
+When using CONCURRENTLY, the Postgresql database requires that the statement
+be invoked outside of a transaction block.   The Python DBAPI enforces that
+even for a single statement, a transaction is present, so to use this
+construct, the DBAPI's "autocommit" mode must be used::
+
+    metadata = MetaData()
+    table = Table(
+        "foo", metadata,
+        Column("id", String))
+    index = Index(
+        "foo_idx", table.c.id, postgresql_concurrently=True)
+
+    with engine.connect() as conn:
+        with conn.execution_options(isolation_level='AUTOCOMMIT'):
+            table.create(conn)
+
+.. seealso::
+
+    :ref:`postgresql_isolation_level`
 
 .. _postgresql_index_reflection: