pgenv - PostgreSQL binary manager

Synopsis

pgenv help

# Check dependencies
pgenv check

# Show versions available to build
pgenv available

# Build PostgreSQL server
pgenv build 10.4

# Switch PostgreSQL version
pgenv switch 10.4

# Use PostgreSQL version
pgenv use 10.4

# Stop current version
pgenv stop

# Start current version
pgenv start

# Show server status
pgenv status

# Restart current version
pgenv restart

# Show current version
pgenv version

# List built versions
pgenv versions

# Clear current version
pgenv clear

# Remove PostgreSQL version
pgenv remove 8.0.25

Description

pgenv is a simple utility to build and run different releases of [PostgreSQL]. This makes it easy to switch between versions when testing applications for compatibility.

Installation

1. Check out pgenv into ~/.pgenv.

   git clone https://github.com/theory/pgenv.git ~/.pgenv
   

2. Add ~/.pgenv/bin and ~/.pgenv/pgsql/bin to your $PATH for access to the pgenv command-line utility and all the programs provided by PostgreSQL:

   echo 'export PATH="$HOME/.pgenv/bin:$HOME/.pgenv/pgsql/bin:$PATH"' >> ~/.bash_profile
   

   Ubuntu note: Modify your ~/.profile instead of ~/.bash_profile.

   Zsh note: Modify your ~/.zshrc file instead of ~/.bash_profile.

3. Restart your shell as a login shell so the path changes take effect. You can now begin using pgenv.

   exec $SHELL -l
   

4. Build a version of PostgreSQL:

   pgenv build 10.4
   

Configuration

By default, all versions of PostgreSQL will be built in the root of the project directory (generally in ~/.pgenv.). If you'd like them to live elsewhere, set the $PGENV_ROOT environment variable to the appropriate directory.

It is possible to configure which programs, flags and languages to build using a configuration file before the program launches the build. For a more detailed configuration, see the pgenv config command below.

You can use a local PostgreSQL git repo instead of downloading tarballs for the build step by setting the external $PGENV_LOCAL_POSTGRESQL_REPO environment variable to the appropriate absolute path.

Running scripts

It is possible to run custom script when particular events happen. The purpose is to let the user to configure the cluster as much as she want, for instance installing extension or pre-loading data.

Custom scripts are driven by a set of configuration variables as follows:

• PGENV_SCRIPT_POSTINSTALL is an executable script run as soon as the build finishes. The return value of the script does not affect the pgenv workflow. The script gets the version of PostgreSQL being installed as first argument.

• PGENV_SCRIPT_POSTINITDB is an executable script run as soon as the use command ends the initdb phase, that happens only the PGDATA has not been initialized (i.e., on very first use). The return value of the script does not affect the pgenv workflow. The script gets the current PGDATA path as first argument. Please note that this script runs with the cluster turned off.

• PGENV_SCRIPT_FIRSTSTART is an executable script run at the very first of a freshly installed cluster. Typically, this happens immediately after the initdb phase, after the cluster has been successfully started. Please note that this script is run only once in the whole cluster's life, that means it will not run at every cluster start action, but only on the very first start of the cluster. Therefore, this script can be used to initialize the cluster with custom data (e.g., creating users, databases, populating tables and so on).

• PGENV_SCRIPT_POSTSTART is an executable script executed each time an instances is started, that is start is executed. The return value of the script does not affect the pgenv workflow. The script gets the current PGDATA path as first argument.

• PGENV_SCRIPT_PRESTOP is an executable script executed before an instance is stopped, that is before the stop command is executed. The return value of the script does not affect the pgenv workflow, and if the script generates errors they are ignored, so that the cluster is going to be stopped anyway. The script gets the current PGDATA path as first argument.

• PGENV_SCRIPT_POSTSTOP is an executable script executed each time an instance is stopped, that is the stop command is executed. The return value of the script does not affect the pgenv workflow. The script gets the current PGDATA path as first argument.

• PGENV_SCRIPT_POSTRESTART is an executable script executed each time an instance is restarted, that is the restart command is executed. The return value of the script does not affect the pgenv workflow. The script gets the current PGDATA path as first argument.

