PG_CREATECLUSTER(1) Debian PostgreSQL infrastructure PG_CREATECLUSTER(1)
NAME
pg_createcluster - create a new PostgreSQL cluster
SYNOPSIS
pg_createcluster [options] version name [-- initdb options]
DESCRIPTION
pg_createcluster creates a new PostgreSQL server cluster (i. e. a
collection of databases served by a postgres(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.
For compatibility with systemd service units, the cluster name should
not contain any dashes (-). pg_ctlcluster will warn about the problem,
but succeed with the operation.
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), and the postgres user is in the
ssl-cert Unix group, pg_createcluster configures the cluster to use this
certificate, and enables SSL. Therefore all clusters will use the same
SSL certificate by default. For versions up to 9.1, symlinks in the data
directory will be created (server.crt and server.key); for 9.2 and
later, the appropriate postgresql.conf options will be set
(ssl_cert_file and ssl_key_file). Of course you can replace this with a
cluster specific certificate. Similarly for
/etc/postgresql-common/root.crt and /etc/postgresql-common/root.crl,
these files will be configured as client certificate CA and revocation
list, when present. (root.crt is initially a placeholder that will only
be used if real certificates are added to the file.)
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 postgres(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 postgres(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.
-q --quiet --no-status
Suppress output from initdb and (or only) the cluster status message
at the end of the output.
--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.
-o guc=value, --pgoption guc=value
Configuration option to set in the new postgresql.conf file.
--createclusterconf=file
Alternative createcluster.conf file to use. Default is
/etc/postgresql-common/createcluster.conf (or
$PGSYSCONFDIR/createcluster.conf).
--environment=file
Alternative default environment file to use. Default is
/etc/postgresql-common/environment (or $PGSYSCONFDIR/environment).
If the file is missing, a placeholder string is used. %v and %c are
replaced; see DEFAULT VALUES below.
-- initdb options
Options passed directly to initdb(1).
Per default, pg_createcluster will update the pg_hba.conf file
generated by initdb to use peer authentication on local (unix)
connections, and md5 on TCP (host) connections. If explicit
authentication config is included here (-A, --auth, --auth-host,
--auth-local), the pg_hba.conf file will be left untouched.
Note: If only one of --auth-host and --auth-local is provided, the
other setting will default to trust as per initdb's defaults,
opening a potential security risk.
STARTUP CONTROL
The start.conf file in the cluster configuration directory controls the
start/stop behavior of that cluster's postgres 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 postgres process is started/stopped automatically in the init
script.
When running from systemd, the cluster is started/stopped when
postgresql.service is started/stopped. This is also the default if
the file is missing.
manual
The postgres process is not handled by the init script, but manually
controlling the cluster with pg_ctlcluster(1) is permitted.
When running from systemd, the cluster is not started automatically
when postgresql.service is started. However, stopping/restarting
postgresql.service will stop/restart the cluster. The cluster can be
started using systemctl start postgresql@version-cluster.
disabled
Neither the init script, pg_ctlcluster(1), nor postgresql@.service
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 postgres process; this option is only meant to prevent
accidents during maintenance, not more.
When running from systemd, invoke systemctl daemon-reload after editing
start.conf.
The pg_ctl.conf file in the cluster configuration directory can contain
additional options passed to pg_ctl of that cluster.
DEFAULT VALUES
Some default values used by pg_createcluster can be modified in
/etc/postgresql-common/createcluster.conf. Occurrences of %v are
replaced by the major version number, and %c by the cluster name. Use %%
for a literal %.
create_main_cluster (Default: true)
Create a main cluster when a new postgresql-NN server package is
installed and no clusters exist yet.
start_conf (Default: auto)
Default start.conf value to use.
data_directory (Default: /var/lib/postgresql/%v/%c)
Default data directory.
waldir|xlogdir (Default: unset)
Default directory for transaction logs. When used, initdb will
create a symlink from pg_wal (PostgreSQL 9.6 and earlier: pg_xlog)
in the data directory to this location. Unset by default, i.e.
transaction logs remain in the data directory. Both spellings of
this option are accepted, and translated to the correct initdb
invocation depending on the cluster version.
initdb_options (Default: unset)
Other options to pass to initdb.
Other options
All other options listed are copied into the new cluster's
postgresql.conf, e.g.:
listen_addresses = '*'
log_line_prefix = '%%t '
Some postgresql.conf options are treated specially:
ssl Only added to postgresql.conf if the default snakeoil
certificates exist and are readable for the cluster owner as
detailed above.
stats_temp_directory
Only added to postgresql.conf if existing, and writable for the
cluster owner, or else if the parent directory is writable. Not
used on PostgreSQL 15 or later.
Include files
include
include_if_exists
include_dir
createcluster.conf supports the same include directives as
postgresql.conf.
add_include
add_include_if_exists
add_include_dir
To add include directives to the new postgresql.conf file, use
the add_* directives. The add_ prefix is removed.
SEE ALSO
initdb(1), pg_ctlcluster(8), pg_lsclusters(1), pg_wrapper(1)
AUTHORS
Martin Pitt <mpitt@debian.org>, Christoph Berg <myon@debian.org>
Debian 2025-05-07 PG_CREATECLUSTER(1)
Generated by dwww version 1.16 on Tue Dec 16 06:04:41 CET 2025.