[PATCH] doc: clarify psql \watch minimum row behavior
Hi,
This patch is for PostgreSQL master. It clarifies that psql \watch min_rows
displays the final result, even when it contains fewer rows than the
threshold, before stopping. It also documents the positive-integer
requirements for count and min_rows and adds deterministic TAP checks for
the continuing and stopping cases.
The patch is intended for application. It changes documentation and tests
only, with no platform-specific code changes.
Validation: git diff --check passes. PostgreSQL Linux CI is running here:
https://github.com/SriVishnu230707/postgres/actions/runs/41178136735 . I
will update this line with the final result before sending.
Regards,
Sri Vishnu
Correction to my earlier message: I omitted the patch attachment, and the
CI run has now completed.
The attached v1 patch is for PostgreSQL master. All three Linux CI jobs
passed (Meson 64-bit, Meson 32-bit, and Autoconf), including psql/001_basic
on the 64-bit run (140 subtests). The run is at
https://github.com/SriVishnu230707/postgres/actions/runs/41178136735 . git
diff --check also passes.
Sorry for the incomplete first message.
Regards,
Sri Vishnu
On Sat, Oct 31, 2026 at 12:25 PM R Sri Vishnu <sri207881@gmail.com> wrote:
Show quoted text
Hi,
This patch is for PostgreSQL master. It clarifies that psql \watch
min_rows displays the final result, even when it contains fewer rows than
the threshold, before stopping. It also documents the positive-integer
requirements for count and min_rows and adds deterministic TAP checks for
the continuing and stopping cases.The patch is intended for application. It changes documentation and tests
only, with no platform-specific code changes.Validation: git diff --check passes. PostgreSQL Linux CI is running here:
https://github.com/SriVishnu230707/postgres/actions/runs/41178136735 . I
will update this line with the final result before sending.Regards,
Sri Vishnu
The previous two messages omitted the patch file. Here is the complete
v1 patch inline in plain text. All three Linux CI jobs passed:
https://github.com/SriVishnu230707/postgres/actions/runs/41178136735
The exact patch is also downloadable at
https://github.com/SriVishnu230707/postgres/commit/75c740c5d6e40b4f680b62952b797516b87b902d.patch
From 75c740c5d6e40b4f680b62952b797516b87b902d Mon Sep 17 00:00:00 2001
From: SriVishnu230707 <sri207881@gmail.com>
Date: Sat, 31 Oct 2026 12:08:30 +0530
Subject: [PATCH v1] doc: clarify psql watch minimum row behavior
---
doc/src/sgml/ref/psql-ref.sgml | 5 +++++
src/bin/psql/t/001_basic.pl | 13 +++++++++++++
2 files changed, 18 insertions(+)
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 4058caf..8aad5c1 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3938,6 +3938,11 @@ SELECT 1 \bind \sendpipeline
For backwards compatibility,
<replaceable class="parameter">seconds</replaceable> can be specified
with or without an <literal>interval=</literal> prefix.
+ The <literal>count=</literal> option limits the number of executions,
+ while <literal>min_rows=</literal> stops execution when a query result
+ has fewer than the specified number of rows. That final result is
+ displayed before execution stops. Both options require a positive
+ integer.
Each query result is
displayed with a header that includes the <literal>\pset
title</literal>
string (if any), the time as of query start, and the delay interval.
diff --git a/src/bin/psql/t/001_basic.pl b/src/bin/psql/t/001_basic.pl
index 028df33..e12376d 100644
--- a/src/bin/psql/t/001_basic.pl
+++ b/src/bin/psql/t/001_basic.pl
@@ -385,6 +385,19 @@ SELECT 1 \watch c=3',
qr/1\n1\n1/, '\watch with 3 iterations, interval of 0');
# Check \watch minimum row count
+psql_like(
+ $node,
+ 'SELECT 123 \watch c=2 i=0 m=1',
+ qr/123\n123/,
+ '\watch prints both results when minimum row count is met');
+
+my ($watch_ret, $watch_stdout, $watch_stderr) =
+ $node->psql('postgres', 'SELECT 123 \watch c=2 i=0 m=2');
+is($watch_ret, 0, '\watch exits successfully when minimum row count
is not met');
+my @watch_rows = ($watch_stdout =~ /^123$/mg);
+is(scalar @watch_rows, 1, '\watch prints the final result only once');
+is($watch_stderr, '', '\watch does not report an error below minimum
row count');
+
psql_fails_like(
$node,
'SELECT 3 \watch m=x',
--
2.50.1.windows.1
Show quoted text
On Sat, Oct 31, 2026 at 5:42 PM R Sri Vishnu <sri207881@gmail.com> wrote:
Correction to my earlier message: I omitted the patch attachment, and the CI run has now completed.
The attached v1 patch is for PostgreSQL master. All three Linux CI jobs passed (Meson 64-bit, Meson 32-bit, and Autoconf), including psql/001_basic on the 64-bit run (140 subtests). The run is at https://github.com/SriVishnu230707/postgres/actions/runs/41178136735 . git diff --check also passes.
Sorry for the incomplete first message.
Regards,
Sri VishnuOn Sat, Oct 31, 2026 at 12:25 PM R Sri Vishnu <sri207881@gmail.com> wrote:
Hi,
This patch is for PostgreSQL master. It clarifies that psql \watch min_rows displays the final result, even when it contains fewer rows than the threshold, before stopping. It also documents the positive-integer requirements for count and min_rows and adds deterministic TAP checks for the continuing and stopping cases.
The patch is intended for application. It changes documentation and tests only, with no platform-specific code changes.
Validation: git diff --check passes. PostgreSQL Linux CI is running here: https://github.com/SriVishnu230707/postgres/actions/runs/41178136735 . I will update this line with the final result before sending.
Regards,
Sri Vishnu