Skip to content

6 Utilities

Changes to configure, initdb, backup, restore, upgrade, psql, and maintenance tools.
GASource pages: PDF 66-80Original PDF on GitHub

PDF page 66

Describes the major enhancements of utility commands.

3.4.1 configure

The “–disable-strong-random” option has been removed from the “configure” command that is run when installing PostgreSQL from source code.

3.4.2 initdb

The initdb command now refers to the /etc/localtime file when determining the time zone of a database cluster. This file is referenced when the environment variable TZ is not specified.

3.4.3 oid2name

The oid2name command has been reviewed for options, and long-named options are now available.

ShortoptionAddedlong-namedoptionDescription
-f–filenodeFile node specification
-i–indexesInclude index and sequence
-o–oidSpecify OID
-q–quietOmit header
-s–tablespacesShow tablespace OID
-S–system-objectsContains system objects
-t–tableSpecify table name
-x–extendedOutput additional information
-d–dbnameDatabase to connect to
-h–hostHostname to connect to (-H option is deprecated)
-p–portPort number to connect to
-U–usernameDatabase username
Table 22 Added options

PDF page 67

3.4.4 pg_basebackup

The behavior of the pg_basebackup command has been changed when the –write-recovery-conf parameter (-R) is specified. The standby.signal file is automatically created in the backup destination folder, and the primary_conninfo parameter is added to the postgresql.auto.conf file. This behavior is only performed when connecting to a PostgreSQL 12 or later instance.

Example 77 -R parameter of pg_basebackup command
$ pg_basebackup -D back -R
$ ls back
backup_label      log           pg_ident.conf  pg_replslot
pg_stat_tmp  PG_VERSION            postgresql.conf
base              pg_commit_ts  pg_logical     pg_serial
pg_subtrans  pg_wal                standby.signal
current_logfiles  pg_dynshmem   pg_multixact   pg_snapshots
pg_tblspc    pg_xact
global            pg_hba.conf   pg_notify      pg_stat
pg_twophase  postgresql.auto.conf
$ cat back/postgresql.auto.conf
# Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.
primary_conninfo
=
'user=postgres
passfile=''/home/postgres/.pgpass''
port=5432
sslmode=disable
sslcompression=0 gssencmode=disable target_session_attrs=any'
primary_slot_name = 'slot1'
$

3.4.5 pg_checksums

The command pg_verify_checksums, which checks checksum integrity, has been renamed to pg_checksums. In addition to checking the integrity of checksums, it is now possible to change checksum activation/deactivation.

PDF page 68

Example 78 Usage of pg_checksums command
$ pg_checksums --help
pg_checksums enables, disables, or verifies data checksums in a
PostgreSQL database cluster.
Usage:
  pg_checksums [OPTION]... [DATADIR]
Options:
 [-D, --pgdata=]DATADIR    data directory
  -c, --check              check data checksums (default)
  -d, --disable            disable data checksums
  -e, --enable             enable data checksums
  -f, --filenode=FILENODE  check only relation with specified
filenode
  -N, --no-sync            do not wait for changes to be written
safely to disk
  -P, --progress           show progress information
  -v, --verbose            output verbose messages
  -V, --version            output version information, then exit
  -?, --help               show this help, then exit
If no data directory (DATADIR) is specified, the environment
variable PGDATA
is used.
Report bugs to <pgsql-bugs@lists.postgresql.org>.
$
 Specify the --check the option to check the integrity of the block. If the consistency error is confirmed,
the command ends with a return value of 1.

PDF page 69

Example 79 Integrity check
$ pg_checksums -D data --check
Checksum operation completed
Files scanned:  973
Blocks scanned: 11187
Bad checksums:  0
Data checksum version: 1
$ echo $?
0
$
 Specify the --enable option (--disable the option to disable) to enable database cluster checksums.
