PgCommon - Common functions for the postgresql-common framework
(C) 2008-2009 Martin Pitt <mpitt@debian.org>
(C) 2012-2021 Christoph Berg <myon@debian.org>
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either
version 2 of the License,
or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
Print an error message to stderr and die with exit status 1
Functions for configuration
returns '1' if the argument is a configuration file value that stands for
true (ON, TRUE, YES, or 1, case insensitive), '0' if the argument represents
a false value (OFF, FALSE, NO, or 0, case insensitive), or undef otherwise.
Quotes a value with single quotes
Arguments: <value>
Returns: quoted string
Replaces %v and %c placeholders
Arguments: <string> <version> <cluster>
Returns: string
Read a 'var = value' style configuration file and return a hash with the
values. Error out if the file cannot be read.
If the file name ends with '.conf', the keys will be normalized to
lower case (suitable for e.g. postgresql.conf), otherwise kept intact
(suitable for environment).
Arguments: <path>
Returns: hash (empty if file does not exist)
Returns path to cluster config file from a cluster configuration
directory (with /etc/postgresql-common/<file name> as fallback)
and return a hash with the values. Error out if the file cannot be read.
If config file name is postgresql.auto.conf, read from PGDATA
Arguments: <version> <cluster> <config file name>
Returns: hash (empty if the file does not exist)
Read a 'var = value' style configuration file from a cluster configuration
Arguments: <version> <cluster> <config file name>
Returns: hash (empty if the file does not exist)
Return parameter from a PostgreSQL configuration file,
or undef if the parameter does not exist.
Arguments: <version> <cluster> <config file name> <parameter name>
Set parameter of a PostgreSQL configuration file.
Arguments: <config file name> <parameter name> <value>
Set parameter of a PostgreSQL cluster configuration file.
Arguments: <version> <cluster> <config file name> <parameter name> <value>
Disable a parameter in a PostgreSQL configuration file by prepending it
with a '#'. Appends an optional explanatory comment <reason> if given.
Arguments: <config file name> <parameter name> <reason>
Disable a parameter in a PostgreSQL cluster configuration file by prepending
it with a '#'. Appends an optional explanatory comment <reason> if given.
Arguments: <version> <cluster> <config file name> <parameter name> <reason>
Replace a parameter in a PostgreSQL configuration file. The old parameter
is prepended with a '#' and gets an optional explanatory comment <reason>
appended, if given. The new parameter is inserted directly after the old one.
Arguments: <version> <cluster> <config file name> <old parameter name>
<reason> <new parameter name> <new value>
Return the port of a particular cluster
Arguments: <version> <cluster>
Set the port of a particular cluster.
Arguments: <version> <cluster> <port>
Return cluster data directory.
Arguments: <version> <cluster name> [<config_hash>]
Return the socket directory of a particular cluster
or undef if the cluster does not exist.
Arguments: <version> <cluster>
Set the socket directory of a particular cluster.
Arguments: <version> <cluster> <directory>
Return the path of a program of a particular version.
Arguments: <program name> [<version>]
Check whether a postgres server is running at the specified port.
Arguments: <version> <cluster> <port>
Read, verify, and return the current start.conf setting.
Arguments: <version> <cluster>
Returns: auto | manual | disabled
Change start.conf setting.
Arguments: <version> <cluster> <value>
<value> = auto | manual | disabled
Change pg_ctl.conf setting.
Arguments: <version> <cluster> <options>
<options> = options passed to pg_ctl(1)
Return the PID from an existing PID file or undef if it does not exist.
Arguments: <pid file path>
Check whether a pid file is present and belongs to a running postgres.
Returns undef if it cannot be determined
Arguments: <pid file path>
postgres does not clean up the PID file when it stops, and it is
not world readable, so only its absence is a definitive result;
if it is present, we need to read it and check the PID, which will
only work as root
Determine if a cluster is managed by a supervisor (pacemaker, patroni).
Returns undef if it cannot be determined
Arguments: <pid file path>
postgres does not clean up the PID file when it stops, and it is
not world readable, so only its absence is a definitive result; if it
is present, we need to read it and check the PID, which will only
work as root
Return a hash with information about a specific cluster (which needs to exist).
Arguments: <version> <cluster name>
Returns: information hash (keys: pgdata, port, running, logfile [unless it
has a custom one], configdir, owneruid, ownergid, waldir, socketdir,
config->postgresql.conf)
Checks if the owner of a cluster is valid, and the owner of the config matches
the owner of the data directory.
Arguments: cluster_info hash reference
Return an array of all available versions (by binaries and postgresql.conf files)
Arguments: binary to scan for (optional, defaults to postgres)
Return the newest available version
Arguments: binary to scan for (optional)
Check whether a version exists
Return an array of all available clusters of given version
Arguments: <version>
Check if a cluster exists.
Arguments: <version> <cluster>
Return the next free PostgreSQL port.
Return the PostgreSQL version, cluster, and database to connect to.
Version is always set (defaulting to the version of the default port
if no matching entry is found, or finally to the latest installed version
if there are no clusters at all), cluster and database may be 'undef'.
If only one cluster exists, and no matching entry is found in the map files,
that cluster is returned.
Copy a file to a destination and setup permissions
Arguments: <source file> <destination file or dir> <uid> <gid> <permissions>
Change effective and real user and group id. Also activates all auxiliary
groups the user is in. Exits with an error message if user/group ID cannot
be changed.
Arguments: <user id> <group id>
Run a command and error out if it exits with a non-zero status.
Arguments: <command ...>
Return the encoding of a particular database in a cluster.
This requires access privileges to that database, so this
function should be called as the cluster owner.
Arguments: <version> <cluster> <database>
Returns: Encoding or undef if it cannot be determined.
Return locale of a particular database in a cluster. This requires access
privileges to that database, so this function should be called as the cluster
owner. (For versions >= 8.4; for older versions use get_cluster_locales()).
Arguments: <version> <cluster> <database>
Returns: (LC_CTYPE, LC_COLLATE) or (undef,undef) if it cannot be determined.
Return the CTYPE and COLLATE locales of a cluster.
This needs to be called as root or as the cluster owner.
(For versions <= 8.3; for >= 8.4, use get_db_locales()).
Arguments: <version> <cluster>
Returns: (LC_CTYPE, LC_COLLATE) or (undef,undef) if it cannot be determined.
Return the pg_control data for a cluster
Arguments: <version> <cluster>
Returns: hashref
Return an array with all databases of a cluster.
This requires connection privileges to template1, so
this function should be called as the cluster owner.
Arguments: <version> <cluster>
Returns: array of database names or undef on error.
Return the device name a file is stored at.
Arguments: <file path>
Returns: device name, or '' if it cannot be determined.
Parse a single pg_hba.conf line.
Arguments: <line>
Returns: Hash reference (or only line and type==undef for invalid lines)
-
line -> the verbatim pg_hba line
-
type -> comment, local, host, hostssl, hostnossl, undef
-
db -> database name
-
user -> user name
-
method -> trust, reject, md5, crypt, password, krb5, ident, pam
-
ip -> ip address
-
mask -> network mask (either a single number as number of bits, or bit mask)
Parse given pg_hba.conf file.
Arguments: <pg_hba.conf path>
Returns: Array with hash refs; for hash contents, see parse_hba_line().
Check if hba method is known
Argument: hba method
Returns: True if method is valid
|