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, 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.
- disabled
- 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>