Even if the checksum is enabled, a consistency check is performed.
Example 80 Enable integrity check
$ pg_checksums -D data --enable
Checksum operation completed
Files scanned:  973
Blocks scanned: 11187
pg_checksums: syncing data directory
pg_checksums: updating control file
Checksums enabled in cluster
$
 This command must be run with the instance successfully shut down. If an instance terminates
abnormally or cannot be executed for a database cluster during the instance is up.
Example 81 Abend an instance and enable integrity
$ pg_ctl -D data -m immediate stop
waiting for server to shut down.... done server stopped
$ pg_checksums -D data --check
pg_checksums: cluster must be shut down
$

PDF page 70

Specify the –progress option (-P option) to display the processing status.

Example 82 Display command execution status
$ pg_checksums -D data --check --progress
87/87 MB (100%) computed
Checksum operation completed
Files scanned:  973
Blocks scanned: 11187
Bad checksums:  0
Data checksum version: 1

3.4.6 pg_ctl

The following feature has been added to the pg_ctl command.

logrotate option

The parameter logrotate for log rotation has been added to the pg_ctl command. In the past, it was necessary to send a SIGHUP signal to the logger process. To suppress the message, specify the -s parameter at the same time.

Example 83 pg_ctl logrotate command
$ pg_ctl -D data logrotate
server signaled to rotate log file
$

3.4.7 pg_dump

The following options have been added to the pg_dump command.

–on-conflict-do-nothing option

This option automatically assigns the ON CONFLICT DO NOTHING clause to the output INSERT statement. Must be specified with the –inserts option or –column-inserts option.

PDF page 71

Example 84 --on-conflict-do-nothing option
$ pg_dump -t data1 --inserts --on-conflict-do-nothing
--
-- PostgreSQL database dump
…
-- Data for Name: data1; Type: TABLE DATA; Schema: public; Owner: demo
--
INSERT INTO public.data1 VALUES (1, 'data1') ON CONFLICT DO NOTHING;
INSERT INTO public.data1 VALUES (2, 'data1') ON CONFLICT DO NOTHING;
…
–extra-float-digits option

If an integer value is specified for this parameter, the “SET extra_float_digits = specified value” statement is executed before data acquisition using the pg_dump command. The dump file does not contain SET statements. The range of values that can be specified is -15 to 3. If a non-numeric value is specified, it is regarded as 0.

–rows-per-insert option

This option is used with the –inserts option. Multiple tuples can be inserted in a single INSERT statement. The range of values is 1 to 2,147,483,647.

PDF page 72

Example 85 -rows-per-insert option
$ pg_dump -t data1 --inserts --rows-per-insert=2
--
-- PostgreSQL database dump
…
-- Data for Name: data1; Type: TABLE DATA; Schema: public; Owner: postgres
--
INSERT INTO public.data1 VALUES
        (1, 'data1'),
        (2, 'data1');
INSERT INTO public.data1 VALUES
        (3, 'data1'),
        (4, 'data1');
…

3.4.8 pg_dumpall

The following options have been added to the pg_dumpall command.

–extra-float-digits option

If an integer value is specified for this parameter, the “SET extra_float_digits = specified value” statement is executed before data acquisition using the pg_dumpall command. The dump file does not contain SET statements. The range of values that can be specified is -15 to 3. If a non-numeric value is specified, it is regarded as 0.

–exclude-database option

In PostgreSQL 12, the –exclude-database option has been added. This option specifies which databases to exclude from backup. When specifying multiple databases, use the same pattern as for the psql command. It is also possible to specify the same option multiple times. In the following example, demodb1 and demodb2 are specified as excluded databases.

Example 86 --exclude-database option
$ pg_dumpall --exclude-database='demodb[12]' -f alldump.sql

PDF page 73

–oids

This option has been removed.

Additional comments

Comments have been added to the output file for user settings (ALTER USER SET statement) and database settings.

Example 87 Additional comments
-- User Configurations
-- User Config {User_name}
-- Databases
-- Database {Database_name} dump

3.4.9 pg_rewind

