3.3. Starting the Database Server

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 use. This is done with the -D option. Thus, the simplest way to start the server is:

$ postmaster -D /usr/local/pgsql/data

which will leave the server running in the foreground. This must be done while logged into the PostgreSQL user account. Without -D, the server will try to use the data directory in the environment variable PGDATA. If neither of these succeed, 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 important to store the server's stdout and stderr output somewhere, as shown above. It will help for auditing purposes and to diagnose problems. (See Section 8.4 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 specify the -i option.

This shell syntax can get tedious quickly. Therefore the shell script wrapper pg_ctl is provided to simplify some tasks. For example:

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 here as in the postmaster. pg_ctl is also capable of stopping the server.

Normally, you will want to start the database server when the computer boots. Autostart scripts are operating system-specific. There are a few distributed with PostgreSQL in the /contrib/start-scripts directory. This may require root privileges.

Different systems have different conventions for starting up daemons at boot time. Many systems have a file /etc/rc.local or /etc/rc.d/rc.local. Others use rc.d directories. Whatever you do, the server must be run by the PostgreSQL user account and not by root or any other user. Therefore you probably should form your commands using 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 these with the proper installation directory and the user name.)

For FreeBSD, 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

On Linux systems either add
```
/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data
```
to /etc/rc.d/rc.local or look at the file contrib/start-scripts/linux in the PostgreSQL source distribution.
On NetBSD, either use the FreeBSD or Linux start scripts, depending on preference.
On Solaris, create a file called /etc/init.d/postgresql which should contain the following 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 to prevent multiple postmasters running in the same data directory, and can also be used for shutting down the postmaster.

3.3.1. Server Start-up Failures

There are several common reasons the postmaster might fail to start. Check the postmaster's log file, or start it by hand (without redirecting standard output or standard error) and see what error messages appear. Some of the error messages are self-explanatory, but some are not, as shown below:

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 another 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, 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 your kernel's limit on the size of shared memory is smaller than the buffer area 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. You may see this message when trying to start multiple postmasters on the same machine if their total space requested exceeds the kernel limit.

An error like:

IpcSemaphoreCreate: semget(key=5440026, num=16, 01600) failed: No space left on device

does not mean you've run out of disk space. It means 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 allowed connections (-N switch), but you'll eventually want to increase the kernel limit.

If you get an "illegal system call" error, it is likely that shared memory or semaphores are not supported in your kernel at all. In that case your only option is to reconfigure the kernel to enable these features.

Details about configuring System V IPC facilities are given in Section 3.5.1.

3.3.2. Client Connection Problems

Although the error conditions possible on the client side are quite varied 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 to the right place. 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 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 6.3.) Other error messages such as Connection timed out may indicate more fundamental problems, like lack of network connectivity.