Rework option set of oid2name

oid2name has done little effort to keep an interface consistent with
other binary utilities:
- -H was used instead of -h/-host.  This option is now marked as
deprecated, still its output is accepted to be backward-compatible.
- -P has been removed from the code, and was still documented.
- All options gain long aliases, making connection options more similar
to other binaries.
- Document environment variables which could be used: PGHOST, PGPORT and
PGUSER.

A basic set of TAP tests is added on the way, and documentation is
cleaned up to be more consistent with other things.

Author: Tatsuro Yamada
Reviewed-by: Michael Paquier
Discussion: https://postgr.es/m/c7e7f25c-1747-cd0f-9335-390bc97b2db5@lab.ntt.co.jp

diff --git a/contrib/oid2name/.gitignore b/contrib/oid2name/.gitignore
index fdefde108ddd1511897045e4cc894cb62763384a..0410fb7afad0d51d03951348c820dc4a421f1804 100644 (file)
--- a/contrib/oid2name/.gitignore
+++ b/contrib/oid2name/.gitignore
@@ -1 +1,3 @@
 /oid2name
+
+/tmp_check/

diff --git a/contrib/oid2name/Makefile b/contrib/oid2name/Makefile
index 3eef8f60bea0017b2b8c98e9e494df1111683487..77b72880f5b7c89de4af0632dbd31e27c00704a9 100644 (file)
--- a/contrib/oid2name/Makefile
+++ b/contrib/oid2name/Makefile
@@ -19,3 +19,9 @@ top_builddir = ../..
 include $(top_builddir)/src/Makefile.global
 include $(top_srcdir)/contrib/contrib-global.mk
 endif
+
+check:
+   $(prove_check)
+
+installcheck:
+   $(prove_installcheck)

diff --git a/contrib/oid2name/oid2name.c b/contrib/oid2name/oid2name.c
index 63e360c4c56d831d728d5828cb3a3c0e3b357b62..aa122ca0e9840d9d2d4af852f533aa645d5376a3 100644 (file)
--- a/contrib/oid2name/oid2name.c
+++ b/contrib/oid2name/oid2name.c
@@ -14,6 +14,8 @@
 #include "fe_utils/connect.h"
 #include "libpq-fe.h"
 #include "pg_getopt.h"
+#include "getopt_long.h"
+
 
 /* an extensible array to keep track of elements to show */
 typedef struct
@@ -60,8 +62,28 @@ void     sql_exec_dumpalltbspc(PGconn *, struct options *);
 void
 get_opts(int argc, char **argv, struct options *my_opts)
 {
+   static struct option long_options[] = {
+       {"dbname", required_argument, NULL, 'd'},
+       {"host", required_argument, NULL, 'h'},
+       {"host", required_argument, NULL, 'H'}, /* deprecated */
+       {"filenode", required_argument, NULL, 'f'},
+       {"indexes", no_argument, NULL, 'i'},
+       {"oid", required_argument, NULL, 'o'},
+       {"port", required_argument, NULL, 'p'},
+       {"quiet", no_argument, NULL, 'q'},
+       {"tablespaces", no_argument, NULL, 's'},
+       {"system-objects", no_argument, NULL, 'S'},
+       {"table", required_argument, NULL, 't'},
+       {"username", required_argument, NULL, 'U'},
+       {"version", no_argument, NULL, 'V'},
+       {"extended", no_argument, NULL, 'x'},
+       {"help", no_argument, NULL, '?'},
+       {NULL, 0, NULL, 0}
+   };
+
    int         c;
    const char *progname;
+   int         optindex;
 
    progname = get_progname(argv[0]);
 
@@ -93,7 +115,7 @@ get_opts(int argc, char **argv, struct options *my_opts)
    }
 
    /* get opts */