The –no-sync option which does not execute sync system calls for storage has been added to the pg_rewind command.

Example 88 pg_rewind command
$ pg_rewind --help
pg_rewind resynchronizes a PostgreSQL cluster with another copy of the
cluster.
Usage:
  pg_rewind [OPTION]...
Options:
  -D, --target-pgdata=DIRECTORY  existing data directory to modify
      --source-pgdata=DIRECTORY  source data directory to synchronize with
      --source-server=CONNSTR    source server to synchronize with
  -n, --dry-run                  stop before modifying anything
  -N, --no-sync                  do not wait for changes to be written
                                 safely to disk
  -P, --progress                 write progress messages
      --debug                    write a lot of debug messages
…

PDF page 74

3.4.10 pg_restore

When specifying standard output as the data output destination, specify “-f -”.

3.4.11 pg_upgrade

The following options have been added to the pg_upgrade command.

–socketdir option

The –socketdir option (or -s option) that specifies the directory for creating a local socket has been added.

–clone option

The –clone option performs fast cloning using the “reflink” feature. This feature is available only on some operating systems and file systems.

Example 89 pg_upgrade command
$ pg_upgrade --help
pg_upgrade upgrades a PostgreSQL cluster to a different major version.
Usage:
  pg_upgrade [OPTION]...
Options:
  -b, --old-bindir=BINDIR       old cluster executable directory
…
  -r, --retain                  retain SQL and log files after success
  -s, --socketdir=DIR           socket directory to use (default CWD)
  -U, --username=NAME           cluster superuser (default "postgres")
  -v, --verbose                 enable verbose internal logging
  -V, --version                 display version information, then exit
  --clone                       clone instead of copying files to new
cluster
  -?, --help                    show this help, then exit
…

PDF page 75

3.4.12 psql

The following features have been added to the psql command.

CSV format output

Output format from psql command can be changed to CSV format. It can be changed in any of the following ways.

Specify psql command parameter –csv
Execute “\pset format csv” command from within the psql command

