Feature request: output controls on `source` (verbose + paging)

[kbcmdba]

Feature request: output controls on source (verbose + paging)

source reads and executes statements from a file, but it gives the user
no control over how the output is presented. Two specific gaps that come
up in real workflows:

• Each statement runs silently before its result is shown. No echo of
  the statement itself, so the output stream is just a series of result
  blocks with no visible "what did this come from?" anchor.
• There's no way to opt the output into a pager. Sometimes that's
  exactly right - you want everything in your terminal scrollback or
  piped onward to another tool. Other times you want to read what each
  statement produced and a pager is the natural fit. Today only the
  first mode is available.

Use cases this gets in the way of:

• Forensic / audit replay. Stepping through a SQL file to see exactly
  which statement produced which result row, or which one failed.
• Reviewing scripted DDL. When applying a multi-statement DDL change
  by hand, seeing each CREATE/ALTER/GRANT echo as it lands gives a
  per-statement progress trace. Without it, a partially-applied script
  leaves you guessing where it stopped.
• Sourcing diagnostic queries when you want to read them. A file
  that runs several SELECTs to inspect database state produces
  several output blocks; if any of them is taller than the screen,
  the earlier ones scroll away. Paging makes them reviewable in the
  cases where you want that.
• Teaching / pairing. Walking another person through a script in
  real time benefits from each statement being visible alongside its
  output, potentially one screenful at a time.

The standard mysql client offers parts of this via mysql -vvv for
verbose mode and a pager setting for paging, but at invocation /
session level, not per-source. mycli has no equivalent for verbose
source, so today the workaround is to drop out of mycli, pipe the file
through mysql -vvv ..., and lose mycli's autocomplete /
syntax-highlighting / formatting on the way.

How it could work

Two flags on the existing source command, independent of each other:

source -v filename.sql       # verbose: echo each statement before exec
source -p filename.sql       # paged: stream output through a pager
source -vp filename.sql      # both

-v (verbose): each statement gets echoed (with a clear visual marker,
e.g. a leading -- comment line or a colored prefix) just before the
client executes it. Failed statements still report the error after their
echo, so the trace is linear: [statement] -> [result or error] -> [next statement].

-p (paged): the combined output stream is fed through a pager so long
output is reviewable instead of blasting past the screen. Reasonable
default for the pager invocation: less -SFX
(-S to chop long lines, -F to quit if it fits on one screen,
-X to leave the content visible after quit). Honor the PAGER env var
if set, otherwise fall back to that default.

Both default off; existing source filename.sql behavior stays as it
is today.

A couple of alternative surfaces if positional flags are awkward given
the existing parser:

• Persistent toggles: \set verbose_source on and \set page_source on
  so subsequent source calls behave accordingly.
• Separate commands: \source-v and \source-p.

I don't care which one - the value is the behaviors themselves. Whatever
fits mycli's existing argument handling cleanest.

Compatibility

source without flags keeps its current behavior - silent, unpaged.
Existing scripts and muscle memory work the same as before.

Why mycli specifically

mycli is the daily tool for many of us who need a more capable terminal
client than mysql. The autocomplete + smart formatting + readline
behavior is enough on its own; verbose and paged source would round
out one of the last places where falling back to the bare client is
still required.

Thanks for an excellent tool.

[rolandwalker]

Hi!

We have done a lot of work lately on --batch=<file> from the CLI:

• Stream input from stdin, rather than reading the entire script into memory. #1450
• Add --throttle option for batch mode pauses #1460
• Support a --checkpoint file for batch input #1466
• Add --batch option as an alternative to STDIN #1723
• Add a --progress progress-bar option #1731
• Make --progress and --checkpoint strictly by-statement #1753
• Skip --checkpoint file statements with --resume #1853

but none of that really touches source, yet. We have been thinking about which of these features to bring in to source.

In addition to the limitations you listed, source also currently reads the entire file into memory.

For today, I would recommend trying mycli with --batch from the shell command line. For example, forensic/audit replay is available using the --log or --checkpoint options.

In the future, we will probably improve source.

One correction to your report: source output does go to the pager; it respects the same pager settings as any other command, as defined in ~/.myclirc.

[kbcmdba]

For anyone watching - YES - I used AI to help me file this request (originally). It doesn't diminish from the request; please don't use that against me. :-) Having said that - I appreciate the feedback a bunch, Roland :-) Also - maybe it's appropriate to have a --no-pager option when the user wants to operate without one for a single command.

[kbcmdba]

In case it didn't come across before, I am amazed at the work being done in mycli. It's a vast improvement from what we had before with the straight-up mysql command and goes much farther than mysqlsh. Great job! I've been a MySQL DBA for over 20 years and this is nothing short of fantastic! 🥇

[rolandwalker]

Appreciated!