NAME
pg_createcluster - create a new PostgreSQL cluster
SYNOPSIS
pg_createcluster [options] version name
DESCRIPTION
pg_createcluster creates a new PostgreSQL server cluster (i. e. a
collection of databases served by a postmaster(1) instance) and
integrates it into the multi-version/multi-cluster architecture of the
postgresql-common package.
Every cluster is uniquely identified by its version and name. The name
can be arbitrary. The default cluster that is created on installation
of a server package is main. However, you might wish to create other
clusters for testing, with other superusers, a cluster for each user on
a shared server, etc. pg_createcluster will abort with an error if you
try to create a cluster with a name that already exists for that
version.
Given a major PostgreSQL version (like "8.2" or "8.3") and a cluster
name, it creates the necessary configuration files in
/etc/postgresql/version/name/; in particular these are postgresql.conf,
pg_ident.conf, pg_hba.conf, a postgresql-common specific configuration
file start.conf (see STARTUP CONTROL below), pg_ctl.conf, and a
symbolic link log which points to the log file (by default,
/var/log/postgresql/postgresql-version-name.log).
postgresql.conf is automatically adapted to use the next available
port, i. e. the first port (starting from 5432) which is not yet used
by an already existing cluster.
If the data directory does not yet exist, PostgreSQL's initdb(1)
command is used to generate a new cluster structure. If the data
directory already exists, it is integrated into the postgresql-common
structure by moving the configuration file and setting the
data_directory option. Please note that this only works for data
directories which were created directly with initdb, i. e. all the
configuration files (postgresql.conf etc.) must be present in the data
directory.
If a custom socket directory is given and it does not exist, it is
created.
If the log file does not exist, it is created. In any case the
permissions are adjusted to allow write access to the cluster owner.
Please note that postgresql.conf can be customized to specify
log_directory and/or log_filename; if at least one of these options is
present, then the symbolic link log in the cluster configuration
directory is ignored.
If the default snakeoil SSL certificate exists
(/etc/ssl/certs/ssl-cert-snakeoil.pem and
/etc/ssl/private/ssl-cert-snakeoil.key), this program creates symlinks
to these files in the data directory (server.crt and server.key) and
enables SSL for that cluster (option ssl in postgresql.conf). Therefore
all clusters will use the same SSL certificate by default. Of course
you can replace these symlinks with a cluster specific certificate.
OPTIONS
-u user, --user=user
Set the user who owns the cluster and becomes the database
superuser to the given name or uid. By default, this is the user
postgres. A cluster must not be owned by root.
-g group, --group=group
Change the group of the cluster related data files. By default this
will be the primary group of the database owner.
-d dir, --datadir=dir
Explicitly set the data directory path, which is used to store all
the actual databases and tables. This will become quite big (easily
in the order of five times the amount of actual data stored in the
cluster). Defaults to /var/lib/postgresql/version/cluster.
-s dir, --socketdir=dir
Explicitly set the directory where the postmaster(1) server stores
the Unix socket for local connections. Defaults to
/var/run/postgresql/ for clusters owned by the user postgres, and
/tmp for clusters owned by other users. Please be aware that /tmp
is an unsafe directory since everybody can create a socket there
and impersonate the database server. If the given directory does
not exist, it is created with appropriate permissions.
-l path, --logfile=path
Explicitly set the path for the postmaster(1) server log file.
Defaults to /var/log/postgresql/postgresql-version-cluster.log.
--locale=locale
Set the default locale for the database cluster. If this option is
not specified, the locale is inherited from the environment that
pg_createcluster runs in.
--lc-collate=locale
--lc-ctype=locale
--lc-messages=locale
--lc-monetary=locale
--lc-numeric=locale
--lc-time=locale
Like --locale, but only sets the locale in the specified category.
-e encoding, --encoding=encoding
Select the encoding of the template database. This will also be the
default encoding of any database you create later, unless you
override it there. The default is derived from the locale, or
SQL_ASCII if that does not work. The character sets supported by
the PostgreSQL server are described in the documentation.
Note: It is not recommended to set this option directly! Set the
locale instead.
-p port, --port=port
Select the port the new cluster listens on (for the Unix socket and
the TCP port); this must be a number between 1024 and 65535, since
PostgreSQL does not run as root and thus needs an unprivileged port
number. By default the next free port starting from 5432 is
assigned.
--start
Immediately start a server for the cluster after creating it (i. e.
call pg_ctlcluster version cluster start on it). By default, the
cluster is not started.
--start-conf=auto|manual|disabled
Set the initial value in the start.conf configuration file. See
STARTUP CONTROL below. By default, auto is used, which means that
the cluster is handled by /etc/init.d/postgresql-version, i. e.
starts and stops automatically on system boot.
STARTUP CONTROL
The start.conf file in the cluster configuration directory controls the
start/stop behavior of that cluster's postmaster process. The file can
contain comment lines (started with '#'), empty lines, and must have
exactly one line with one of the following keywords:
auto
The postmaster process is started/stopped automatically in the init
script. This is also the default if the file is missing.
manual
The postmaster process is not handled by the init script, but
manually controlling the cluster with pg_ctlcluster(1) is
permitted.
disable
Neither the init script nor pg_ctlcluster(1) are permitted to
start/stop the cluster. Please be aware that this will not stop the
cluster owner from calling lower level tools to control the
postmaster process; this option is only meant to prevent accidents
during maintenance, not more.
The pg_ctl.conf file in the cluster configuration directory can
contain additional options passed to pg_ctl of that cluster.
SEE ALSO
pg_ctlcluster(8), pg_lsclusters(1), pg_wrapper(1)
AUTHOR
Martin Pitt <mpitt@debian.org>