From ac2e9673622591319d107272747a02d2c7f343bd Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Wed, 23 Jan 2013 10:58:04 -0500 Subject: [PATCH] pg_isready 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 | 1 + doc/src/sgml/ref/pg_isready.sgml | 200 ++++++++++++++++++++++++++++++ doc/src/sgml/reference.sgml | 1 + src/bin/scripts/.gitignore | 1 + src/bin/scripts/Makefile | 4 +- src/bin/scripts/pg_isready.c | 202 +++++++++++++++++++++++++++++++ src/interfaces/libpq/libpq-fe.h | 5 + 7 files changed, 413 insertions(+), 1 deletion(-) create mode 100644 doc/src/sgml/ref/pg_isready.sgml create mode 100644 src/bin/scripts/pg_isready.c diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index df84054bce..b3fc57d942 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -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 index 0000000000..ea0d3a7506 --- /dev/null +++ b/doc/src/sgml/ref/pg_isready.sgml @@ -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 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 + + + + 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 + + + + + + diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 0872168407..fe90227b4f 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -223,6 +223,7 @@ &pgConfig; &pgDump; &pgDumpall; + &pgIsready; &pgReceivexlog; &pgRestore; &psqlRef; diff --git a/src/bin/scripts/.gitignore b/src/bin/scripts/.gitignore index e62f4b03a7..0b9b786da0 100644 --- a/src/bin/scripts/.gitignore +++ b/src/bin/scripts/.gitignore @@ -7,6 +7,7 @@ /dropuser /reindexdb /vacuumdb +/pg_isready /dumputils.c /keywords.c diff --git a/src/bin/scripts/Makefile b/src/bin/scripts/Makefile index ea4841159d..26f6f8b3b4 100644 --- a/src/bin/scripts/Makefile +++ b/src/bin/scripts/Makefile @@ -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 index 0000000000..feee1a7288 --- /dev/null +++ b/src/bin/scripts/pg_isready.c @@ -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")); +} diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h index 895afbcc71..e0f4bc7c49 100644 --- a/src/interfaces/libpq/libpq-fe.h +++ b/src/interfaces/libpq/libpq-fe.h @@ -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 */ -- 2.40.0