-   while ((c = getopt(argc, argv, "H:p:U:d:t:o:f:qSxish")) != -1)
+   while ((c = getopt_long(argc, argv, "d:f:h:H:io:p:qsSt:U:x", long_options, &optindex)) != -1)
    {
        switch (c)
        {
@@ -102,39 +124,40 @@ get_opts(int argc, char **argv, struct options *my_opts)
                my_opts->dbname = pg_strdup(optarg);
                break;
 
-               /* specify one tablename to show */
-           case 't':
-               add_one_elt(optarg, my_opts->tables);
-               break;
-
-               /* specify one Oid to show */
-           case 'o':
-               add_one_elt(optarg, my_opts->oids);
-               break;
-
                /* specify one filenode to show */
            case 'f':
                add_one_elt(optarg, my_opts->filenodes);
                break;
 
-               /* don't show headers */
-           case 'q':
-               my_opts->quiet = true;
-               break;
-
                /* host to connect to */
-           case 'H':
+           case 'H':           /* deprecated */
+           case 'h':
                my_opts->hostname = pg_strdup(optarg);
                break;
 
+               /* also display indexes */
+           case 'i':
+               my_opts->indexes = true;
+               break;
+
+               /* specify one Oid to show */
+           case 'o':
+               add_one_elt(optarg, my_opts->oids);
+               break;
+
                /* port to connect to on remote host */
            case 'p':
                my_opts->port = pg_strdup(optarg);
                break;
 
-               /* username */
-           case 'U':
-               my_opts->username = pg_strdup(optarg);
+               /* don't show headers */
+           case 'q':
+               my_opts->quiet = true;
+               break;
+
+               /* dump tablespaces only */
+           case 's':
+               my_opts->tablespaces = true;
                break;
 
                /* display system tables */
@@ -142,9 +165,14 @@ get_opts(int argc, char **argv, struct options *my_opts)
                my_opts->systables = true;
                break;
 
-               /* also display indexes */
-           case 'i':
-               my_opts->indexes = true;
+               /* specify one tablename to show */
+           case 't':
+               add_one_elt(optarg, my_opts->tables);
+               break;
+
+               /* username */
+           case 'U':
+               my_opts->username = pg_strdup(optarg);
                break;
 
                /* display extra columns */
@@ -152,16 +180,6 @@ get_opts(int argc, char **argv, struct options *my_opts)
                my_opts->extended = true;
                break;
 
-               /* dump tablespaces only */
-           case 's':
-               my_opts->tablespaces = true;
-               break;
-
-           case 'h':
-               help(progname);
-               exit(0);
-               break;
-
            default:
                fprintf(stderr, _("Try \"%s --help\" for more information.\n"), progname);
                exit(1);
@@ -176,20 +194,22 @@ help(const char *progname)
           "Usage:\n"
           "  %s [OPTION]...\n"
           "\nOptions:\n"
-          "  -d DBNAME      database to connect to\n"
-          "  -f FILENODE    show info for table with given file node\n"
-          "  -H HOSTNAME    database server host or socket directory\n"
-          "  -i             show indexes and sequences too\n"
-          "  -o OID         show info for table with given OID\n"
-          "  -p PORT        database server port number\n"
-          "  -q             quiet (don't show headers)\n"
-          "  -s             show all tablespaces\n"
-          "  -S             show system objects too\n"
-          "  -t TABLE       show info for named table\n"
-          "  -U NAME        connect as specified database user\n"
-          "  -V, --version  output version information, then exit\n"
-          "  -x             extended (show additional columns)\n"
-          "  -?, --help     show this help, then exit\n"
+          "  -f, --filenode=FILENODE    show info for table with given file node\n"
+          "  -i, --indexes              show indexes and sequences too\n"
+          "  -o, --oid=OID              show info for table with given OID\n"
+          "  -q, --quiet                quiet (don't show headers)\n"
+          "  -s, --tablespaces          show all tablespaces\n"
+          "  -S, --system-objects       show system objects too\n"
+          "  -t, --table=TABLE          show info for named table\n"
+          "  -V, --version              output version information, then exit\n"
+          "  -x, --extended             extended (show additional columns)\n"
+          "  -?, --help                 show this help, then exit\n"
+          "\nConnection options:\n"
+          "  -d, --dbname=DBNAME        database to connect to\n"
+          "  -h, --host=HOSTNAME        database server host or socket directory\n"
+          "  -H                         same as -h, deprecated option\n"
+          "  -p, --port=PORT            database server port number\n"
+          "  -U, --username=USERNAME    connect as specified database user\n"
           "\nThe default action is to show all database OIDs.\n\n"
           "Report bugs to <pgsql-bugs@postgresql.org>.\n",
           progname, progname);

diff --git a/contrib/oid2name/t/001_basic.pl b/contrib/oid2name/t/001_basic.pl
new file mode 100644 (file)
index 0000000..fa2c574
--- /dev/null
+++ b/contrib/oid2name/t/001_basic.pl
@@ -0,0 +1,12 @@
+use strict;
+use warnings;
+
+use TestLib;
+use Test::More tests => 8;
+
+#########################################
+# Basic checks
+
+program_help_ok('oid2name');
+program_version_ok('oid2name');
+program_options_handling_ok('oid2name');

diff --git a/doc/src/sgml/oid2name.sgml b/doc/src/sgml/oid2name.sgml
index dd875281c8120ed015eacddc86c20c20a7d10865..c7ebd61c6bf1caa3875e9fc634de3155f3039159 100644 (file)
--- a/doc/src/sgml/oid2name.sgml
+++ b/doc/src/sgml/oid2name.sgml
@@ -60,41 +60,48 @@
    <variablelist>
 
     <varlistentry>
-     <term><option>-f</option> <replaceable>filenode</replaceable></term>
-     <listitem><para>show info for table with filenode <replaceable>filenode</replaceable></para></listitem>
+     <term><option>-f <replaceable class="parameter">filenode</replaceable></option></term>
+     <term><option>--filenode=<replaceable class="parameter">filenode</replaceable></option></term>
+     <listitem><para>show info for table with filenode <replaceable>filenode</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-i</option></term>
-     <listitem><para>include indexes and sequences in the listing</para></listitem>
+     <term><option>--indexes</option></term>
+     <listitem><para>include indexes and sequences in the listing.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-o</option> <replaceable>oid</replaceable></term>
-     <listitem><para>show info for table with OID <replaceable>oid</replaceable></para></listitem>
+     <term><option>-o <replaceable class="parameter">oid</replaceable></option></term>
+     <term><option>--oid=<replaceable class="parameter">oid</replaceable></option></term>
+     <listitem><para>show info for table with OID <replaceable>oid</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-q</option></term>
-     <listitem><para>omit headers (useful for scripting)</para></listitem>
+     <term><option>--quiet</option></term>
+     <listitem><para>omit headers (useful for scripting).</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-s</option></term>
-     <listitem><para>show tablespace OIDs</para></listitem>
+     <term><option>--tablespaces</option></term>
+     <listitem><para>show tablespace OIDs.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-S</option></term>
+     <term><option>--system-objects</option></term>
      <listitem><para>include system objects (those in
       <option>information_schema</option>, <option>pg_toast</option>
-      and <option>pg_catalog</option> schemas)
+      and <option>pg_catalog</option> schemas).
      </para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-t</option> <replaceable>tablename_pattern</replaceable></term>
