The PostgreSQL How to Guide instructs Solaris system administrators and database professionals in the process of configuring and running PostgreSQL on a Solaris 10 system. This guide covers launching and setting up the PostgreSQL database using the Solaris Service Management Facility (SMF), and configuring PostgreSQL to run in a Solaris Container technology called Solaris Zones. The user will then be able to verify and test the PostgreSQL data base.
This guide assumes that the release of Solaris being used is the Solaris 10 6/06 operating system or later. Starting with Solaris 10 6/06, PostgreSQL has been integrated with the operating system and can be installed with Solaris. If an earlier version of Solaris 10 (e.g. Solaris 10 1/06 or Solaris 10 3/05 ) is used, PostgreSQL must be installed on the system. Instructions on finding the packages and how to perform the install are included at the end of this guide.
This guide is not exhaustive and does not cover all optional features of these technologies. However, the reference section provided at the end of the document provides pointers to where administrators can learn more.
PDF[246K] |
Table of Contents
|
|
Back To Top
PostgreSQL is shipped with both Solaris Express Developer Edition (SXDE) and Solaris 10. Depending on which Solaris 10 update you're using, the instructions may be different.
Solaris Express Developer Edition
SXDE 5/07 includes PostgreSQL 8.1 and 8.2.
# chown postgres:postgres /var/lib/pgsql/data
# su - postgres
$ /usr/bin/initdb -D /var/lib/pgsql/data
# /usr/sbin/svcadm enable postgresql:version_81
# su - postgres
$ /usr/postgres/8.2/bin/initdb -D /var/postgres/8.2/data
# /usr/sbin/svcadm enable postgresql:version_82
The binaries for PostgreSQL 8.1 and 8.2 are located in /usr/bin and /usr/postgres/8.2/bin, respectively. To use 8.2, make sure to add /usr/postgres/8.2/bin to PATH.
It is possible to run both PostgreSQL 8.1 and 8.2 servers at the same time as long as the port numbers are different.
The data directory used above are the defaults, but you can put the database anywhere. Just make sure the SMF property for data directory is changed appropriately. See postgres_82 man page (e.g. run "man postgres_82" from the command prompt) for more information.
Solaris 10 6/06 or 11/06
Once you have successfully installed Solaris 10, there are a few steps that you will need to perform before you can start the database.
# groupadd postgres
# useradd -c 'PostgreSQL user' -d /export/home/postgres -g postgres -m -s
/bin/bash postgres
# chown postgres /var/lib/pgsql/data
# chmod 700 /var/lib/pgsql/data
$ initdb -D /var/lib/pgsql/data
$ pg_ctl -D /var/lib/pgsql/data -l postmaster.log start
$ psql postgres
To configure the database, modify the postgresql.conf file in the database cluster directory used in step 3. For tuning tips on Solaris, visit http://www.sun.com/servers/coolthreads/tnb/applications_postgresql.jsp.
Back To Top
PostgreSQL has been integrated with SMF in Solaris Express Developer Edition. If you are using Solaris 10 6/06 or 11/06 and want the SMF enabled PostgreSQL, you will have to do that manually with the following steps.
SMF creates a standardized control mechanism for application services by turning them into first-class objects that administrators can observe and manage in a uniform way. These services can then be automatically restarted if they are accidentally terminated by an administrator, if they are aborted as the result of a software programming error, or if they are interrupted by an underlying hardware problem. SMF is simple to use. Developers can convert most existing applications to take full advantage of SMF features just by adding a simple service manifest (XML file) to each application and using a few SMF commands to import the service description and activate the service.
Below are the SMF service manifest and accompanying shell script needed to integrate PostgreSQL with Solaris SMF.
Perform the following steps to import the manifest into the SMF repository.
"/usr/share/lib/xml/dtd/service_bundle.dtd.1">
name='application/database/postgresql'
type='service'
version='1'>
name='network'
grouping='require_all'
restart_on='none'
type='service'>
name='filesystem-local'
grouping='require_all'
restart_on='none'
type='service'>
type='method'
name='start'
exec='/lib/svc/method/postgresql start'
timeout_seconds='300' />
type='method'
name='stop'
exec='/lib/svc/method/postgresql stop'
timeout_seconds='300' />
type='method'
name='refresh'
exec='/lib/svc/method/postgresql refresh'
timeout_seconds='60' />
value='/var/lib/pgsql/data' />
value='postmaster.log' />
value='/var/lib/pgsql/data2' />
value='postmaster.log' />
PostgreSQL RDBMS
uri='http://postgresql.org' />
The default instance of the manifest assumes that the database user is postgres, database cluster directory is /var/lib/pgsql/data and the postmaster log file is postmaster.log. If any of them is different, update the above XML accordingly or use the svccfg command to change this property after the manifest has been imported. See the examples below.
#!/sbin/sh
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
# Copyright 2006 Sun Microsystems, Inc. All rights reserved.
# Use is subject to license terms.
#
# ident "%Z%%M% %I% %E SMI"
. /lib/svc/share/smf_include.sh
# SMF_FMRI is the name of the target service. This allows multiple instances
# to use the same script.
getproparg()
{ val=`svcprop -p $1 $SMF_FMRI`
[ -n "$val" ] && echo $val
}
PGBIN=/usr/bin
PGDATA=`getproparg postgresql/data`
PGLOG=`getproparg postgresql/log`
if [ -z $SMF_FMRI ]; then
echo "SMF framework variables are not initialized."
exit $SMF_EXIT_ERR
fi
if [ -z $PGDATA ]; then
echo "postgresql/data property not set"
exit $SMF_EXIT_ERR_CONFIG
fi
if [ -z $PGLOG ]; then
echo "postgresql/log property not set"
exit $SMF_EXIT_ERR_CONFIG
fi
case "$1" in
'start')
$PGBIN/pg_ctl -D $PGDATA -l $PGDATA/$PGLOG start
;;
'stop')
$PGBIN/pg_ctl -D $PGDATA stop
;;
'refresh')
$PGBIN/pg_ctl -D $PGDATA reload
;;
*)
echo $"Usage: $0 {start|refresh}"
exit 1
;;
esac
exit $SMF_EXIT_OK
# cd /var/svc/manifest/application/database
# /usr/sbin/svccfg import postgresql.xml
# svcs postgresql
# /usr/sbin/svcadm enable postgresql:defaultFrom this point on the PostgreSQL process is controlled by the Solaris SMF, and the administrator can change its state by using the svcadm command. If the service is terminated for some reason, the SMF restarter daemon will attempt to restart it, and at system reboot the service will be started automatically unless it is disabled.
# svcadm disable postgresql:defaultTo change the database cluster directory to "/pgdata" for the default instance, execute:
# svccfg -s postgresql:default setprop method_context/user = "foo"
# svcadm refresh postgresql:default
# svcadm enable postgresql:default
# svcadm disable postgresql:defaultFor more details on how to use SMF, please read the smf(5) man page or online documentation at http://docs.sun.com/app/docs/doc/817-1985/6mhm8o5rh?a=view.
# svccfg -s postgresql:default setprop postgresql/data = "/pgdata"
# svcadm refresh postgresql:default
# svcadm enable postgresql:default
Solaris Zones, a part of Solaris Containers technology, is used to virtualize operating system services and provide an isolated and secure environment for running applications. A zone is a virtualized operating system environment created within a single instance of the Solaris Operating System. When you create a zone, you produce an application execution environment in which processes are isolated from the rest of the system. This isolation prevents processes that are running in one zone from monitoring or affecting processes that are running in other zones. Even a process running with superuser credentials cannot view or affect activity in other zones.
The following example will demonstrate the first approach, with PostgreSQL binary installed in the global zone and using a sparse root zone to run the process.
Before creating a Solaris Zone, decide on a directory where it will reside. In this example, the zone will be installed in /export/zones/pg_zone. Make sure to limit the access of this directory to only the user with read, write, and execute permission (e.g chmod 700 /export/zones/pg_zone).
Note: For more detailed, step-by-step instructions on configuring zones, visit the Solaris Containers how to guide at sun.com/solaris/howtoguides.
global# zonecfg -z pg_zoneThis will return the message "pg_zone: No such zone configured" before prompting you to begin configuring a new zone. You are now in the zonecfg shell that is identified by its prompt:"zonecfg:email-zone>".
zonecfg:pg_zone> createNote: Change "address" and "physical" to the appropriate IP address and name of interface card, respectively.
zonecfg:pg_zone> set zonepath=/export/zones/pg_zone
zonecfg:pg_zone> set autoboot=true
zonecfg:pg_zone> add net
zonecfg:pg_zone:net> set address=10.6.222.74/24
zonecfg:pg_zone:net> set physical=ipge0
zonecfg:pg_zone:net> end
zonecfg:pg_zone> verify
zonecfg:pg_zone> commit
zonecfg:pg_zone> exit
At this point a zone configuration file is created in /etc/zones/pg_zone.xml
global# zoneadm -z pg_zone install
This can take a few minutes.
global# zoneadm list -iv
global# zoneadm -z pg_zone boot
global# zlogin -C pg_zone
The first time you log in to the console, you are prompted to answer a series of questions.
At this point the newly created zone is ready to use. You can proceed to setup PostgreSQL in the zone.
global# zonecfg -z pg_zone
zonecfg:pg_zone> add fs
zonecfg:pg_zone:fs> set type=ufs
zonecfg:pg_zone:fs> set special=/dev/dsk/c1t1d0s0
zonecfg:pg_zone:fs> set raw=/dev/rdsk/c1t1d0s0
zonecfg:pg_zone:fs> set dir=/pg_log
zonecfg:pg_zone:fs> end
zonecfg:pg_zone> verify
zonecfg:pg_zone> commit
zonecfg:pg_zone> exit
Change the properties "special", "raw", and "dir" appropriately for your environment.
Back To Top
This section only applies when using Solaris 10 3/05 or 1/06 releases.
Obtaining the PackagesThe packages can be downloaded from http://pgfoundry.org/projects/solarispackages/
The table below lists all the packages and what they are used for. For a complete list of files in each package see the pkgmap file in each package.
|
Back To Top
To remain in compliance with the Solaris OS, the PostgreSQL for Solaris packages install files in various locations which are different than the default locations found in PostgreSQL documentation. According to the PostgreSQL documentation, PostgreSQL is installed under the directory /usr/local/pgsql, with executables, source, and data existing in various subdirectories.
Different distributions have different recommended file locations. In particular, the documentation directory can be /usr/doc, /usr/doc/packages, /usr/share/doc, /usr/share/doc/packages, or some other similar path. The Solaris locations are listed below:
|
Back To Top
This section only applies when using Solaris 10 3/05 or Solaris 10 1/06 releases.
To quickly get PostgreSQL up and running, you can install a subset of the packages available. See the table above for further information. Here are a couple of scenarios:
If a package depends on other package(s), you will need to install these dependencies first. You will be notified of these dependencies during install.
Solaris packages are installed using the pkgadd command. This command transfers the contents of a software package from the distribution medium or directory and installs it onto a system.
This section provides basic installation instructions for installing your package in order to verify that it installs correctly.
# pkgadd -d device-name [ pkg-abbrev...]
device-name
specifies the location of the package. Note that device-name can be a full directory path name or the identifiers for a tape, floppy disk, or removable disk.
pkg-abbrev
Is the name of one or more packages (separated by spaces) to be added. If omitted, pkgadd installs all available packages.
For example, the following command will install SUNWpostgr-libs package from the current directory:
# pkgadd -d . SUNWpostgr-libs
After you have installed all the necessary packages, refer to "Starting PostgreSQL for the First Time" section above to run the database.
Back To Top
If you're installing PostgreSQL on Solaris 10 3/05 or 1/06, you will need to install Python patch 121606-01 before using PL/Python procedural language. The Python patch can be downloaded from: http://pgfoundry.org/projects/solarispackages.
Refer to the man pages for instructions on using 'patchadd' and 'patchrm' scripts provided with Solaris. To install the patch follow these steps:
# patchadd /var/tmp/121606-01
The above command will take a few minutes, so be patient. After the patch is installed successfully, you can proceed to use PL/Python.
Note: If you encounter patchadd or patchrm problems, such as "wordlist too large" messages while installing this patch, you may need to install the following patch:
119254-02 (or newer) Install and Patch Utilities Patch
Back To Top
You shouldn't need to remove PostgreSQL packages, but if you choose to, it is recommended that you execute a full database dump (and possibly a filesystem level backup) before removing Solaris packages. Because the pkgrm command updates information in the software products database, it is important when you remove a package to use the pkgrm command, even though you might be tempted to use the rm command instead. For example, you could use the rm command to remove a binary executable file, but that is not the same as using pkgrm to remove the software package that includes that binary executable. Using the rm command to remove a package s files will corrupt the software products database. (If you really only want to remove one file, you can use the removef command, which will update the software product database correctly.)
# pkgrm pkg-list ...
pkg-list
Is the name of one or more packages (separated by spaces). If omitted, pkgrm removes all available packages. # pkginfo | egrep pkg-abbrev
If pkg-abbrev is installed, the pkginfo command returns a line of information about it. Otherwise, pkginfo returns the system prompt.
You should stop all server processes before removing packages.
Note: If you have created database clusters in /var/lib/pgsql/data directory, any newly created files and directories will not be removed by a pkgrm of SUNWpostgr-server-data package. If you want to remove the database content, you have to do it manually.
Back To Top
Fully integrated into Solaris 10 with flexible support offerings from Sun, PostgreSQL on Solaris 10 is an enterprise-class open source database. When combined with the reliable, stable Solaris Operating System, customers can use PostgreSQL for a majority of the commercial database needs. Customers now have the additional reassurance of world-class, global 24x7 support from Sun.
Back To Top
While this How to Guide provides a user with the basic steps required to get started with a PostgreSQL database on Solaris 10, more information on varying configurations, additional Solaris 10 How to Guides and other relevant information for PostgreSQL for Solaris are referenced below.
Solaris 10 Manuals and Reference Materials
|
|
Solaris 10 Overview
|
sun.com/solaris/
|
Solaris 10 FAQ
|
sun.com/software/solaris/faq.jsp
|
Solaris 10 Datasheets and Resources
|
sun.com/solaris/teachme
|
Additional Solaris How to Guides
|
sun.com/solaris/howtoguides
|
Predictive Self-Healing Feature Information
|
sun.com/solaris/availability
|
PostgreSQL for Solaris Reference Materials
|
|
PostgreSQL for Solaris Service & Support Offering
|
sun.com/service/osdb/index.xml
|
PostgreSQL for Solaris Web site
|
sun.com/solaris/postgresql
|
Community Resources
|
|
PostgreSQL Documentation
|
postgresql.org/docs/
|
PostgreSQL for Solaris documentation
|
postgresql.org/docs/techdocs.33
|
PostgreSQL Packages for Solaris
|
pgfoundry.org/projects/solarispackages/
|