From e1153d869e154798fbcb82dafa113222a06f1b38 Mon Sep 17 00:00:00 2001
From: Charles Leifer <coleifer@gmail.com>
Date: Mon, 22 Apr 2024 13:15:47 -0500
Subject: [PATCH] Docs clarification and test cleanup.

Fixes #2876
---
 CHANGELOG.md    | 21 ++++++++++++++++++++-
 tests/models.py |  4 ----
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b406f5753..353f3ee65 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -211,7 +211,7 @@ class MyModel(db.Model):
 
 Rollback behavior change in commit ab43376697 (GH #2026). Peewee will no longer
 automatically return the cursor `rowcount` for certain bulk-inserts.  This
-should only affect users of MySQL and Sqlite who relied on a bulk INSERT
+should mainly affect users of MySQL and Sqlite who relied on a bulk INSERT
 returning the `rowcount` (as opposed to the cursor's `lastrowid`). The
 `rowcount` behavior is still available chaining the ``as_rowcount()`` method:
 
@@ -233,6 +233,25 @@ last_id = query.execute()
 rows_inserted = query.as_rowcount().execute()
 ```
 
+Additionally, in previous versions specifying an empty `.returning()` with
+Postgres would cause the rowcount to be returned. For Postgres users who wish
+to receive the rowcount:
+
+```python
+# NOTE: this change only affects Postgresql.
+db = PostgresqlDatabase(...)
+
+# Previously, an empty returning() would return the rowcount.
+query = User.insert_many(...)  # Bulk insert.
+query = User.insert_from(...)  # Bulk insert (INSERT INTO .. SELECT FROM).
+
+# Old behavior:
+# rows_inserted = query.returning().execute()
+
+# To get the rows inserted in 3.15 and newer:
+rows_inserted = query.as_rowcount().execute()
+```
+
 This release contains a fix for a long-standing request to allow data-modifying
 queries to support CTEs. CTEs are now supported for use with INSERT, DELETE and
 UPDATE queries - see #2152.
diff --git a/tests/models.py b/tests/models.py
index 5271eeab2..15ed41ebb 100644
--- a/tests/models.py
+++ b/tests/models.py
@@ -421,8 +421,6 @@ def test_insert_rowcount(self):
         User.create(username='u0')  # Ensure that last insert ID != rowcount.
 
         iq = User.insert_many([(u,) for u in ('u1', 'u2', 'u3')])
-        if IS_POSTGRESQL or IS_CRDB:
-            iq = iq.returning()
         self.assertEqual(iq.as_rowcount().execute(), 3)
 
         # Now explicitly specify empty returning() for all DBs.
@@ -433,8 +431,6 @@ def test_insert_rowcount(self):
                  .select(User.username.concat('-x'))
                  .where(User.username.in_(['u1', 'u2'])))
         iq = User.insert_from(query, ['username'])
-        if IS_POSTGRESQL or IS_CRDB:
-            iq = iq.returning()
         self.assertEqual(iq.as_rowcount().execute(), 2)
 
         query = (User