[4.1.x] Refs #30511 -- Updated docs about auto-incrementing primary keys on PostgreSQL.

Follow up to 2eea361eff58dd98c409c5227064b901f41bd0d6.
Backport of 081871bc20cc8b28481109b8dcadc321e177e6be from main

4 files changed, 17 insertions, 13 deletions

diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt
index df595e947c..ee0707456d 100644
--- a/docs/intro/tutorial02.txt
+++ b/docs/intro/tutorial02.txt
@@ -274,7 +274,7 @@ readability):
     -- Create model Question
     --
     CREATE TABLE "polls_question" (
-        "id" serial NOT NULL PRIMARY KEY,
+        "id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
         "question_text" varchar(200) NOT NULL,
         "pub_date" timestamp with time zone NOT NULL
     );
@@ -282,10 +282,10 @@ readability):
     -- Create model Choice
     --
     CREATE TABLE "polls_choice" (
-        "id" serial NOT NULL PRIMARY KEY,
+        "id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
         "choice_text" varchar(200) NOT NULL,
         "votes" integer NOT NULL,
-        "question_id" integer NOT NULL
+        "question_id" bigint NOT NULL
     );
     ALTER TABLE "polls_choice"
       ADD CONSTRAINT "polls_choice_question_id_c5b4b260_fk_polls_question_id"
@@ -315,10 +315,10 @@ Note the following:
   PostgreSQL to not enforce the foreign key until the end of the transaction.
 
 * It's tailored to the database you're using, so database-specific field types
-  such as ``auto_increment`` (MySQL), ``serial`` (PostgreSQL), or ``integer
-  primary key autoincrement`` (SQLite) are handled for you automatically. Same
-  goes for the quoting of field names -- e.g., using double quotes or
-  single quotes.
+  such as ``auto_increment`` (MySQL), ``bigint PRIMARY KEY GENERATED BY DEFAULT
+  AS IDENTITY`` (PostgreSQL), or ``integer primary key autoincrement`` (SQLite)
+  are handled for you automatically. Same goes for the quoting of field names
+  -- e.g., using double quotes or single quotes.
 
 * The :djadmin:`sqlmigrate` command doesn't actually run the migration on your
   database - instead, it prints it to the screen so that you can see what SQL
diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index 1b8f54495a..2a4e082869 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -258,7 +258,7 @@ This command should produce the following output:
     -- Create model WorldBorder
     --
     CREATE TABLE "world_worldborder" (
-        "id" bigserial NOT NULL PRIMARY KEY,
+        "id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
         "name" varchar(50) NOT NULL,
         "area" integer NOT NULL,
         "pop2005" integer NOT NULL,
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 166835a53b..ed5b65f267 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -296,9 +296,9 @@ live for the duration of the transaction.
 Manually-specifying values of auto-incrementing primary keys
 ------------------------------------------------------------
 
-Django uses PostgreSQL's `SERIAL data type`_ to store auto-incrementing primary
-keys. A ``SERIAL`` column is populated with values from a `sequence`_ that
-keeps track of the next available value. Manually assigning a value to an
+Django uses PostgreSQL's identity columns to store auto-incrementing primary
+keys. An identity column is populated with values from a `sequence`_ that keeps
+track of the next available value. Manually assigning a value to an
 auto-incrementing field doesn't update the field's sequence, which might later
 cause a conflict. For example::
 
@@ -315,7 +315,11 @@ If you need to specify such values, reset the sequence afterward to avoid
 reusing a value that's already in the table. The :djadmin:`sqlsequencereset`
 management command generates the SQL statements to do that.
 
-.. _SERIAL data type: https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL
+.. versionchanged:: 4.1
+
+    In older versions, PostgreSQL’s ``SERIAL`` data type was used instead of
+    identity columns.
+
 .. _sequence: https://www.postgresql.org/docs/current/sql-createsequence.html
 
 Test database templates
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 7e2cc9969f..f984e1b0a5 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -39,7 +39,7 @@ The above ``Person`` model would create a database table like this:
 .. code-block:: sql
 
     CREATE TABLE myapp_person (
-        "id" serial NOT NULL PRIMARY KEY,
+        "id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
         "first_name" varchar(30) NOT NULL,
         "last_name" varchar(30) NOT NULL
     );