pex.1

.TH PEX 1 2013 Pex pex
.
.SH NAME
pex \- light-weight package manager for PostgreSQL
.
.SH SYNOPSIS
\fBpex\fR \fIcommand\fR [\fIpackage\fR]...
.
.SH DESCRIPTION
\fBpex\fR is an easy way to install add-on packages (extensions,
loadable modules) into a PostgreSQL server.  \fBpex\fR downloads, builds, and installs the software.  Depending on the package, you need to run \fICREATE EXTENSION\fR and make any necessary configuration file changes manually.
.
.SH COMMANDS
.TP
\fBaudit\fR [\fIpackage\fR]...
Check \fIpackage\fR description file (or all packages) for syntactical correctness and style issues.  Useful when creating new packages.
.
.TP
\fBcat\fR \fIpackage\fR...
Print \fIpackage\fR description file to standard output.
.
.TP
\fBcreate\fR \fB\-n\fR \fIpackagename\fR \fIurl\fR
Help create a new package description file: Download the file at \fIurl\fR, populate some fields in the package description file, open the new package description file in an editor.
.
.TP
\fBdebuild\fR \fIpackage\fR \fIoptions\fR...
(experimental) Build a Debian package out of \fIpackage\fR.  Additional options are passed to \fBdebuild\fR (for example \fB-b\fR for a binary-only build).
.
.TP
\fBedit\fR [\fIpackage\fR]...
Open \fIpackage\fR description file (or all packages) in an editor.
.
.TP
\fBfetch\fR \fIpackage\fR...
Download source archive for \fIpackage\fR but don't install it.
.
.TP
\fBhome\fR [\fIpackage\fR]...
Open home page of \fIpackage\fR in a browser.  (Not all browsers can open more than one page at once.)  Without argument, open the home page of Pex.
.
.TP
\fBinfo\fR \fIpackage\fR...
Show information about \fIpackage\fR.
.
.TP
\fBinit\fR [\fIrepository\fR]
Create directories for Pex and do the initial clone of the packages repository.  Call this just once before using \fBpex\fR.  A nondefault Git repository for package descriptions can optionally be specified.
.
.TP
\fBinstall\fR \fIpackage\fR
Download, build, and install \fIpackage\fR.  If the option \fB\-\-if\-not\-exists\fR is specified and the package is already installed, do nothing.  Otherwise, installing an already installed package is an error.
.
.TP
\fBls\fR, \fBlist\fR
List installed packages.
.
.TP
\fBoutdated\fR
List outdated packages.
.
.TP
\fBrepotest\fR
Run a test suite over the current package repository.  The details of this are subject to change.
.
.TP
\fBrpmbuild\fR \fIpackage\fR \fIoptions\fR...
(experimental) Build an RPM package out of \fIpackage\fR.  Additional options are passed to \fBrpmbuild\fR (for example \fB-ba\fR).
.
.TP
\fBsearch\fR [\fIsubstring\fR]
Search among available packages.  If no search string is given, all available packages are listed.
.
.TP
\fBupdate\fR [\fB\-\-rebase\fR]
Fetch newest package description files using Git.  If \fB\-\-rebase\fR is specified, \fBgit pull \-\-rebase\fR is used.
.
.TP
\fBupgrade\fR [\fIpackage\fR]...
Install latest version of \fIpackage\fR or all installed packages.
.
.SH OPTIONS
.SS "Choosing a PostgreSQL Instance"
\fBpex\fR supports managing multiple PostgreSQL installations.  For example, you could have several major versions installed, or installations with different build options.  The build processes of PostgreSQL extension packages generally locate the target installation by looking for the \fBpg_config\fR program associated with the installation.  \fBpex\fR provides several ways to specify which installation to use.

