PostgreSQL One-click Installer Guide

http://www.enterprisedb.com/resources-community/pginst-guide

PostgreSQL One-click Installer Guide

Contents

• Introduction
• Mac OS X pre-installation notes
• Interactive installation
• Non-interactive installation
• Uninstallation
• Troubleshooting

Introduction

The PostgreSQL one-click installers are designed to make it quick and simple to install PostgreSQL on your computer. They provide a distribution-independent, self contained PostgreSQL installation along with the popular Open Source PostgreSQL administration tool pgAdmin and the StackBuilder package manager which can be used to download and install drivers, tools and applications to complement your PostgreSQL installation.

The one-click installers are packaged by EnterpriseDB for the PostgreSQL community, and are available for computers running Linux 32 or 64 bit, Mac OS X or Windows.

This document is based on the 8.4.x one-click installers.

Mac OS X pre-installation notes

Installation on Mac OS X is slightly different from other platforms as the distribution is in a different format and some additional configuration may be required over other operating systems.

• The Mac OS X installer is an App Bundle, which is a set of files and directories in a prescribed format. To ensure the App Bundle can be downloaded, it is packaged inside a disk image (.dmg) file. To extract the installer, simply mount the disk image and copy the installer to the desired location, or run it directly from the disk image if preferred.
• Mac OS X ships with shared memory settings which are too low for running PostgreSQL by default. The installer will detect this, and if possible reconfigure shared memory and then prompt you to reboot the system and rerun the installation. For more information, please see the README file in the distribution disk image.

Interactive installation

Most users will use the interactive mode for the installers. To launch the installation in interactive mode, you can normally double-click the file, or, you may choose to launch it from the command line, for example:

Linux:

# ./postgresql-8.4.0-1-linux.bin

or, if your distribution uses a privilege escalation model, such as Ubuntu:

$ sudo ./postgresql-8.4.0-1-linux.bin

Mac OS X:

$ open ./postgresql-8.4.0-1-osx.app/

Windows:

C:\> postgresql-8.4.0-1-windows.exe

On Linux and Mac OS X, you can also run the installers in command line mode. This is useful if you're installing or upgrading a remote system and only have shell access. Command line mode is not available on Windows.

Linux:

# ./postgresql-8.4.0-1-linux.bin --mode text

Mac OS X:

$ sudo ./postgresql-8.4.0-b2-2-osx.app/Contents/MacOS/installbuilder.sh --mode text

Note that on Mac OS X, if you use any command line options you must call the installer script within the App Bundle directly.

Installation walkthrough

The following screenshots show a typical installation on Mac OS X. Linux and Windows installations follow the same procedure, as do text based installations, albeit without the graphical user interface.

Privilege escalation

Some operating systems (for example, Mac OS X and Linux) will prompt you to escalate your privileges before running the installer. Enter your username and password to continue.

Introduction

The first page is an introduction. Click Next to continue.

Installation Directory

Select the directory to install PostgreSQL to and click Next to continue.

Data Directory

Select the directory in which you wish to store your data. You may also select an existing data directory which will be re-used, provided it is compatible with the server.

Password

Enter and confirm the password to be used for the superuser account (postgres) in the database cluster. On Windows, this password is also used for the service account and must match the current password if the account already exists. You can change the superuser password independently of the service account password at any time following the installation. Note that this page will not be shown ion Linux or Mac if you are reusing an existing data directory.

Port

Select the port that the server will listen on. By default, incoming connections will only be accepted from the local machine. You can change this behaviour by editing the pg_hba.conf file in the data directory and reloading the server configuration. Note that this page will not be shown if you are reusing an existing data directory.

Advanced Options

This page allows you to configure some advanced server options:

• Locale: Choose the local that the cluster will be initialised with. The [Default locale] option will allow the initdbprogram to try to determine the appropriate locale from the environment. On Mac OS X, that is generally C.UTF8, whilst on Linux and Windows the current locale can normally be correctly determined.
• Install pl/pgsql in template1 database?: This option will install the pl/pgsql procedural language in the template1 database which means it will be present in any new databases created using that template. If you choose not to install pl/pgsql, it can be easily installed in selected databases in the future if required.

Note that this page will not be shown if you are reusing an existing data directory.

Ready to Install

If you are happy with the options you selected, click Next to begin the installation process.

Installing

The installer will copy the program files to your computer, and them initialise the database cluster and configure the server.

Completing the PostgreSQL Setup Wizard

Once the installation has finished, you will be offered the chance to run StackBuilder, with which you can download and install additional tools, popular applications and drivers to complement your PostgreSQL installation. A shortcut to run StackBuilder at any time will also be available on your Gnome/KDE/XFCE menu on Linux, Applications folder on Mac OS X, or Start Menu on Windows. You will also find additional shortcuts to run pgAdmin, the psql command line interface and to access the PostgreSQL documentation.

Non-interactive installation

If you are a software author you may wish to embed the PostgreSQL installer within your own application installer. A non-interactive installer mode is provided to allow this in which only a progress bar will be shown to the user. Parameters may be passed to the installer either on the command line, or using an option file.

In order to start the installer in non-interactive mode, the --mode command line option is used (in conjunction with any other options that are required). For example, on Mac OS X:

$ sudo ./postgresql-8.4.0-b2-2-osx.app/Contents/MacOS/installbuilder.sh --mode unattended [additional options]

Command line options

The following command line options are available to control the installation:

• --prefix <installation path>: Specifies the installation directory. Defaults to /opt/PostgreSQL/8.X on Linux,/Library/PostgreSQL/8.X on Mac OS X, and %PROGRAMFILES%\PostgreSQL\8.X on Windows.
   
• --datadir <data directory path>: Specifies the data directory. Defaults to $PREFIX/data.
   
• --superpassword <password>: Specifies the superuser (and on Windows, service account) password to use. Defaults to postgres in non-interactive mode.
   
• --port <port number>: Specifies the port number to listen on. Defaults to 5432.
   
• --locale <locale>: Specifies the locale to initialise the cluster in. Defaults to the locale detected by initdb.
   
• --create_shortcuts [1|0];: Specifies whether or not menu shortcuts should be created. Defaults to 1 (yes).
   
• --install_plpgsql [1|0];: Specifies whether or not pl/pgsql will be installed in template1. Defaults to 1 (yes).
   
• --install_runtimes [1|0]; (Windows only): Specifies whether or not install the Microsoft Visual C++ runtimes before the installation proceeds. Defaults to 1 (yes).
   

Option file

You can launch the installer using an option file, by passing the filename on the command line, for example:

# postgresql-8.4.0-1-linux.bin --optionfile /path/to/optionfile

The option file may contain the same parameters that are available on the command line, in a option=value format. For example:

prefix=/usr/local/pgsql84
datadir=/var/lib/pgsql84
port=5678

Uninstallation

If you need to uninstall PostgreSQL, you can run the uninstaller that is created during the installation process at any time. Note that the uninstaller will never remove your data directory, or the service user account. You can find the uninstaller in the installation directory, and can run it as you ran the installer. No command line options are generally required. On Windows, you can also run the uninstaller from the Add/Remove Programs control panel applet.

Troubleshooting

If you encounter any problems during installation, please check the logfile that is created in /tmp on Linux or Mac OS X or %TEMP% on Windows. The file will be called install-postgresql.log. The logfile may contain the superuser password you specified during the installation, which should be replaced before sharing the log with anyone.

 If you are unable to resolve the problem having reviewed the logfile, please search the EnterpriseDB forums as well as your favourite search engine for a solution.

If you still cannot resolve the issue, please post details of the problem, along with system details and any appropriate parts of the installation logfile to the installer forum.