PG_CREATECLUSTER
Section: Debian PostgreSQL infrastructure (1)
Updated: 2023-03-14
Index
Return to Main Contents
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.
- 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>
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- STARTUP CONTROL
-
- DEFAULT VALUES
-
- SEE ALSO
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 23:51:59 GMT, April 19, 2024