pg_isready
authorRobert Haas
Wed, 23 Jan 2013 15:58:04 +0000 (10:58 -0500)
committerRobert Haas
Wed, 23 Jan 2013 16:01:20 +0000 (11:01 -0500)
New command-line utility to test whether a server is ready to
accept connections.

Phil Sorber, reviewed by Michael Paquier and Peter Eisentraut

doc/src/sgml/ref/allfiles.sgml
doc/src/sgml/ref/pg_isready.sgml [new file with mode: 0644]
doc/src/sgml/reference.sgml
src/bin/scripts/.gitignore
src/bin/scripts/Makefile
src/bin/scripts/pg_isready.c [new file with mode: 0644]
src/interfaces/libpq/libpq-fe.h

index df84054bcee42a237532ef92bff7014558056d14..b3fc57d942f8275f4c1a96c7f2abf9e5262bc92b 100644 (file)
@@ -175,6 +175,7 @@ Complete list of usable sgml source files in this directory.
 
 
 
+
 
 
 
diff --git a/doc/src/sgml/ref/pg_isready.sgml b/doc/src/sgml/ref/pg_isready.sgml
new file mode 100644 (file)
index 0000000..ea0d3a7
--- /dev/null
@@ -0,0 +1,200 @@
+
+
+
+  pg_isready
+  1
+  Application
+
+  pg_isready
+  checks the connection status of a PostgreSQL server
+
+  pg_isready
+
+  
+   pg_isready
+   connection-option
+   option
+  
+
+
+  Description
+  
+   pg_isready is a utility for checking the connection
+   status of a PostgreSQL database server. The exit
+   status specifies the result of the connection check.
+  
+
+  Options
+
+    
+
+    
+      
+      
+      
+      
+       Specifies the name of the database to connect to.
+      
+      
+       If this parameter contains an = sign or starts
+       with a valid URI prefix
+       (postgresql://
+       or postgres://), it is treated as a
+       conninfo string. See  for more information.
+      
+      
+    
+
+     
+       
+       
+       
+       
+       Specifies the host name of the machine on which the
+       server is running. If the value begins
+       with a slash, it is used as the directory for the Unix-domain
+       socket.
+       
+       
+     
+
+     
+       
+       
+       
+       
+       Specifies the TCP port or the local Unix-domain
+       socket file extension on which the server is listening for
+       connections. Defaults to the value of the PGPORT
+       environment variable or, if not set, to the port specified at
+       compile time, usually 5432.
+       
+       
+     
+
+     
+      
+      
+      
+       
+        Do not display status message. This is useful when scripting.
+       
+      
+     
+
+     
+       
+       
+       
+       
+       Connect to the database as the user 
+       class="parameter">username instead of the default.
+       
+       
+     
+
+     
+      
+      
+       
+        
+         Print the pg_isready version and exit.
+        
+       
+     
+
+     
+      
+      
+      
+       
+        Show help about pg_isready command line
+        arguments, and exit.
+       
+      
+     
+   
+
+  Exit Status
+
+  
+   pg_isready returns 0 to the shell if the server
+   is accepting connections normally, 1 if the server is rejecting
+   connections (for example during startup), 2 if there was no response to the
+   connection attempt, and 3 if no attempt was made (for example due to invalid
+   parameters).
+  
+
+  Environment
+
+  
+   pg_isready, like most other PostgreSQL
+   utilities,
+   also uses the environment variables supported by libpq
+   (see ).
+  
+
+  Notes
+
+  
+   The options 
+   error messages in the logs, but are not necessary for proper functionality.
+  
+
+  Examples
+
+  
+   Standard Usage:
+   
+    $ pg_isready
+    /tmp:5432 - accepting connections
+    $ echo $?
+    0
+   
+  
+
+  
+   Running with connection parameters to a PostgreSQL cluster in startup:
+   
+    pg_isready -h localhost -p 5433
+    localhost:5433 - rejecting connections
+    $ echo $?
+    1
+   
+  
+
+  
+   Running with connection parameters to a non-responsive PostgreSQL cluster:
+   
+    pg_isready -h someremotehost
+    someremotehost:5432 - no response
+    $ echo $?
+    2
+   
+  
+
+
+
index 08721684074c325d325800acd9bcde432e5a70a5..fe90227b4f3a07be32be5a96a9b969f4f0a27732 100644 (file)
    &pgConfig;
    &pgDump;
    &pgDumpall;
+   &pgIsready;
    &pgReceivexlog;
    &pgRestore;
    &psqlRef;
index e62f4b03a7cfa478b7ec90dcf641adc707471328..0b9b786da032722064c3bd35da618145cda30223 100644 (file)
@@ -7,6 +7,7 @@
 /dropuser
 /reindexdb
 /vacuumdb
+/pg_isready
 
 /dumputils.c
 /keywords.c
index ea4841159d7a6f2c3389a10e14bff3aebaef9806..26f6f8b3b4fff2cd98ad20b2694d924a9d392a62 100644 (file)
@@ -16,7 +16,7 @@ subdir = src/bin/scripts
 top_builddir = ../../..
 include $(top_builddir)/src/Makefile.global
 
-PROGRAMS = createdb createlang createuser dropdb droplang dropuser clusterdb vacuumdb reindexdb
+PROGRAMS = createdb createlang createuser dropdb droplang dropuser clusterdb vacuumdb reindexdb pg_isready
 
 override CPPFLAGS := -I$(top_srcdir)/src/bin/pg_dump -I$(top_srcdir)/src/bin/psql -I$(libpq_srcdir) $(CPPFLAGS)
 
@@ -34,6 +34,7 @@ dropuser: dropuser.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
 clusterdb: clusterdb.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
 vacuumdb: vacuumdb.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
 reindexdb: reindexdb.o common.o dumputils.o kwlookup.o keywords.o | submake-libpq
+pg_isready: pg_isready.o common.o | submake-libpq submake-libpgport
 
 dumputils.c keywords.c: % : $(top_srcdir)/src/bin/pg_dump/%
    rm -f $@ && $(LN_S) $< .
@@ -54,6 +55,7 @@ install: all installdirs
    $(INSTALL_PROGRAM) clusterdb$(X)  '$(DESTDIR)$(bindir)'/clusterdb$(X)
    $(INSTALL_PROGRAM) vacuumdb$(X)   '$(DESTDIR)$(bindir)'/vacuumdb$(X)
    $(INSTALL_PROGRAM) reindexdb$(X)  '$(DESTDIR)$(bindir)'/reindexdb$(X)
+   $(INSTALL_PROGRAM) pg_isready$(X) '$(DESTDIR)$(bindir)'/pg_isready$(X)
 
 installdirs:
    $(MKDIR_P) '$(DESTDIR)$(bindir)'
diff --git a/src/bin/scripts/pg_isready.c b/src/bin/scripts/pg_isready.c
new file mode 100644 (file)
index 0000000..feee1a7
--- /dev/null
@@ -0,0 +1,202 @@
+/*-------------------------------------------------------------------------
+ *
+ * pg_isready --- checks the status of the PostgreSQL server
+ *
+ * Copyright (c) 2013, PostgreSQL Global Development Group
+ *
+ * src/bin/scripts/pg_isready.c
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#include "postgres_fe.h"
+#include "common.h"
+
+static void
+help(const char *progname);
+
+int
+main(int argc, char **argv)
+{
+   int c,optindex,opt_index = 0;
+
+   const char *progname;
+
+   const char *pghost = NULL;
+   const char *pgport = NULL;
+   const char *pguser = NULL;
+   const char *pgdbname = NULL;
+
+   const char *keywords[4], *values[4];
+
+   bool quiet = false;
+
+   PGPing rv;
+   PQconninfoOption *connect_options, *conn_opt_ptr;
+
+   /*
+    * We accept user and database as options to avoid
+    * useless errors from connecting with invalid params
+    */
+
+   static struct option long_options[] = {
+           {"dbname", required_argument, NULL, 'd'},
+           {"host", required_argument, NULL, 'h'},
+           {"port", required_argument, NULL, 'p'},
+           {"quiet", no_argument, NULL, 'q'},
+           {"username", required_argument, NULL, 'U'},
+           {NULL, 0, NULL, 0}
+       };
+
+   progname = get_progname(argv[0]);
+   handle_help_version_opts(argc, argv, progname, help);
+
+   while ((c = getopt_long(argc, argv, "d:h:p:qU:V", long_options, &optindex)) != -1)
+   {
+       switch (c)
+       {
+           case 'd':
+               pgdbname = pg_strdup(optarg);
+               break;
+           case 'h':
+               pghost = pg_strdup(optarg);
+               break;
+           case 'p':
+               pgport = pg_strdup(optarg);
+               break;
+           case 'q':
+               quiet = true;
+               break;
+           case 'U':
+               pguser = pg_strdup(optarg);
+               break;
+           default:
+               /*
+                * We need to make sure we don't return 1 here because someone
+                * checking the return code might infer unintended meaning
+                */
+               exit(PQPING_NO_ATTEMPT);
+       }
+   }
+
+   if (optind < argc)
+   {
+       fprintf(stderr, _("%s: too many command-line arguments (first is \"%s\")\n"),
+               progname, argv[optind]);
+       fprintf(stderr, _("Try \"%s --help\" for more information.\n"), progname);
+       /*
+        * We need to make sure we don't return 1 here because someone
+        * checking the return code might infer unintended meaning
+        */
+       exit(PQPING_NO_ATTEMPT);
+   }
+
+   /*
+    * Get the default options so we can display them in our output
+    */
+
+   connect_options = PQconndefaults();
+   conn_opt_ptr = connect_options;
+
+   while (conn_opt_ptr->keyword)
+   {
+       if (strncmp(conn_opt_ptr->keyword, "host", 5) == 0)
+       {
+           if (pghost)
+           {
+               keywords[opt_index] = conn_opt_ptr->keyword;
+               values[opt_index] = pghost;
+               opt_index++;
+           }
+           else if (conn_opt_ptr->val)
+               pghost = conn_opt_ptr->val;
+           else
+               pghost = DEFAULT_PGSOCKET_DIR;
+       }
+       else if (strncmp(conn_opt_ptr->keyword, "port", 5) == 0)
+       {
+           if (pgport)
+           {
+               keywords[opt_index] = conn_opt_ptr->keyword;
+               values[opt_index] = pgport;
+               opt_index++;
+           }
+           else if (conn_opt_ptr->val)
+               pgport = conn_opt_ptr->val;
+       }
+       else if (strncmp(conn_opt_ptr->keyword, "user", 5) == 0)
+       {
+           if (pguser)
+           {
+               keywords[opt_index] = conn_opt_ptr->keyword;
+               values[opt_index] = pguser;
+               opt_index++;
+           }
+           else if (conn_opt_ptr->val)
+               pguser = conn_opt_ptr->val;
+       }
+       else if (strncmp(conn_opt_ptr->keyword, "dbname", 7) == 0)
+       {
+           if (pgdbname)
+           {
+               keywords[opt_index] = conn_opt_ptr->keyword;
+               values[opt_index] = pgdbname;
+               opt_index++;
+           }
+           else if (conn_opt_ptr->val)
+               pgdbname = conn_opt_ptr->val;
+       }
+       conn_opt_ptr++;
+   }
+
+   keywords[opt_index] = NULL;
+   values[opt_index] = NULL;
+
+   rv = PQpingParams(keywords, values, 1);
+
+   if (!quiet)
+   {
+       printf("%s:%s - ", pghost, pgport);
+
+       switch (rv)
+       {
+           case PQPING_OK:
+               printf("accepting connections\n");
+               break;
+           case PQPING_REJECT:
+               printf("rejecting connections\n");
+               break;
+           case PQPING_NO_RESPONSE:
+               printf("no response\n");
+               break;
+           case PQPING_NO_ATTEMPT:
+               printf("no attempt\n");
+               break;
+           default:
+               printf("unknown\n");
+       }
+   }
+
+   PQconninfoFree(connect_options);
+
+   exit(rv);
+}
+
+static void
+help(const char *progname)
+{
+   printf(_("%s issues a connection check to a PostgreSQL database.\n\n"), progname);
+   printf(_("Usage:\n"));
+   printf(_("  %s [OPTION]...\n"), progname);
+
+   printf(_("\nOptions:\n"));
+   printf(_("  -d, --dbname=DBNAME      database name\n"));
+   printf(_("  -q, --quiet              run quietly\n"));
+   printf(_("  -V, --version            output version information, then exit\n"));
+   printf(_("  -?, --help               show this help, then exit\n"));
+
+   printf(_("\nConnection options:\n"));
+   printf(_("  -h, --host=HOSTNAME      database server host or socket directory\n"));
+   printf(_("  -p, --port=PORT          database server port\n"));
+   printf(_("  -U, --username=USERNAME  database username\n"));
+}
index 895afbcc71f0a9ab71fb9d648541a181a9490c7d..e0f4bc7c4995e41024d4e3e43c12251111b2e4e2 100644 (file)
@@ -110,6 +110,11 @@ typedef enum
    PQERRORS_VERBOSE            /* all the facts, ma'am */
 } PGVerbosity;
 
+/*
+ * PGPing - The ordering of this enum should not be altered because the
+ * values are exposed externally via pg_isready.
+ */
+
 typedef enum
 {
    PQPING_OK,                  /* server is accepting connections */