- add a note how to generate pg10 IDENTITY for now

Change-Id: I22dbf6ba322904a80c6df46f6a31daa2fcc1f946

1 files changed, 36 insertions, 2 deletions

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index f911ac167..641c62a6a 100644
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -11,8 +11,8 @@ r"""
 
 .. _postgresql_sequences:
 
-Sequences/SERIAL
-----------------
+Sequences/SERIAL/IDENTITY
+-------------------------
 
 PostgreSQL supports sequences, and SQLAlchemy uses these as the default means
 of creating new primary key values for integer-based primary key columns. When
@@ -43,6 +43,40 @@ case.
 To force the usage of RETURNING by default off, specify the flag
 ``implicit_returning=False`` to :func:`.create_engine`.
 
+Postgresql 10 IDENTITY columns
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Postgresql 10 has a new IDENTITY feature that supersedes the use of SERIAL.
+Built-in support for rendering of IDENTITY is not available yet, however the
+following compilation hook may be used to replace occurrences of SERIAL with
+IDENTITY::
+
+    from sqlalchemy.schema import CreateColumn
+    from sqlalchemy.ext.compiler import compiles
+
+
+    @compiles(CreateColumn, 'postgresql')
+    def use_identity(element, compiler, **kw):
+        text = compiler.visit_create_column(element, **kw)
+        text = text.replace("SERIAL", "INT GENERATED BY DEFAULT AS IDENTITY")
+        return text
+
+Using the above, a table such as::
+
+    t = Table(
+        't', m,
+        Column('id', Integer, primary_key=True),
+        Column('data', String)
+    )
+
+Will generate on the backing database as::
+
+    CREATE TABLE t (
+        id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+        data VARCHAR,
+        PRIMARY KEY (id)
+    )
+
 .. _postgresql_isolation_level:
 
 Transaction Isolation Level