Note that \fBpex\fR only deals with PostgreSQL \fIinstallations\fR, not \fIinstances\fR.  It only cares about file system locations for installing program, library, and data files.  It does not do anything in the PostgreSQL data directory, and it does not make any changes in a running database instance.
.
.TP
\fB\-d\fR \fIdatadir\fR
Use PostgreSQL installation running on this data directory.  \fBpex\fR looks inside the data directory for the file system location of the binary that serves that data directory.  This only works if the server has been started on this data directory at least once.  And it requires read access to the data directory.
.
.TP
\fB\-D\fR
Use PostgreSQL installation running on default data directory, otherwise like \fB-d\fR (only works if PGDATA environment variable is set).
.
.TP
\fB\-g\fR \fIpath\fR
Use PostgreSQL installation in this location.  \fIpath\fR can be either the full path to the \fBpg_config\fR program (e.g., \fI/usr/local/pgsql/bin/pg_config\fR) or the bin directory (e.g., \fI/usr/local/pgsql/bin\fR) or the root directory of the installation (e.g., \fI/usr/local/pgsql\fR), if the \fBpg_config\fR program is installed in the standard place thereunder.
.
.TP
\fB\-G\fR
Use PostgreSQL installation in the default location.  This is the default behavior.  \fBpg_config\fR will be located by relying on the shell's search path.
.
.TP
\fB\-p\fR \fIport\fR
Use PostgreSQL installation running on this port.  \fBpex\fR connects to the local PostgreSQL instance at the given port, determines the data directory, and then proceeds like \fB\-d\fR.
.
.TP
\fB\-P\fR
Use PostgreSQL installation running on the default port (whatever \fBpsql\fR and libpq think is the default).  You can also use this if you have a very strange configuration (for example, multiple instances using different Unix-domain sockets but the same port): Specify connection options using libpq environment variables and use the \fB\-P\fR option to tell \fBpex\fR to get the data directory by connecting to a running PostgreSQL instance.
.
.SS "Other Options"
.TP
\fB\-S\fR
When installing a package, run the actual installation part (but not the downloading, building, etc.) under \fBsudo\fR.  You might need to use this if you run \fBpex\fR as an unprivileged user but want to install into the system installation of PostgreSQL.  (Alternatively, you could run \fBpex\fR itself under \fBsudo\fR or something similar, but then the downloading and building also runs with higher privileges, which might be less desirable.)
.
.SS "Global Options"
These options are only processed when they are the sole command-line argument.
.TP
\fB\-\-cache\fR
Print location of cache directory (see also under FILES below).
.
.TP
\fB\-\-help\fR
Show help.
.
.TP
\fB\-\-repository\fR
Print location of Git repository with the package description files (see also under FILES below).
.
.SH ENVIRONMENT
.TP
BROWSER
Web browser to use for opening package home pages.
.TP
EDITOR
Text editor to use.
.TP
XDG_CACHE_HOME, XDG_DATA_HOME
Override locations for cache and data files.  See section FILES.
.
.SH FILES
.TP
\fI$XDG_CACHE_HOME/pex/\fR, default \fI~/.cache/pex/\fR
Downloaded package archive files and build trees are stored under this directory.  You can remove things from here without too much concern.
.
.TP
\fI$XDG_DATA_HOME/pex/\fR, default \fI~/.local/share/pex/\fR
Package description files (normally a Git repository) are stored under this directory.
.
.TP
$(pg_config \-\-sharedir)\fI/pex/\fR
This directory contains information about what packages are installed.  You can remove it if it bothers you, but then it is not possible to query what packages are installed, and the upgrade functionality won't know what to do.
.
.SH NOTES
\fBpex\fR uses \fBcurl\fR and \fBgit\fR under the hood.  See there for information on how to set up proxy access and other details.
.
.SH BUGS
For issues with \fBpex\fR itself, see \fIhttps://github\.com/petere/pex/issues\fR.

For issues with package descriptions and for proposals for new packages, see \fIhttps://github\.com/petere/pex-packages/issues\fR.
.
.SH EXAMPLES
Run this once:
.RS
pex init
.RE

Search for a package:
.RS
pex search hash
.RE

Install a package:
.RS
pex install pghashlib
.RE

Fetch new package descriptions:
.RS
pex update
.RE

Upgrade all installed packages:
.RS
pex upgrade
.RE

Install a package into several PostgreSQL installations:
.RS
pex \-p 5432 install pghashlib
.br
pex \-p 5433 install pghashlib
.br
pex \-p 5434 install pghashlib
.RE
.
.SH AUTHORS
Peter Eisentraut
.
.SH "SEE ALSO"
.BR curl (1),
.BR git (1),
.BR pg_config (1)

Pex home page: \fIhttps://github\.com/petere/pex\fR