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>