[#26648] YSQL: Recommend read committed isolation

Summary:
### Motivation

Consider the following scenario

Setup:

```
CREATE TABLE tokens(token INT);
INSERT INTO tokens SELECT i FROM GENERATE_SERIES(1, 100) i;
```

The following txn faces a read restart error when there is a concurrent insert:

```
BEGIN ISOLATION LEVEL READ COMMITTED;
SELECT token FROM tokens LIMIT 1;
SELECT token FROM tokens ORDER BY token; <--- read restart error here.
ROLLBACK;
```

Concurrent insert:

```
INSERT INTO tokens SELECT i FROM GENERATE_SERIES(200, 300) i;
```

Error:

```
2025-04-03 15:37:39.463 UTC [321440] ERROR:  Restart read required at: { read: { days: 20181 time: 15:37:39.460582 } local_limit: { days: 20181 time: 15:37:39.460582 } global_limit: <min> in_txn_limit: <max> serial_no: 0 } (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
2025-04-03 15:37:39.463 UTC [321440] STATEMENT:  SELECT token FROM tokens ORDER BY token
```

The error recommends increasing ysql_output_buffer_size if this is the first statement of a repeatable read txn. This is not the first statement of the txn. However, thats difficult to read. Users often miss the condition and increase the buffer size.

Moreover, the error message does not provide a good recommendation when the error is on a non-first statement of repeatable read.

### Fix

Change recommendation to consider read committed isolation level.

```
2025-04-03 15:28:26.175 UTC [309395] ERROR:  Restart read required at: { read: { days: 20181 time: 15:28:26.171916 } local_limit: { days: 20181 time: 15:28:26.171916 } global_limit: <min> in_txn_limit: <max> serial_no: 0 } (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level. Please turn on yb_enable_read_committed_isolation to enable READ COMMITTED isolation level.)
2025-04-03 15:28:26.175 UTC [309395] STATEMENT:  SELECT token FROM tokens ORDER BY token
```

Fixes #26648
Jira: DB-16025

Test Plan:
Jenkins

```
./yb_build.sh --cxx-test pg_debug_read_restarts-test
./yb_build.sh --java-test TestPgRegressIsolationWithoutWaitQueues#testPgRegress
./yb_build.sh --java-test TestPgRegressWaitQueues#testPgRegress
./yb_build.sh --java-test TestPgRegressIsolation#testPgRegress
./yb_build.sh --java-test TestPgRegressIsolation#testPgRegressWithDelayedTxnApply
```

Backport-through: 2024.2

Reviewers: pjain, smishra

Reviewed By: pjain

Subscribers: yql

Differential Revision: https://phorge.dev.yugabyte.com/D42974

Author: pao214

src/postgres/src/backend/access/transam/xact.c

@@ -3217,13 +3217,6 @@ YBStartTransactionCommandInternal(bool yb_skip_read_committed_internal_savepoint
 			 */
 			if (YBTransactionsEnabled() && IsYBReadCommitted() && !yb_skip_read_committed_internal_savepoint)
 			{
-				/*
-				 * Reset field ybDataSentForCurrQuery (indicates whether any data was sent as part of the
-				 * current query). This helps track if automatic restart of a query is possible in
-				 * READ COMMITTED isolation level.
-				 */
-				s->ybDataSentForCurrQuery = false;
-
 				/*
 				 * Create a new internal sub txn before any execution. This aids in rolling back any changes
 				 * before restarting the statement.

src/postgres/src/backend/tcop/postgres.c

@@ -4825,6 +4825,27 @@ yb_is_retry_possible(ErrorData *edata, int attempt,
 		return false;
 	}
 
+	/*
+	 * This check is not strictly necessary.
+	 * However, recommend read committed isolation level when
+	 * increasing ysql_output_buffer_size is ineffective.
+	 *
+	 * This scenario is retryable if isolation is read committed instead.
+	 */
+	if (!IsYBReadCommitted() && YBIsDataSent() && !YBIsDataSentForCurrQuery())
+	{
+		const char *retry_err = "";
+
+		retry_err = psprintf("query layer retry isn't possible because "
+							 "this is not the first command in the "
+							 "transaction. Consider using READ COMMITTED "
+							 "isolation level.");
+		edata->message = psprintf("%s (%s)", edata->message, retry_err);
+		if (yb_debug_log_internal_restarts)
+			elog(LOG, "%s", retry_err);
+		return false;
+	}
+
 	/*
 	 * In REPEATABLE READ and SERIALIZABLE isolation levels, retrying involves restarting the whole
 	 * transaction. So, we can only retry if no data has been sent to the external client as part of
@@ -4838,10 +4859,7 @@ yb_is_retry_possible(ErrorData *edata, int attempt,
 		(IsYBReadCommitted() && YBIsDataSentForCurrQuery()))
 	{
 		const char *retry_err = ("query layer retry isn't possible because "
-								 "data was already sent, if this is the read "
-								 "committed isolation (or) the first "
-								 "statement in repeatable read/ serializable "
-								 "isolation transaction, consider increasing "
+								 "data was already transferred, consider increasing "
 								 "the tserver gflag ysql_output_buffer_size");
 
 		edata->message = psprintf("%s (%s)", edata->message, retry_err);
@@ -6254,6 +6272,8 @@ PostgresMain(const char *dbname, const char *username)
 				yb_catalog_version_type != CATALOG_VERSION_CATALOG_TABLE)
 				yb_catalog_version_type = CATALOG_VERSION_UNSET;
 			yb_is_multi_statement_query = false;
+			/* New Query => Did not sent any data for the current query. */
+			YBMarkDataNotSentForCurrQuery();
 		}
 
 		switch (firstchar)

src/postgres/src/test/isolation/expected/yb.orig.deadlock.out

@@ -34,7 +34,7 @@ step s3_upd_all_k_except_2: UPDATE test SET v=3 where k!=2; <waiting ...>
 step s1c: COMMIT;
 step s2_upd_all_k_except_1: <... completed>
 step s3_upd_all_k_except_2: <... completed>
-ERROR:  deadlock detected (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  deadlock detected (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s2c: COMMIT;
 step s3c: COMMIT;
 step s1_select: SELECT * FROM test ORDER BY k;
@@ -70,7 +70,7 @@ step s2_upd_k1: UPDATE test SET v=2 WHERE k=1;
 step s3_upd_k2: UPDATE test SET v=3 WHERE k=2;
 step s2_upd_all_k_except_1: UPDATE test SET v=2 where k!=1; <waiting ...>
 step s3_upd_all_k_except_2: UPDATE test SET v=3 where k!=2;
-ERROR:  deadlock detected (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  deadlock detected (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s2_upd_all_k_except_1: <... completed>
 step s2c: COMMIT;
 step s3c: COMMIT;

src/postgres/src/test/isolation/expected/yb.orig.fk-relationship.out

@@ -96,7 +96,7 @@ step s1_serializable_txn: BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
 step s1_update_fk1: UPDATE tb SET fk1 = 10 WHERE k = 1;
 step s2_update_fk2: UPDATE tb SET fk2 = 10 WHERE k = 1;
 step s1_commit: COMMIT;
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_select_tb: SELECT * FROM tb;
 k|fk1|fk2
 -+---+---
@@ -139,7 +139,7 @@ step s1_repeatable_read_txn: BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
 step s1_update_fk1: UPDATE tb SET fk1 = 10 WHERE k = 1;
 step s2_update_fk2: UPDATE tb SET fk2 = 10 WHERE k = 1;
 step s1_commit: COMMIT;
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_select_tb: SELECT * FROM tb;
 k|fk1|fk2
 -+---+---

src/postgres/src/test/isolation/expected/yb.orig.modify-transaction-characteristics.out

@@ -21,7 +21,7 @@ step s1_update: UPDATE test SET v=v+1 WHERE k=1;
 step s2_update: UPDATE test SET v=v*2 WHERE k=1; <waiting ...>
 step s1_commit: COMMIT;
 step s2_update: <... completed>
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s2_rollback: ROLLBACK;
 step s2_select: SELECT * FROM test;
 k|v
@@ -51,7 +51,7 @@ step s1_update: UPDATE test SET v=v+1 WHERE k=1;
 step s2_update: UPDATE test SET v=v*2 WHERE k=1; <waiting ...>
 step s1_commit: COMMIT;
 step s2_update: <... completed>
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s2_rollback: ROLLBACK;
 step s2_select: SELECT * FROM test;
 k|v
@@ -83,7 +83,7 @@ step s1_update: UPDATE test SET v=v+1 WHERE k=1;
 step s2_update: UPDATE test SET v=v*2 WHERE k=1; <waiting ...>
 step s1_commit: COMMIT;
 step s2_update: <... completed>
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s2_rollback: ROLLBACK;
 step s2_select: SELECT * FROM test;
 k|v
@@ -113,7 +113,7 @@ step s1_update: UPDATE test SET v=v+1 WHERE k=1;
 step s2_update: UPDATE test SET v=v*2 WHERE k=1; <waiting ...>
 step s1_commit: COMMIT;
 step s2_update: <... completed>
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s2_rollback: ROLLBACK;
 step s2_select: SELECT * FROM test;
 k|v
@@ -259,7 +259,7 @@ k|v
 
 step s1_update: UPDATE test SET v=v+1 WHERE k=1; <waiting ...>
 step s2_update: UPDATE test SET v=v*2 WHERE k=1;
-ERROR:  deadlock detected (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  deadlock detected (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_update: <... completed>
 step s1_commit: COMMIT;
 step s2_rollback: ROLLBACK;
@@ -289,7 +289,7 @@ k|v
 
 step s1_update: UPDATE test SET v=v+1 WHERE k=1; <waiting ...>
 step s2_update: UPDATE test SET v=v*2 WHERE k=1;
-ERROR:  deadlock detected (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  deadlock detected (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_update: <... completed>
 step s1_commit: COMMIT;
 step s2_rollback: ROLLBACK;
@@ -321,7 +321,7 @@ k|v
 
 step s1_update: UPDATE test SET v=v+1 WHERE k=1; <waiting ...>
 step s2_update: UPDATE test SET v=v*2 WHERE k=1;
-ERROR:  deadlock detected (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  deadlock detected (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_update: <... completed>
 step s1_commit: COMMIT;
 step s2_rollback: ROLLBACK;
@@ -351,7 +351,7 @@ k|v
 
 step s1_update: UPDATE test SET v=v+1 WHERE k=1; <waiting ...>
 step s2_update: UPDATE test SET v=v*2 WHERE k=1;
-ERROR:  deadlock detected (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  deadlock detected (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_update: <... completed>
 step s1_commit: COMMIT;
 step s2_rollback: ROLLBACK;

src/postgres/src/test/isolation/expected/yb.orig.only-abort-sub-txn.out

@@ -19,7 +19,7 @@ step s1_pick_read_time: SELECT * FROM tbl;
 step s2_update_conflicting_key: UPDATE tbl SET v = 2 WHERE k = 1;
 step s1_savepoint_a: SAVEPOINT a;
 step s1_update_conflicting_key: UPDATE tbl SET v = 3 WHERE k = 1;
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_rollback_to_a: ROLLBACK TO a;
 step s1_update_non_conflicting_key: UPDATE tbl SET v = 3 WHERE k = 2;
 step s1_commit: COMMIT;

src/postgres/src/test/isolation/expected/yb.orig.user-managed-constraint.out

@@ -67,7 +67,7 @@ step s1_serializable_txn: BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
 step s1_update: UPDATE t SET v1 = add_with_limit(v1, v2, 35) WHERE k = 1;
 step s2_update: UPDATE t SET v2 = add_with_limit(v2, v1, 35) WHERE k = 1;
 step s1_commit: COMMIT;
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_select: select *, v1 + v2 from t;
 k|v1|v2|?column?
 -+--+--+--------
@@ -84,7 +84,7 @@ step s1_repeatable_read_txn: BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
 step s1_update: UPDATE t SET v1 = add_with_limit(v1, v2, 35) WHERE k = 1;
 step s2_update: UPDATE t SET v2 = add_with_limit(v2, v1, 35) WHERE k = 1;
 step s1_commit: COMMIT;
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_select: select *, v1 + v2 from t;
 k|v1|v2|?column?
 -+--+--+--------
@@ -193,7 +193,7 @@ step s2_update_case:
   UPDATE t SET v2 = CASE WHEN v1 + v2 < 35 THEN v1 + v2 ELSE 0 END WHERE k = 1;
 
 step s1_commit: COMMIT;
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_select: select *, v1 + v2 from t;
 k|v1|v2|?column?
 -+--+--+--------
@@ -214,7 +214,7 @@ step s2_update_case:
   UPDATE t SET v2 = CASE WHEN v1 + v2 < 35 THEN v1 + v2 ELSE 0 END WHERE k = 1;
 
 step s1_commit: COMMIT;
-ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because data was already sent, if this is the read committed isolation (or) the first statement in repeatable read/ serializable isolation transaction, consider increasing the tserver gflag ysql_output_buffer_size)
+ERROR:  could not serialize access due to concurrent update (query layer retry isn't possible because this is not the first command in the transaction. Consider using READ COMMITTED isolation level.)
 step s1_select: select *, v1 + v2 from t;
 k|v1|v2|?column?
 -+--+--+--------

src/yb/yql/pgwrapper/CMakeLists.txt

@@ -131,6 +131,7 @@ ADD_YB_TEST(pg_create_database-test)
 ADD_YB_TEST(pg_ddl_atomicity-test)
 ADD_YB_TEST(pg_ddl_atomicity_stress-test)
 ADD_YB_TEST(pg_ddl_concurrency-test)
+ADD_YB_TEST(pg_debug_read_restarts-test)
 ADD_YB_TEST(pg_drop_column_test)
 ADD_YB_TEST(pg_export_snapshot-test)
 ADD_YB_TEST(pg_explicit_lock-test)

src/yb/yql/pgwrapper/pg_debug_read_restarts-test.cc

@@ -0,0 +1,45 @@
+// Copyright (c) YugabyteDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+// in compliance with the License.  You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software distributed under the License
+// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+// or implied.  See the License for the specific language governing permissions and limitations
+// under the License.
+//
+
+#include "yb/yql/pgwrapper/libpq_utils.h"
+#include "yb/yql/pgwrapper/pg_mini_test_base.h"
+
+namespace yb::pgwrapper {
+
+class PgDebugReadRestartsTest : public PgMiniTestBase {
+ protected:
+  size_t NumTabletServers() override {
+    return 3;
+  }
+};
+
+TEST_F(PgDebugReadRestartsTest, RecommendReadCommitted) {
+  auto setup_conn = ASSERT_RESULT(Connect());
+  ASSERT_OK(setup_conn.Execute("DROP TABLE IF EXISTS tokens"));
+  ASSERT_OK(setup_conn.Execute("CREATE TABLE tokens(token INT)"));
+  ASSERT_OK(setup_conn.Execute("INSERT INTO tokens SELECT i FROM GENERATE_SERIES(1, 100) i"));
+
+  auto read_conn = ASSERT_RESULT(Connect());
+  auto insert_conn = ASSERT_RESULT(Connect());
+  ASSERT_OK(read_conn.StartTransaction(SNAPSHOT_ISOLATION));
+  auto rows = ASSERT_RESULT(read_conn.FetchRows<int32_t>("SELECT token FROM tokens LIMIT 1"));
+  ASSERT_OK(insert_conn.Execute("INSERT INTO tokens SELECT i FROM GENERATE_SERIES(200, 300) i"));
+  auto result = read_conn.FetchRows<int32_t>("SELECT token FROM tokens ORDER BY token");
+  ASSERT_NOK(result);
+  auto error_string = result.status().ToString();
+  // Recommend read committed isolation level
+  ASSERT_STR_CONTAINS(error_string, "Consider using READ COMMITTED");
+  ASSERT_OK(read_conn.RollbackTransaction());
+}
+
+} // namespace yb::pgwrapper