In this chapter, we will cover what can go wrong during the installation process and what can be done to avoid those things from happening. At the end of the chapter, you should be able to avoid all of the pitfalls, traps, and dangers you might face during the setup process.
For this chapter, I have compiled some of the core problems that I have seen over the years, as follows:
Deciding on a version during installation
Memory and kernel issues
Preventing problems by adding checksums to your database instance
Wrong encodings and subsequent import errors
Polluted template databases
Killing the postmaster badly
At the end of the chapter, you should be able to install PostgreSQL and protect yourself against the most common issues popping up immediately after installation.
9.4.0, 9.4.1, or 9.4.2
9.3.4, 9.3.5, or 9.3.6
The last digit is the so-called minor release. When a new minor release is issued, it generally means that some bugs have been fixed (for example, some time zone changes, crashes, and so on). There will never be new features, missing functions, or changes of that sort in a minor release. The same applies to something truly importantâthe storage format. It won't change with a new minor release.
These little facts have a wide range of consequences. As the binary format and the functionality are unchanged, you can simply upgrade your binaries, restart PostgreSQL, and enjoy your improved minor release.
When the digit in the middle changes, things get a bit more complex. A changing middle digit is called a major release. It usually happens around once a year and provides you with significant new functionality. If this happens, we cannot just stop or start the database anymore to replace the binaries. In this case, we face a real migration process, which will be discussed later on in this book.
If the first digit changes, something really important has happened. Examples of such important events were introductions of SQL (6.0), the Windows port (8.0), streaming replication (9.0), and so on. Technically, there is no difference between the first and the second digitâthey mean the same thing to the end user. However, a migration process is needed.
The question that now arises is this: if you have a choice, which version of PostgreSQL should you use? Well, in general, it is a good idea to take the latest stable release. In PostgreSQL, every version number following the design patterns I just outlined is a stable release.
Installing binary packages
Installing from source
Installing from source is not too hard to do. However, this chapter will focus on installing binary packages only. Nowadays, most people (not including me) like to install PostgreSQL from binary packages because it is easier and faster.
Basically, two types of binary packages are common these days: RPM (Red Hat-based) and DEB (Debian-based). In this chapter, installing these two types of packages will be discussed.
Most Linux distributions include PostgreSQL. However, the shipped PostgreSQL version is somewhat ancient in many cases. Recently, I saw a Linux distribution that still featured PostgreSQL 8.4, a version already abandoned by the PostgreSQL community. Distributors tend to ship older versions to ensure that new bugs are not introduced into their systems. For high-performance production servers, outdated versions might not be the best idea, however.
Clearly, for many people, it is not feasible to run long-outdated versions of PostgreSQL. Therefore, it makes sense to make use of repositories provided by the community. The Yum repository shows which distributions we can use RPMs for, at http://yum.postgresql.org/repopackages.php.
Once you have found your distribution, the first thing is to install this repository information for Fedora 20 as it is shown in the next listing:
yum install http://yum.postgresql.org/9.4/fedora/fedora-20-x86_64/pgdg-fedora94-9.4-1.noarch.rpm
Once the repository has been added, we can install PostgreSQL:
yum install postgresql94-server postgresql94-contrib /usr/pgsql-9.4/bin/postgresql94-setup initdb systemctl enable postgresql-9.4.service systemctl start postgresql-9.4.service
First of all, PostgreSQL 9.4 is installed. Then a so-called database instance is created (
initdb). Next, the service is enabled to make sure that it is always there after a reboot, and finally, the postgresql-9.4 service is started.
Installing Debian packages is also not too hard. By the way, the process on Ubuntu as well as on some other similar distributions is the same as that on Debian, so you can directly use the knowledge gained from this section for other distributions.
A simple file called
/etc/apt/sources.list.d/pgdg.list can be created, and a line for the PostgreSQL repository (all the following steps can be done as root user or using
sudo) can be added:
deb http://apt.postgresql.org/pub/repos/apt/ YOUR_DEBIAN_VERSION_HERE-pgdg main
So, in the case of Debian Wheezy, the following line would be useful:
deb http://apt.postgresql.org/pub/repos/apt/ wheezy-pgdg main
Once we have added the repository, we can import the signing key:
$# wget --quiet -O - \ https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - OK
VoilÃ ! Things are mostly done. In the next step, the repository information can be updated:
Once this has been done successfully, it is time to install PostgreSQL:
apt-get install "postgresql-9.4"
If no error is issued by the operating system, it means you have successfully installed PostgreSQL. The beauty here is that PostgreSQL will fire up automatically after a restart. A simple database instance has also been created for you.
If everything has worked as expected, you can give it a try and log in to the database:
[email protected]:~# su - postgres $ psql postgres psql (9.4.1) Type "help" for help. postgres=#
Some of the most important issues are related to the kernel and memory. Up to version 9.2, PostgreSQL was using the classical system V shared memory to cache data, store locks, and so on. Since PostgreSQL 9.3, things have changed, solving most issues people had been facing during installation.
However, in PostgreSQL 9.2 or before, you might have faced the following error message:
HINT: This error usually means that PostgreSQL's request for a shared memory segment exceeded your kernel's
SHMMAXparameter. You can either reduce the request size or reconfigure the kernel with larger
SHMMAX. To reduce the request size (currently 1122263040 bytes), reduce PostgreSQL's shared memory usage, perhaps by reducing shared_buffers or max_connections.
If the request size is already small, it's possible that it is less than your kernel's
SHMMIN parameter, in which case raising the request size or reconfiguring
SHMMIN is called for.
The PostgreSQL documentation contains more information about shared memory configuration.
If you are facing a message like this, it means that the kernel does not provide you with enough shared memory to satisfy your needs. Where does this need for shared memory come from? Back in the old days, PostgreSQL stored a lot of stuff, such as the I/O cache (shared_buffers, locks, autovacuum-related information and a lot more), in the shared memory. Traditionally, most Linux distributions have had a tight grip on the memory, and they don't issue large shared memory segments; for example, Red Hat has long limited the maximum amount of shared memory available to applications to 32 MB. For most applications, this is not enough to run PostgreSQL in a useful wayâespecially not if performance does matter (and it usually does).
To fix this problem, you have to adjust kernel parameters. Managing Kernel Resources of the PostgreSQL Administrator's Guide will tell you exactly why we have to adjust kernel parameters.
For more information, check out the PostgreSQL documentation at http://www.postgresql.org/docs/9.4/static/kernel-resources.htm.
Since not all operating systems can be covered in this little book, only Linux and Mac OS X will be discussed here in detail.
$ sysctl -w kernel.shmmax=17179869184 $ sysctl -w kernel.shmall=4194304
In this example,
shmall have been adjusted to 16 GB. Note that
shmmax is in bytes while
shmall is in 4k blocks. The kernel will now provide you with a great deal of shared memory.
SEMMNS: This is the maximum number of system-wide semaphores. It should be at least ceil((max_connections + autovacuum_max_workers + 4) / 16) * 17, and it should have room for other applications in addition to this.
kern.sysv.shmmax=4194304 kern.sysv.shmmin=1 kern.sysv.shmmni=32 kern.sysv.shmseg=8 kern.sysv.shmall=1024
Mac OS X is somewhat nasty to configure. The reason is that you have to set all five parameters to make this work. Otherwise, your changes will be silently ignored, and this can be really painful.
In addition to that, it has to be assured that
SHMMAX is an exact multiple of 4096. If it is not, trouble is near.
If you want to change these parameters on the fly, recent versions of OS X provide a
systcl command just like Linux. Here is how it works:
sysctl -w kern.sysv.shmmax sysctl -w kern.sysv.shmmin sysctl -w kern.sysv.shmmni sysctl -w kern.sysv.shmseg sysctl -w kern.sysv.shmall
If you are planning to run a large-scale system, it can also be beneficial to raise the maximum number of open files allowed. To do that,
/etc/security/limits.conf can be adapted, as shown in the next example:
postgres hard nofile 1024 postgres soft nofile 1024
This example says that the
postgres user can have up to 1,024 open files per session.
Note that this is only important for large systems; open files won't hurt an average setup.
When PostgreSQL is installed, a so-called database instance is created. This step is performed by a program called
initdb, which is a part of every PostgreSQL setup. Most binary packages will do this for you and you don't have to do this by hand.
Why should you care then? If you happen to run a highly critical system, it could be worthwhile to add checksums to the database instance. What is the purpose of checksums? In many cases, it is assumed that crashes happen instantlyâsomething blows up and a system fails. This is not always the case. In many scenarios, the problem starts silently. RAM may start to break, or the filesystem may start to develop slight corruption. When the problem surfaces, it may be too late. Checksums have been implemented to fight this very problem. Whenever a piece of data is written or read, the checksum is checked. If this is done, a problem can be detected as it develops.
How can those checksums be enabled? All you have to do is to add
initdb (just change your init scripts to enable this during instance creation). Don't worry! The performance penalty of this feature can hardly be measured, so it is safe and fast to enable its functionality.
Keep in mind that this feature can really help prevent problems at fairly low costs (especially when your I/O system is lousy).
Encoding-related problems are some of the most frequent problems that occur when people start with a fresh PostgreSQL setup. In PostgreSQL, every database in your instance has a specific encoding. One database might be
[email protected], while some other database might have been created as
[email protected] (which denotes German as it is used in Austria).
To figure out which encodings your database system is using, try to run
psql -l from your Unix shell. What you will get is a list of all databases in the instance that include those encodings.
So where can we actually expect trouble? Once a database has been created, many people would want to load data into the system. Let's assume that you are loading data into the
aUTF-8 database. However, the data you are loading contains some ASCII characters such as
Ã¶, and so on. The ASCII code for
Ã¶ is 148. Binary 148 is not a valid Unicode character. In Unicode, U+00F6 is needed. Boom! Your import will fail and PostgreSQL will error out.
If you are planning to load data into a new database, ensure that the encoding or character set of the data is the same as that of the database. Otherwise, you may face ugly surprises.
test=# \h CREATE DATABASE Command: CREATE DATABASE Description: create a new database Syntax: CREATE DATABASE name [ [ WITH ] [ OWNER [=] user_name ] [ TEMPLATE [=] template ] [ ENCODING [=] encoding ] [ LC_COLLATE [=] lc_collate ] [ LC_CTYPE [=] lc_ctype ] [ TABLESPACE [=] tablespace_name ] [ CONNECTION LIMIT [=] connlimit ] ]
ENCODING and the
LC* settings are used here to define the proper encoding for your new database.
It is somewhat important to understand what happens during the creation of a new database in your system. The most important point is that
CREATE DATABASE (unless told otherwise) clones the
template1 database, which is available in all PostgreSQL setups.
This cloning has some important implications. If you have loaded a very large amount of data into
template1, all of that will be copied every time you create a new database. In many cases, this is not really desirable but happens by mistake. People new to PostgreSQL sometimes put data into
template1 because they don't know where else to place new tables and so on. The consequences can be disastrous.
After PostgreSQL has been installed and started, many people wonder how to stop it. The most simplistic way is, of course, to use your
/etc/init.d/postgresql stop init scripts.
However, some administrators tend to be a bit crueler and use
kill -9 to terminate PostgreSQL. In general, this is not really beneficial because it will cause some nasty side effects. Why is this so?
The PostgreSQL architecture works like this: when you start PostgreSQL you are starting a process called postmaster. Whenever a new connection comes in, this postmaster forks and creates a so-called
backend process (BE). This process is in charge of handling exactly one connection. In a working system, you might see hundreds of processes serving hundreds of users. The important thing here is that all of those processes are synchronized through some common chunk of memory (traditionally, shared memory, and in the more recent versions, mapped memory), and all of them have access to this chunk. What might happen if a database connection or any other process in the PostgreSQL infrastructure is killed with
kill -9? A process modifying this common chunk of memory might die while making a change. The process killed cannot defend itself against the onslaught, so who can guarantee that the shared memory is not corrupted due to the interruption?
This is exactly when the postmaster steps in. It ensures that one of these backend processes has died unexpectedly. To prevent the potential corruption from spreading, it kills every other database connection, goes into recovery mode, and fixes the database instance. Then new database connections are allowed again.
While this makes a lot of sense, it can be quite disturbing to those users who are connected to the database system. Therefore, it is highly recommended not to use
kill -9. A normal kill will be fine.