Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Pager

Page long query results and help text in MariaDB Shell through less, more, or another program with --pager, the pager command, the PAGER variable, and shell.enable_pager.

A pager is a program, such as less or more, that shows long output one screen at a time. MariaDB Shell can send output to a pager so that a wide or long result doesn't scroll past. The pager is off by default and works only in interactive sessions.

What Goes Through the Pager

When a pager is set, the shell sends it:

  • The results of SQL statements that return rows, in SQL mode and from \sql <statement> in Python mode.

  • The output of \help.

  • All text output in Python mode, but only after you call shell.enable_pager(). See Paging Python Output.

Each statement or help request is paged separately. When you quit the pager, the shell shows the prompt again.

Setting the Pager

The pager command is held in the pager shell option. Its value is a command line, so it can include options for the pager program. An empty value means no pager.

Method
Scope

PAGER environment variable

Sets the pager at startup when neither --pager nor a persisted pager option sets it.

--pager=<command>

Sets the pager for the session.

\option --persist pager <command>

Sets the pager for this and future sessions.

\pager <command> or \P <command>

Changes the pager during the session.

\nopager

Turns the pager off for the rest of the session.

mariadb-shell --pager="less -SFX" mariadb://dba@localhost/shop

For results, less -SFX works well: -S keeps long lines unwrapped so that table rows stay aligned and you can scroll sideways with the arrow keys, -F exits right away when the output fits on one screen, and -X leaves the output on the screen after you quit.

Changing the Pager During a Session

\pager (or \P) takes the pager command as the rest of the line. Quotes are optional:

\pager without an argument, or with an empty string (\pager ""), restores the pager that was in effect when the shell started. \nopager turns paging off:

Both commands change the pager option for the current session only. To keep a pager, persist the option:

The pager can be any program that reads standard input. For example, \pager cat -n numbers the output lines, and \pager tee -a /tmp/session.log appends results to a file while still showing them:

Paging Python Output

In Python mode, output isn't paged automatically, because scripts often print progress messages line by line. To page the output of a long report or a loop, turn the pager on with shell.enable_pager() and off with shell.disable_pager():

Between the two calls, all text output except prompts goes to the pager in the pager option. Notes:

  • If you change the pager option while paging is on, the new pager is used from then on.

  • If the pager option is empty, enable_pager() has no visible effect until you set a pager.

  • Switching to SQL mode turns Python paging off, as if you had called disable_pager().

  • disable_pager() doesn't change the pager option, so SQL results are still paged.

  • Both functions have no effect in batch mode.

This page is licensed: GPLv2

Last updated

Was this helpful?