PG_CREATECLUSTER(1)

📦
version 293ubuntu1 · 8 versions
, in ubuntu stonking

💖 PG_CREATECLUSTER 💖

okay so bestie, this is the Debian PostgreSQL infrastructure manual page for pg_createcluster, and honestly? it's a whole vibe. if you've ever been like "i want a second Postgres cluster, one that's all mine, with its own port and its own everything" — yeah, this is the girl for you. buckle up, we're doing this together 🫶

✨ NAME ✨

pg_createcluster — create a new PostgreSQL cluster 💅

🌸 SYNOPSIS 🌸

pg_createcluster [options] version name [-- initdb options]

🦋 DESCRIPTION 🦋

So pg_createcluster creates a brand-new PostgreSQL server cluster — and when we say cluster, we mean a whole collection of databases that get served up by one postgres(1) instance. then it slides it right into the multi-version / multi-cluster architecture of the postgresql-common package, no cap. it just fits.

Every single cluster is uniquely identified by its version and its name. the name? can be literally anything you want, icon. The default cluster that gets created when you install a server package is called main. but maybe you want extra clusters for testing, or clusters with different superusers, or one cluster per user on a shared server, etc. — all valid, all slay. and heads up: pg_createcluster will abort with an error if you try to create a cluster with a name that already exists for that version. no duplicates, periodt.

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. 🙈 so like, it'll side-eye you but let it happen.

Given a major PostgreSQL version (like "8.2" or "8.3") and a cluster name, it creates all the necessary configuration files in /etc/postgresql/version/name/. and bestie, here's the full list, we're not skipping anybody:

  • postgresql.conf
  • pg_ident.conf
  • pg_hba.conf
  • a postgresql-common specific configuration file start.conf (peep STARTUP CONTROL below for the tea)
  • 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. it's finding the empty seat in the cafeteria for you 💅

If the data directory doesn't exist yet, PostgreSQL's initdb(1) command is used to generate a brand-new cluster structure. but if the data directory already exists? it gets integrated into the postgresql-common structure by moving the configuration file and setting the data_directory option. please note: 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. no config files, no entry, sorry bestie 😭

If a custom socket directory is given and it doesn't exist, it is created. done. 🎀

If the log file doesn't exist, it is created. and either way, 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. so it's just sitting there, pretty, unused, not the main character anymore 💀

If the default snakeoil SSL certificate exists — that's /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, then 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 — do your own thing, queen 👑. 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.) so it's like, waiting patiently for its moment. iconic behaviour honestly.

💅 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 where all the actual databases and tables live. heads up: 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. yikes, bestie. if the given directory doesn't 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 isn't specified, the locale is inherited from the environment that pg_createcluster runs in. it's giving "just absorb the room's energy".
  • --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. one category at a time, we're being specific 💅

  • -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 doesn't 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. fr fr, listen to the manpage on this one 🫶
  • -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. no stepping on anyone's toes here ✨
  • -q, --quiet, --no-status — suppress output from initdb and (or only) the cluster status message at the end of the output. for when you want it chill and silent 🤫
  • --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. it's created but napping 😴
  • --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 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). pass them right on through, no filter 💅

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. it knows when to not meddle.

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. not the vibe. be careful out there bestie 😭

👑 STARTUP CONTROL 👑

The start.conf file in the cluster configuration directory controls the start/stop behavior of that cluster's postgres process. it 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. so it's a soft little fence, not a fortress 🫣

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 ✨

okay bestie listen 💖 some of the defaults that pg_createcluster uses are tweakable, and the place to do it is:

/etc/postgresql-common/createcluster.conf

and inside that file, a couple of placeholders get swapped in for you: every %v becomes the major version number, every %c becomes the cluster name, and if you want an actual, literal percent sign, you write %%. periodt. 💅

🎀 create_main_cluster (Default: true)

should we make a main cluster when a brand new postgresql-NN server package shows up and, like, zero clusters exist yet? Yes queen. That's the default. 👑

🎀 start_conf (Default: auto)

the default value that gets used for start.conf. slay.

🎀 data_directory (Default: /var/lib/postgresql/%v/%c)

the default home for your data. iconic. 🌸

🎀 waldir|xlogdir (Default: unset)

this is the default directory for your transaction logs. and the way it works is: when you actually set it, initdb will create a symlink from pg_wal (and for PostgreSQL 9.6 and earlier: pg_xlog) inside the data directory, pointing at this location. it's unset by default, meaning the transaction logs just vibe in the data directory like normal. Also! Both spellings of this option are accepted, and they get translated into the correct initdb invocation depending on the cluster version. so use whichever one your heart says. 🦋

🎀 initdb_options (Default: unset)

any other options you wanna yeet over to initdb. extra credit for you. ✨

🍓 Other options

every other option in here gets copied straight into your new cluster's postgresql.conf, like:

listen_addresses = '*'
log_line_prefix = '%%t '

but wait — a couple of postgresql.conf options get the special treatment:

  • ssl — it only gets added to postgresql.conf if the default snakeoil certificates exist and are readable by the cluster owner, exactly as described above. no certs, no ssl = on, sorry bestie. 😭
  • stats_temp_directory — it only gets added to postgresql.conf if it already exists and is writable by the cluster owner, or if its parent directory is writable. heads up though: this one isn't used at all on PostgreSQL 15 or later. 👀

🌈 Include files

  • include
  • include_if_exists
  • include_dir

createcluster.conf supports the exact same include directives as postgresql.conf. she's flexible like that. 💜

  • add_include
  • add_include_if_exists
  • add_include_dir

now if you wanna push include directives into the new postgresql.conf file, you use these add_* ones. and here's the lil trick: the add_ prefix gets removed. poof. 🧚

👀 SEE ALSO 👀

like, go read these too, i'm begging:

💖 AUTHORS 💖

the actual geniuses behind this masterpiece:

  • Martin Pitt <mpitt@debian.org>
  • Christoph Berg <myon@debian.org>

fr fr, thank them. 🫶

okay and one last thing before you go, my love — this whole page is Debian's, from way back on 2026-07-28, and it's page PG_CREATECLUSTER(1) of the manual. go forth and cluster responsibly. no cap. 💅✨👑

📦 where this page comes from