.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` 
.    ds C' 
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PG_CREATECLUSTER 1"
.TH PG_CREATECLUSTER 1 "2023-05-24" "Debian" "Debian PostgreSQL infrastructure"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pg_createcluster \- create a new PostgreSQL cluster
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBpg_createcluster\fR [\fIoptions\fR] \fIversion\fR \fIname\fR [\fB\-\-\fR \fIinitdb options\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBpg_createcluster\fR creates a new PostgreSQL server cluster (i. e. a
collection of databases served by a \fBpostgres\fR\|(1) instance) and
integrates it into the multi\-version/multi\-cluster architecture of the
\&\fBpostgresql-common\fR package.
.PP
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 \f(CW\*(C`main\*(C'\fR. However, you might wish to create other clusters for
testing, with other superusers, a cluster for each user on a shared server,
etc. \f(CW\*(C`pg_createcluster\*(C'\fR will abort with an error if you try to create a
cluster with a name that already exists for that version.
.PP
For compatibility with \fBsystemd\fR service units, the cluster name should not
contain any dashes (\fB\-\fR). \fBpg_ctlcluster\fR will warn about the problem, but
succeed with the operation.
.PP
Given a major PostgreSQL \fIversion\fR (like \*(L"8.2\*(R" or \*(L"8.3\*(R") and a cluster
\&\fIname\fR, it creates the necessary configuration files in
\&\f(CW\*(C`/etc/postgresql/\*(C'\fR\fIversion\fR\f(CW\*(C`/\*(C'\fR\fIname\fR\f(CW\*(C`/\*(C'\fR; in particular these are
\&\f(CW\*(C`postgresql.conf\*(C'\fR, \f(CW\*(C`pg_ident.conf\*(C'\fR, \f(CW\*(C`pg_hba.conf\*(C'\fR, a postgresql-common
specific configuration file \f(CW\*(C`start.conf\*(C'\fR (see \fB\s-1STARTUP CONTROL\s0\fR below),
\&\f(CW\*(C`pg_ctl.conf\*(C'\fR, and a symbolic link \f(CW\*(C`log\*(C'\fR which points to the log file (by
default, \f(CW\*(C`/var/log/postgresql/postgresql\-\*(C'\fR\fIversion\fR\f(CW\*(C`\-\*(C'\fR\fIname\fR\f(CW\*(C`.log\*(C'\fR).
.PP
\&\f(CW\*(C`postgresql.conf\*(C'\fR 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.
.PP
If the data directory does not yet exist, PostgreSQL's \fBinitdb\fR\|(1) command is
used to generate a new cluster structure. If the data directory already exists,
it is integrated into the \fBpostgresql-common\fR structure by moving the
configuration file and setting the data_directory option. Please note that this
\&\fIonly\fR works for data directories which were created directly with \fBinitdb\fR, i.
e. all the configuration files (\f(CW\*(C`postgresql.conf\*(C'\fR etc.) must be present in the
data directory.
.PP
If a custom socket directory is given and it does not exist, it is created.
.PP
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
\&\f(CW\*(C`postgresql.conf\*(C'\fR can be customized to specify \f(CW\*(C`log_directory\*(C'\fR and/or
\&\f(CW\*(C`log_filename\*(C'\fR; if at least one of these options is present, then the symbolic
link \f(CW\*(C`log\*(C'\fR in the cluster configuration directory is ignored.
.PP
If the default snakeoil \s-1SSL\s0 certificate exists
(\f(CW\*(C`/etc/ssl/certs/ssl\-cert\-snakeoil.pem\*(C'\fR and
\&\f(CW\*(C`/etc/ssl/private/ssl\-cert\-snakeoil.key\*(C'\fR), and the \f(CW\*(C`postgres\*(C'\fR user is in the
\&\f(CW\*(C`ssl\-cert\*(C'\fR Unix group, \fBpg_createcluster\fR configures the cluster to use this
certificate, and enables \s-1SSL.\s0 Therefore all clusters will use the same \s-1SSL\s0
certificate by default. For versions up to 9.1, symlinks in the data directory
will be created (\f(CW\*(C`server.crt\*(C'\fR and \f(CW\*(C`server.key\*(C'\fR); for 9.2 and later, the
appropriate \f(CW\*(C`postgresql.conf\*(C'\fR options will be set (\f(CW\*(C`ssl_cert_file\*(C'\fR and
\&\f(CW\*(C`ssl_key_file\*(C'\fR). Of course you can replace this with a cluster specific
certificate. Similarly for \f(CW\*(C`/etc/postgresql\-common/root.crt\*(C'\fR and
\&\f(CW\*(C`/etc/postgresql\-common/root.crl\*(C'\fR, these files will be configured as client
certificate \s-1CA\s0 and revocation list, when present. (\f(CW\*(C`root.crt\*(C'\fR is initially a
placeholder that will only be used if real certificates are added to the file.)
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-u\fR \fIuser\fR, \fB\-\-user=\fR\fIuser\fR" 4
.IX Item "-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 \fBpostgres\fR.  A cluster must
not be owned by root.
.IP "\fB\-g\fR \fIgroup\fR, \fB\-\-group=\fR\fIgroup\fR" 4
.IX Item "-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.
.IP "\fB\-d\fR \fIdir\fR, \fB\-\-datadir=\fR\fIdir\fR" 4
.IX Item "-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
\&\f(CW\*(C`/var/lib/postgresql/\*(C'\fR\fIversion\fR\f(CW\*(C`/\*(C'\fR\fIcluster\fR.
.IP "\fB\-s\fR \fIdir\fR, \fB\-\-socketdir=\fR\fIdir\fR" 4
.IX Item "-s dir, --socketdir=dir"
Explicitly set the directory where the \fBpostgres\fR\|(1) server stores the Unix
socket for local connections. Defaults to \f(CW\*(C`/var/run/postgresql/\*(C'\fR for clusters
owned by the user \fBpostgres\fR, and \f(CW\*(C`/tmp\*(C'\fR for clusters owned by other users.
Please be aware that \f(CW\*(C`/tmp\*(C'\fR 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.
.IP "\fB\-l\fR \fIpath\fR, \fB\-\-logfile=\fR\fIpath\fR" 4
.IX Item "-l path, --logfile=path"
Explicitly set the path for the \fBpostgres\fR\|(1) server log file. Defaults to
\&\f(CW\*(C`/var/log/postgresql/postgresql\-\*(C'\fR\fIversion\fR\f(CW\*(C`\-\*(C'\fR\fIcluster\fR\f(CW\*(C`.log\*(C'\fR.
.IP "\fB\-\-locale=\fR\fIlocale\fR" 4
.IX Item "--locale=locale"
Set the default locale for the database cluster. If this option is not
specified, the locale is inherited from the environment that
\&\fBpg_createcluster\fR runs in.
.IP "\fB\-\-lc\-collate=\fR\fIlocale\fR" 4
.IX Item "--lc-collate=locale"
.PD 0
.IP "\fB\-\-lc\-ctype=\fR\fIlocale\fR" 4
.IX Item "--lc-ctype=locale"
.IP "\fB\-\-lc\-messages=\fR\fIlocale\fR" 4
.IX Item "--lc-messages=locale"
.IP "\fB\-\-lc\-monetary=\fR\fIlocale\fR" 4
.IX Item "--lc-monetary=locale"
.IP "\fB\-\-lc\-numeric=\fR\fIlocale\fR" 4
.IX Item "--lc-numeric=locale"
.IP "\fB\-\-lc\-time=\fR\fIlocale\fR" 4
.IX Item "--lc-time=locale"
.PD
Like \fB\-\-locale\fR, but only sets the locale in the specified category.
.IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding=\fR\fIencoding\fR" 4
.IX Item "-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 \s-1SQL_ASCII\s0 if that does not work.  The
character sets supported by the PostgreSQL server are described in the
documentation.
.Sp
\&\fBNote\fR: It is not recommended to set this option directly! Set the locale
instead.
.IP "\fB\-p\fR \fIport\fR, \fB\-\-port=\fR\fIport\fR" 4
.IX Item "-p port, --port=port"
Select the port the new cluster listens on (for the Unix socket and the \s-1TCP\s0
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.
.IP "\fB\-q\fR \fB\-\-quiet\fR \fB\-\-no\-status\fR" 4
.IX Item "-q --quiet --no-status"
Suppress output from \fBinitdb\fR and (or only) the cluster status message at the
end of the output.
.IP "\fB\-\-start\fR" 4
.IX Item "--start"
Immediately start a server for the cluster after creating it (i. e. call
\&\f(CW\*(C`pg_ctlcluster\*(C'\fR \fIversion cluster\fR \f(CW\*(C`start\*(C'\fR on it). By default, the cluster is
not started.
.IP "\fB\-\-start\-conf=\fR\fBauto\fR|\fBmanual\fR|\fBdisabled\fR" 4
.IX Item "--start-conf=auto|manual|disabled"
Set the initial value in the \f(CW\*(C`start.conf\*(C'\fR configuration file. See \fB\s-1STARTUP
CONTROL\s0\fR below. By default, \fBauto\fR is used, which means that the cluster is
handled by \f(CW\*(C`/etc/init.d/postgresql\*(C'\fR, i. e. starts and stops
automatically on system boot.
.IP "\fB\-o\fR \fIguc\fR\fB=\fR\fIvalue\fR, \fB\-\-pgoption\fR \fIguc\fR\fB=\fR\fIvalue\fR" 4
.IX Item "-o guc=value, --pgoption guc=value"
Configuration option to set in the new \f(CW\*(C`postgresql.conf\*(C'\fR file.
.IP "\fB\-\-createclusterconf=\fR\fIfile\fR" 4
.IX Item "--createclusterconf=file"
Alternative \fBcreatecluster.conf\fR file to use. Default is
\&\f(CW\*(C`/etc/postgresql\-common/createcluster.conf\*(C'\fR (or
\&\f(CW\*(C`$PGSYSCONFDIR/createcluster.conf\*(C'\fR).
.IP "\fB\-\-environment=\fR\fIfile\fR" 4
.IX Item "--environment=file"
Alternative default \fBenvironment\fR file to use. Default is
\&\f(CW\*(C`/etc/postgresql\-common/environment\*(C'\fR (or \f(CW\*(C`$PGSYSCONFDIR/environment\*(C'\fR).
If the file is missing, a placeholder string is used.
\&\f(CW%v\fR and \f(CW%c\fR are replaced; see \s-1DEFAULT VALUES\s0 below.
.IP "\fB\-\-\fR \fIinitdb options\fR" 4
.IX Item "-- initdb options"
Options passed directly to \fBinitdb\fR\|(1).
.Sp
Per default, \fBpg_createcluster\fR will update the \f(CW\*(C`pg_hba.conf\*(C'\fR file generated
by initdb to use peer authentication on local (unix) connections, and md5 on
\&\s-1TCP\s0 (host) connections. If explicit authentication config is included here
(\fB\-A\fR, \fB\-\-auth\fR, \fB\-\-auth\-host\fR, \fB\-\-auth\-local\fR), the \f(CW\*(C`pg_hba.conf\*(C'\fR file
will be left untouched.
.Sp
\&\fINote:\fR If only one of \fB\-\-auth\-host\fR and \fB\-\-auth\-local\fR is provided, the
other setting will default to \fBtrust\fR as per \fBinitdb\fR's defaults, opening a
potential security risk.
.SH "STARTUP CONTROL"
.IX Header "STARTUP CONTROL"
The \f(CW\*(C`start.conf\*(C'\fR 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:
.IP "\fBauto\fR" 4
.IX Item "auto"
The postgres process is started/stopped automatically in the init script.
.Sp
When running from \fBsystemd\fR, the cluster is started/stopped when
\&\fBpostgresql.service\fR is started/stopped.
This is also the default if the file is missing.
.IP "\fBmanual\fR" 4
.IX Item "manual"
The postgres process is not handled by the init script, but manually
controlling the cluster with \fBpg_ctlcluster\fR\|(1) is permitted.
.Sp
When running from \fBsystemd\fR, the cluster is not started automatically when
\&\fBpostgresql.service\fR is started. However, stopping/restarting
\&\fBpostgresql.service\fR will stop/restart the cluster. The cluster can be started
using \fBsystemctl start postgresql@\fR\fIversion\fR\fB\-\fR\fIcluster\fR.
.IP "\fBdisabled\fR" 4
.IX Item "disabled"
Neither the init script, \fBpg_ctlcluster\fR\|(1), nor \fBpostgresql@.service\fR 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.
.PP
When running from \fBsystemd\fR, invoke \fBsystemctl daemon-reload\fR after editing
\&\f(CW\*(C`start.conf\*(C'\fR.
.PP
The \f(CW\*(C`pg_ctl.conf\*(C'\fR file in the cluster configuration directory can contain
additional options passed to \fBpg_ctl\fR of that cluster.
.SH "DEFAULT VALUES"
.IX Header "DEFAULT VALUES"
Some default values used by \fBpg_createcluster\fR can be modified in
\&\f(CW\*(C`/etc/postgresql\-common/createcluster.conf\*(C'\fR. Occurrences of \fB\f(CB%v\fB\fR are replaced
by the major version number, and \fB\f(CB%c\fB\fR by the cluster name. Use \fB%%\fR for a
literal \fB%\fR.
.IP "\fBcreate_main_cluster\fR (Default: \fBtrue\fR)" 4
.IX Item "create_main_cluster (Default: true)"
Create a \fBmain\fR cluster when a new postgresql-NN server package is installed.
.IP "\fBstart_conf\fR (Default: \fBauto\fR)" 4
.IX Item "start_conf (Default: auto)"
Default \f(CW\*(C`start.conf\*(C'\fR value to use.
.IP "\fBdata_directory\fR (Default: \fB/var/lib/postgresql/%v/%c\fR)" 4
.IX Item "data_directory (Default: /var/lib/postgresql/%v/%c)"
Default data directory.
.IP "\fBwaldir|xlogdir\fR (Default: unset)" 4
.IX Item "waldir|xlogdir (Default: unset)"
Default directory for transaction logs. When used, \fBinitdb\fR will create a
symlink from \f(CW\*(C`pg_wal\*(C'\fR (PostgreSQL 9.6 and earlier: \f(CW\*(C`pg_xlog\*(C'\fR) 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.
.IP "\fBinitdb_options\fR (Default: unset)" 4
.IX Item "initdb_options (Default: unset)"
Other options to pass to \fBinitdb\fR.
.IP "Other options" 4
.IX Item "Other options"
All other options listed are copied into the new cluster's postgresql.conf, e.g.:
.Sp
.Vb 2
\&    listen_addresses = \*(Aq*\*(Aq
\&    log_line_prefix = \*(Aq%%t \*(Aq
.Ve
.Sp
Some postgresql.conf options are treated specially:
.RS 4
.IP "\fBssl\fR" 4
.IX Item "ssl"
Only added to postgresql.conf if the default snakeoil certificates exist and
are readable for the cluster owner as detailed above.
.IP "\fBstats_temp_directory\fR" 4
.IX Item "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.
.RE
.RS 4
.RE
.IP "Include files" 4
.IX Item "Include files"
.RS 4
.PD 0
.IP "\fBinclude\fR" 4
.IX Item "include"
.IP "\fBinclude_if_exists\fR" 4
.IX Item "include_if_exists"
.IP "\fBinclude_dir\fR" 4
.IX Item "include_dir"
.PD
\&\fBcreatecluster.conf\fR supports the same include directives as
\&\fBpostgresql.conf\fR.
.IP "\fBadd_include\fR" 4
.IX Item "add_include"
.PD 0
.IP "\fBadd_include_if_exists\fR" 4
.IX Item "add_include_if_exists"
.IP "\fBadd_include_dir\fR" 4
.IX Item "add_include_dir"
.PD
To add include directives to the new postgresql.conf file, use the \fBadd_*\fR
directives. The \fBadd_\fR prefix is removed.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBinitdb\fR\|(1), \fBpg_ctlcluster\fR\|(8), \fBpg_lsclusters\fR\|(1), \fBpg_wrapper\fR\|(1)
.SH "AUTHORS"
.IX Header "AUTHORS"
Martin Pitt <mpitt@debian.org>, Christoph Berg <myon@debian.org>