Re: [PATCH] doc: clarify psql \watch minimum row behavior

From: R Sri Vishnu <sri207881(at)gmail(dot)com>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: [PATCH] doc: clarify psql \watch minimum row behavior
Date: 2026-10-31 12:14:56
Message-ID: CANM6wF+sj0ueQf89G39=4oGCi3WksA-FatjFJeQvxZjY4qYQbg@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

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(at)gmail(dot)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

On Sat, Oct 31, 2026 at 5:42 PM R Sri Vishnu <sri207881(at)gmail(dot)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 Vishnu
>
> On Sat, Oct 31, 2026 at 12:25 PM R Sri Vishnu <sri207881(at)gmail(dot)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

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Zhijie Hou 2026-10-31 12:35:15 Re: Add a hook for handling logical decoding messages on subscribers.
Previous Message R Sri Vishnu 2026-10-31 12:12:36 Re: [PATCH] doc: clarify psql \watch minimum row behavior