-     <listitem><para>show info for table(s) matching <replaceable>tablename_pattern</replaceable></para></listitem>
+     <term><option>-t <replaceable class="parameter">tablename_pattern</replaceable></option></term>
+     <term><option>--table=<replaceable class="parameter">tablename_pattern</replaceable></option></term>
+     <listitem><para>show info for table(s) matching <replaceable class="parameter">tablename_pattern</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
@@ -109,8 +116,9 @@
 
     <varlistentry>
      <term><option>-x</option></term>
+     <term><option>--extended</option></term>
      <listitem><para>display more information about each object shown: tablespace name,
-      schema name, and OID
+      schema name, and OID.
      </para></listitem>
     </varlistentry>
 
@@ -133,29 +141,34 @@
 
    <variablelist>
     <varlistentry>
-     <term><option>-d</option> <replaceable>database</replaceable></term>
-     <listitem><para>database to connect to</para></listitem>
+     <term><option>-d <replaceable class="parameter">database</replaceable></option></term>
+     <term><option>--dbname=<replaceable class="parameter">database</replaceable></option></term>
+     <listitem><para>database to connect to.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-H</option> <replaceable>host</replaceable></term>
-     <listitem><para>database server's host</para></listitem>
+     <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
+     <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
+     <listitem><para>database server's host.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-p</option> <replaceable>port</replaceable></term>
-     <listitem><para>database server's port</para></listitem>
+     <term><option>-H <replaceable class="parameter">host</replaceable></option></term>
+     <listitem><para>database server's host.  Use of this parameter is
+     <emphasis>deprecated</emphasis> as of
+     <productname>PostgreSQL</productname> 12.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-U</option> <replaceable>username</replaceable></term>
-     <listitem><para>user name to connect as</para></listitem>
+     <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
+     <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
+     <listitem><para>database server's port.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-P</option> <replaceable>password</replaceable></term>
-     <listitem><para>password (deprecated &mdash; putting this on the command line
-      is a security hazard)</para></listitem>
+     <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
+     <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
+     <listitem><para>user name to connect as.</para></listitem>
     </varlistentry>
 
    </variablelist>
@@ -188,6 +201,30 @@
   </para>
  </refsect1>
 
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   This utility, like most other <productname>PostgreSQL</productname>
+   utilities, also uses the environment variables supported by
+   <application>libpq</application> (see <xref linkend="libpq-envars"/>).
+  </para>
+ </refsect1>
+
  <refsect1>
   <title>Notes</title>