September 26, 2024: PostgreSQL 17 Released!
Unsupported versions: 7.0 / 6.5 / 6.4
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.

initlocation

Name

initlocation — Create a secondary Postgres database storage area
initlocation [ --location=er">alble> | -D altdir ]
    [ --username=name | -u name ]
    [ altdir ]
  

Inputs

--location=altdir, -D altdir, altdir

Where in your Unix filesystem do you want alternate databases to go? The top level directory is called the PGDATA directory, so you might want to point your first alternate location at PGDATA2.

--username=name, -u name, PGUSER

Who will be the Unix filesystem owner of this database storage area? The Postgres superuser is a Unix user who owns all files that store the database system and also owns the postmaster and backend processes that access them. Usually, this is the user who should run initlocation and who will thus have ownership of the directories and files.

Note: Only the Unix superuser can create a database system with a different user as the Postgres superuser. Specifying a user other than the Postgres superuser may lead to database security and data integrity problems. Refer to the PostgreSQL Administrator's Guide for more information.

Outputs

initlocation will create directories in the specified place.

We are initializing the database area with username postgres (uid=500). This user will own all the files and must also own the server process. Creating Postgres database system directory altdir Creating Postgres database system directory altdir

Successful completion.

We are initializing the database area with username postgres (uid=500). This user will own all the files and must also own the server process. Creating Postgres database system directory /usr/local/src/testlocation mkdir: cannot make directory `altdir': Permission denied

You do not have filesystem permission to write to the specified directory area.

Valid username not given. You must specify the username for the Postgres superuser for the database system you are initializing, either with the --username option or by default to the USER environment variable.

The username which you have specified is not the Postgres superuser.

Can't tell what username to use. You don't have the USER environment variable set to your username and didn't specify the --username option

Specify the --username command line option.

Description

initlocation creates a new Postgres secondary database storage area. A secondary storage area contains a required tree of directories with the correct file permissions on those directories.

Creating a database storage area consists of creating the directories in which database data might live.

There are two kinds of arguments for initlocation. First, you can specify an environment variable (e.g. PGDATA2). This environment variable should be known to the backend for later use in CREATE DATABASE/WITH LOCATION or createdb -D altdir. However, the backend daemon must have this variable in it's environment for this to succeed. Second, you may be able to specify an explicit absolute path to the top directory of the storage area. However,this second option is possible only if explicitly enabled during the Postgres installation. It is usually disabled to alleviate security and data integrity concerns.

Note: Postgres will add /base/ to the specified path to create the storage area.

The backend requires that any argument to WITH LOCATION which is in all uppercase and which has no path delimiters is an environment variable.

Usage

To create a database in an alternate location, using an environment variable:

% setenv PGDATA2 /opt/postgres/data
% initlocation PGDATA2
% createdb -D PGDATA2