The above configuration variables can be set in the configuration file or on the fly, for instance:

$ export PGENV_SCRIPT_POSTSTART=/usr/local/bin/load_data.sh
$ pgenv start 12.0

It is worth noting that the start, restart and post script are not shared between similar events: for instance the PGENV_SCRIPT_POSTSTOP is not executed if the user issues a restart command (even if that implies somehow a cluster stop).

Please note that running external scripts can result in damages and crashes in the pgenv workflow. In the future, more hooks to run scripts could be added.

Upgrading

You can upgrade your installation to the cutting-edge version at any time with a simple git pull.

$ cd ~/.pgenv
$ git pull

Dependencies

---

pgenv needs the following dependencies in order to run:

• env - Sets environment for execution
• bash - Command shell interpreter
• curl - Used to download files
• sed, grep, cat, tar, sort, tr, uname, tail - General Unix command line utilities
• patch - For patching versions that need patching
• make - Builds PostgreSQL

Morever, bunzip2(1) and gunzip(1) are required to extract the downloaded PostgreSQL tarballs.

Optional dependencies:

• git(1) in the case you want to build a development version of PostgreSQL

• Perl 5 - To build PL/Perl
• Python - To build PL/Python

Command Reference

Like git, the pgenv command delegates to subcommands based on its first argument.

Some commands require you to specify the PostgreSQL version to act on. You can specify the version the command applies to by either entering the PostgreSQL version number or by specifying any of the special keywords:

• current or version to indicate the currently selected PostgreSQL version;
• earliest to indicate the oldest installed version (excluding beta versions);
• newest to indicate the newest installed version (excluding beta versions).

It is important to note that earliest and latest have nothing to do with the time you installed PostgreSQL by means of pgenv: they refer only to PostgreSQL stable versions. To better clarify this, the following snippet shows you which aliases point to which versions in an example installation.

9.6.19                 <-- earliest (also earliest 9.6)
9.6.20      <-- latest 9.6
12.2        <-- earliest 12
12.4        <-- latest 12
13beta2
13.0                   <-- latest (also latest 13)

The subcommands are:

pgenv use

Sets the version of PostgreSQL to be used in all shells by symlinking its directory to ~/$PGENV_ROOT/pgsql and starting it. Initializes the data directory if none exists. If another version is currently active, it will be stopped before switching. If the specified version is already in use, the use command won't stop it, but will initialize its data directory and starts it if it's not already running.

$ pgenv use 10.4
waiting for server to shut down.... done
server stopped
waiting for server to start.... done
server started
PostgreSQL 10.4 started

The use command supports the special keywords earliest and latest to respectively indicate the oldest PostgreSQL version installed and the newest one. It is also possible to indicate a major version to narrow the scope of the special keywords. As an example:

pgenv use latest 10

will select the most recent PostgreSQL version of the 10 series installed.

Since pgenv version 1.3.7, the use command accepts also arbitrary strings as version specifiers, assuming such specifiers identify externally managed PostgreSQL installations. An externally managed PostgreSQL installation must have the same directory layout of those managed by pgenv, and therefore:

• it must live within pgenv-<your_version_identifier> inside the PGENV_ROOT directory;
• it must contain a data subdirectory that will be used as PGDATA for such installation;
• it must contain a bin, lib, share and include subdirectories as for other installations.

Please consider that using externally managed PostgreSQL installations requires you to use unique version identifiers to avoid clashing with those used by pgenv. All PostgreSQL version numbering, as well as the reserved words latest and earliest, cannot be used as custom identifiers.

pgenv switch

Sets the version of PostgreSQL to be used in all shells by symlinking its directory to $PGENV_ROOT/pgsql. Contrary to pgenv use this command does not manage a database for you. Meaning, it will not start, stop and initialize a postgres database with the given version. Instead it simply changes the environment to a different version of PostgreSQL. This can be useful if the user has other tools to automate the provisioning and lifecycle of a database.

$ pgenv sw