The default value of column separator is a comma (,), but it can be changed by “\pset csv_fieldsep” command. If the output value contains delimiters, the value is enclosed in double quotation marks ("). Column titles can be suppressed with “\pset tuples_only on” command.

Example 90 \pset format csv command
postgres=> \pset format csv
Output format is csv.
postgres=> \pset csv_fieldsep
Field separator for CSV is ",".
postgres=> SELECT * FROM data1 ;
c1,c2
<- Title
1,ABC
2,"AB,C"
<- If the data contains column separators.
2,"AB""C"
<- When the data contains double quotations.
Display of partition table

The partition table is now output explicitly when the \d command is executed.

PDF page 76

Example 91 \d command
postgres=> CREATE TABLE part1(c1 NUMERIC, c2 VARCHAR(10)) PARTITION
                 BY LIST(c1) ;
CERATE TABLE
postgres=> \d part1
                Partitioned table "public.part1"
 Column |         Type          | Collation | Nullable | Default
--------+-----------------------+-----------+----------+---------
 c1     | numeric               |           |          |
 c2     | character varying(10) |           |          |
Partition key: LIST (c1)
Number of partitions: 0
 Tablespace of partitioned indexes is now displayed.
Example 92 \d command
postgres=> CREATE INDEX idx1_part1 ON part1(c2) TABLESPACE ts1 ;
CREATE INDEX
postgres=> \d idx1_part1
       Partitioned index "public.idx1_part1"
 Column |         Type          | Key? | Definition
--------+-----------------------+------+------------
 c2     | character varying(10) | yes  | c2
btree, for table "public.part1"
Tablespace: "ts1"
Display object privilege

Partitioned tables are now specified in the list of object privileges.

PDF page 77

Example 93 \z command
postgres=> CREATE TABLE part1(c1 NUMERIC, c2 VARCHAR(10)) PARTITION BY
LIST (c1) ;
CREATE TABLE
postgres=> CREATE TABLE part1v1 PARTITION OF part1 FOR VALUES IN (10) ;
CREATE TABLE
postgres=> \z
                                    Access privileges
 Schema |  Name   |       Type        | Access privileges | Column
privileges | Policies
--------+---------+-------------------+-------------------+-------------
------+----------
 public | part1   | partitioned table |                   |                   |
 public | part1v1 | table             |                   |                   |
(2 rows)
Display connection information

The TCP / IP address is now output when the \conninfo command is executed.

Example 94 \conninfo command
$ psql -p 5432 -h pghost1 -d postgres -U demo
Password for user demo: <<PASSWORD>>
psql (12.0)
Type "help" for help.
postgres=> \conninfo
You are connected to database "postgres" as user "demo" on host
"pghost1" (address "192.168.1.101") at port "5432".
postgres=>
SQLSTATE with VERBOSITY

SQLSTATE can now be specified in the “\set VERBOSITY” command.

PDF page 78

Example 95 \set VERBOSITY command
postgres=> \set VERBOSITY sqlstate
postgres=> SELECT * FROM not_exists ;
psql: ERROR:  42P01
Display of partition table

The “\dP” command to display only the partition table has been added.

Example 96 \dP command
ostgres=> CREATE TABLE part1(c1 INT, c2 VARCHAR(2)) PARTITION BY RANGE(c1) ;
CREATE TABLE
postgres=> CREATE TABLE part1v1 PARTITION OF part1 FOR VALUES FROM (0) TO (1000000) ;
CREATE TABLE
postgres=> \dP
             List of partitioned relations
 Schema | Name  | Owner |       Type        | On table
--------+-------+-------+-------------------+----------
 public | part1 | demo  | partitioned table |
(1 row)
postgres=> \dP+
                          List of partitioned relations
 Schema | Name  | Owner |       Type        | On table | Total size | Description
--------+-------+-------+-------------------+----------+------------+-------------
 public | part1 | demo  | partitioned table |          | 0 bytes    |
(1 row)
Display of manual URL

Specifying DDL with the \h command now displays the URL of the corresponding manual.

PDF page 79

Example 97 \h command
postgres=> \h CREATE SEQUENCE
Command:     CREATE SEQUENCE
Description: define a new sequence generator
Syntax:
CREATE [ TEMPORARY | TEMP ] SEQUENCE [ IF NOT EXISTS ] name
    [ AS data_type ]
    [ INCREMENT [ BY ] increment ]
    [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ]
    [ START [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ]
    [ OWNED BY { table_name.column_name | NONE } ]
URL: https://www.postgresql.org/docs/12/sql-createsequence.html

3.4.13 vacuumdb

The following options have been added to the vacuumdb command.

–disable-page-skipping option

This option is for executing a VACUUM (DISABLE_PAGE_SKIPPING) statement from a command line. This option can be specified for PostgreSQL 9.6 or later instances.

–skip-locked option

This option is for executing a VACUUM (SKIPP_LOCKED) statement from a command line. This option can be specified for PostgreSQL 12 or later instances.

Example 98 Execute against old version
$ vacuumdb -h remhost11 -d postgres -U postgres --skip-locked
vacuumdb: error: cannot use the "skip-locked" option on server
versions older than PostgreSQL 12
–min-mxid-age option

Only execute the vacuum or analyze commands on tables with a multixact ID age of at least specified age.

PDF page 80

–min-xid-age option

Only execute the vacuum or analyze commands on tables with a transaction ID age of at least specified age.

3.4.14 vacuumlo

The vacuumlo command now has a long name option available.

ShortoptionAddedlong-namedoptionDescription
-l–limitThe upper limit of objects to delete
-n–dry-runNot actually run
-v–verboseThe output of additional information
-h–hostConnect host
-p–portConnect port number
-U–usernameConnect user name
-w–no-passwordDo not output password prompt
-W–passwordForce password input
Table 23 Added long-name option