Before anyone can access
the database you must start the database server. The database
server is called postmaster. The
postmaster must know where to find the data it is supposed to
work on. This is done with the -D
option. Thus, the simplest way to start the server is, for
example,
$ postmaster -D /usr/local/pgsql/data
which will leave the server running in the foreground. This
must again be done while logged into the PostgreSQL user account. Without a
-D, the server will try to use the
data directory in the environment variable PGDATA; if neither of these works it will fail.
To start the postmaster in the background, use the usual shell syntax:
$ postmaster -D /usr/local/pgsql/data > logfile 2>&1 &
It is an extremely good idea to keep the server's stdout and stderr output around somewhere, as suggested here. It will help both for auditing purposes and to diagnose problems. (See Section 8.3 for a more thorough discussion of log file handling.)
The postmaster also
takes a number of other command line options. For more
information see the reference page and Section 3.4 below. In particular, in
order for the server to accept TCP/IP connections (rather than
just Unix domain socket ones), you must also specify the
-i option.
This shell syntax can get tedious quickly. Therefore the shell script wrapper pg_ctl is provided that encapsulates some of the tasks. E.g.,
pg_ctl start -l logfile
will start the server in the background and put the output
into the named log file. The -D
option has the same meaning as when invoking postmaster directly.
pg_ctl also implements a
symmetric "stop" operation.
Normally, you will want to start the database server when the computer boots up. This is not required; the PostgreSQL server can be run successfully from non-privileged accounts without root intervention.
Different systems have different conventions for starting up daemons at boot time, so you are advised to familiarize yourself with them. Many systems have a file /etc/rc.local or /etc/rc.d/rc.local which is almost certainly no bad place to put such a command. Whatever you do, the server must be run by the PostgreSQL user account and not by root or any other user. Therefore you probably always want to form your command lines along the lines of su -c '...' postgres, for example:
su -c 'pg_ctl start -D /usr/local/pgsql/data -l serverlog' postgres
Here are a few more operating system specific suggestions. (Always replace the proper installation directory and the user name you chose.)
For FreeBSD, take a look at the file contrib/start-scripts/freebsd in the PostgreSQL source distribution.
On OpenBSD, add the following lines to the file /etc/rc.local:
if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postmaster ]; then
su - -c '/usr/local/pgsql/bin/pg_ctl start -l /var/postgresql/log -s' postgres
echo -n ' postgresql'
fi
/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data
to /etc/rc.d/rc.local or look into the file contrib/start-scripts/linux in the PostgreSQL source distribution to integrate the start and shutdown into the run level system.
On NetBSD, either use the FreeBSD or Linux start scripts, depending on preference, as an example and place the file at /usr/local/etc/rc.d/postgresql.
On Solaris, create a file called /etc/init.d/postgresql to contain the following single line:
su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data"
Then, create a symbolic link to it in /etc/rc3.d as S99postgresql.
While the postmaster is running, its PID is in the file postmaster.pid in the data directory. This is used as an interlock against multiple postmasters running in the same data directory, and can also be used for shutting down the postmaster.
There are several common reasons for the postmaster to fail to start up. Check the postmaster's log file, or start it by hand (without redirecting standard output or standard error) to see what complaint messages appear. Some of the possible error messages are reasonably self-explanatory, but here are some that are not.
FATAL: StreamServerPort: bind() failed: Address already in use
Is another postmaster already running on that port?
This usually means just what it suggests: you tried to start a second postmaster on the same port where one is already running. However, if the kernel error message is not Address already in use or some variant of that wording, there may be a different problem. For example, trying to start a postmaster on a reserved port number may draw something like
$ postmaster -i -p 666
FATAL: StreamServerPort: bind() failed: Permission denied
Is another postmaster already running on that port?
A message like
IpcMemoryCreate: shmget(key=5440001, size=83918612, 01600) failed: Invalid argument FATAL 1: ShmemCreate: cannot create region
probably means that your kernel's limit on the size of
shared memory areas is smaller than the buffer area that
PostgreSQL is trying to create
(83918612 bytes in this example). Or it could mean that you
don't have System-V-style shared memory support configured into
your kernel at all. As a temporary workaround, you can try
starting the postmaster with a smaller-than-normal number of
buffers (-B switch). You will
eventually want to reconfigure your kernel to increase the
allowed shared memory size, however. You may see this message
when trying to start multiple postmasters on the same machine,
if their total space requests exceed the kernel limit.
An error like
IpcSemaphoreCreate: semget(key=5440026, num=16, 01600) failed: No space left on device
does not mean that
you've run out of disk space; it means that your kernel's limit
on the number of System V semaphores is smaller than the number
PostgreSQL wants to create. As
above, you may be able to work around the problem by starting
the postmaster with a reduced number of backend processes
(-N switch), but you'll eventually
want to increase the kernel limit.
If you get an "illegal system call" error, then it is likely that shared memory or semaphores are not supported at all in your kernel. In that case your only option is to re-configure the kernel to turn on these features.
Details about configuring System V IPC facilities are given in Section 3.5.1.
Although the possible error conditions on the client side are both virtually infinite and application-dependent, a few of them might be directly related to how the server was started up. Conditions other than those shown below should be documented with the respective client application.
psql: could not connect to server: Connection refused
Is the server running on host server.joe.com and accepting
TCP/IP connections on port 5432?
This is the generic "I couldn't find a
server to talk to" failure. It looks like the above when
TCP/IP communication is attempted. A common mistake is to
forget the -i option to allow the
postmaster to accept TCP/IP connections.
Alternatively, you'll get this when attempting Unix-socket communication to a local postmaster:
psql: could not connect to server: Connection refused
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
The last line is useful in verifying that the client is trying to connect where it is supposed to. If there is in fact no postmaster running there, the kernel error message will typically be either Connection refused or No such file or directory, as illustrated. (It is particularly important to realize that Connection refused in this context does not mean that the postmaster got your connection request and rejected it -- that case will produce a different message, as shown in Section 4.3.) Other error messages such as Connection timed out may indicate more fundamental problems, like lack of network connectivity.