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>

Debian                                             2024-08-09                                PG_CREATECLUSTER(1)