September 26, 2024: PostgreSQL 17 Released!
Supported Versions: Current (17) / 16 / 15 / 14 / 13 / 12
Development Versions: devel
Unsupported versions: 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1
This documentation is for an unsupported version of PostgreSQL.
You may want to view the same page for the current version, or one of the other supported versions listed above instead.

3.2. Creating a database cluster

Before you can do anything, you must initialize a database storage area on disk. We call this a database cluster. (SQL speaks of a catalog cluster instead.) A database cluster is a collection of databases that will be accessible through a single instance of a running database server. After initialization, a database cluster will contain one database named template1. As the name suggests, this will be used as a template for subsequently created databases; it should not be used for actual work.

In file system terms, a database cluster will be a single directory under which all data will be stored. We call this the data directory or data area. It is completely up to you where you choose to store your data. There is no default, although locations such as /usr/local/pgsql/data or /var/lib/pgsql/data are popular. To initialize a database cluster, use the command initdb, which is installed with PostgreSQL. The desired file system location of your database system is indicated by the -D option, for example

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

Note that you must execute this command while being logged into the PostgreSQL user account, which is described in the previous section.

Tip: As an alternative to the -D option, you can set the environment variable PGDATA.

initdb will attempt to create the directory you specify if it does not already exist. It is likely that it won't have the permission to do so (if you followed our advice and created an unprivileged account). In that case you should create the directory yourself (as root) and transfer ownership of it to the PostgreSQL user account. Here is how this might work:

root# mkdir /usr/local/pgsql/data
root# chown postgres /usr/local/pgsql/data
root# su postgres
postgres$ initdb -D /usr/local/pgsql/data

initdb will refuse to run if the data directory looks like it belongs to an already initialized installation.

Because the data directory contains all the data stored in the database, it is essential that it be well secured from unauthorized access. initdb therefore revokes access permissions from everyone but the PostgreSQL user account.

However, while the directory contents are secure, the default pg_hba.conf authentication method of trust allows any local user to connect to the database and even become the database superuser. If you don't trust other local users, we recommend you use initdb's option -W or --pwprompt to assign a password to the database superuser. After initdb, modify pg_hba.conf to use md5 or password, instead of trust, authentication before you start the server for the first time. (Other, possibly more convenient approaches include using ident authentication or file system permissions to restrict connections. See Chapter 4 for more information.)

One surprise you might encounter while running initdb is a notice similar to this one:

NOTICE:  Initializing database with en_US collation order.
        This locale setting will prevent use of index optimization for
        LIKE and regexp searches.  If you are concerned about speed of
        such queries, you may wish to set LC_COLLATE to "C" and
        re-initdb.  For more information see the Administrator's Guide.

This notice is intended to warn you that the currently selected locale will cause indexes to be sorted in an order that prevents them from being used for LIKE and regular-expression searches. If you need good performance of such searches, you should set your current locale to C and re-run initdb. On most systems, setting the current locale is done by changing the value of the environment variable LC_ALL or LANG. The sort order used within a particular database cluster is set by initdb and cannot be changed later, short of dumping all data, rerunning initdb, and reloading the data. So it's important to make this choice correctly now.