summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/app-initdb.html
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
commit5e45211a64149b3c659b90ff2de6fa982a5a93ed (patch)
tree739caf8c461053357daa9f162bef34516c7bf452 /doc/src/sgml/html/app-initdb.html
parentInitial commit. (diff)
downloadpostgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.tar.xz
postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.zip
Adding upstream version 15.5.upstream/15.5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/html/app-initdb.html')
-rw-r--r--doc/src/sgml/html/app-initdb.html251
1 files changed, 251 insertions, 0 deletions
diff --git a/doc/src/sgml/html/app-initdb.html b/doc/src/sgml/html/app-initdb.html
new file mode 100644
index 0000000..00f2877
--- /dev/null
+++ b/doc/src/sgml/html/app-initdb.html
@@ -0,0 +1,251 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>initdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="reference-server.html" title="PostgreSQL Server Applications" /><link rel="next" href="pgarchivecleanup.html" title="pg_archivecleanup" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">initdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="reference-server.html" title="PostgreSQL Server Applications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pgarchivecleanup.html" title="pg_archivecleanup">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-INITDB"><div class="titlepage"></div><a id="id-1.9.5.3.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">initdb</span></span></h2><p>initdb — create a new <span class="productname">PostgreSQL</span> database cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.3.4.1"><code class="command">initdb</code> [<em class="replaceable"><code>option</code></em>...] [ <code class="option">--pgdata</code> | <code class="option">-D</code> ]<em class="replaceable"><code> directory</code></em> </p></div></div><div class="refsect1" id="R1-APP-INITDB-1"><h2>Description</h2><p>
+ <code class="command">initdb</code> creates a new
+ <span class="productname">PostgreSQL</span> database cluster. A database
+ cluster is a collection of databases that are managed by a single
+ server instance.
+ </p><p>
+ Creating a database cluster consists of creating the directories in
+ which the database data will live, generating the shared catalog
+ tables (tables that belong to the whole cluster rather than to any
+ particular database), and creating the <code class="literal">postgres</code>,
+ <code class="literal">template1</code>, and <code class="literal">template0</code> databases.
+ The <code class="literal">postgres</code> database is a default database meant
+ for use by users, utilities and third party applications.
+ <code class="literal">template1</code> and <code class="literal">template0</code> are
+ meant as source databases to be copied by later <code class="command">CREATE
+ DATABASE</code> commands. <code class="literal">template0</code> should never
+ be modified, but you can add objects to <code class="literal">template1</code>,
+ which by default will be copied into databases created later. See
+ <a class="xref" href="manage-ag-templatedbs.html" title="23.3. Template Databases">Section 23.3</a> for more details.
+ </p><p>
+ Although <code class="command">initdb</code> will attempt to create the
+ specified data directory, it might not have permission if the parent
+ directory of the desired data directory is root-owned. To initialize
+ in such a setup, create an empty data directory as root, then use
+ <code class="command">chown</code> to assign ownership of that directory to the
+ database user account, then <code class="command">su</code> to become the
+ database user to run <code class="command">initdb</code>.
+ </p><p>
+ <code class="command">initdb</code> must be run as the user that will own the
+ server process, because the server needs to have access to the
+ files and directories that <code class="command">initdb</code> creates.
+ Since the server cannot be run as root, you must not run
+ <code class="command">initdb</code> as root either. (It will in fact refuse
+ to do so.)
+ </p><p>
+ For security reasons the new cluster created by <code class="command">initdb</code>
+ will only be accessible by the cluster owner by default. The
+ <code class="option">--allow-group-access</code> option allows any user in the same
+ group as the cluster owner to read files in the cluster. This is useful
+ for performing backups as a non-privileged user.
+ </p><p>
+ <code class="command">initdb</code> initializes the database cluster's default locale
+ and character set encoding. These can also be set separately for each
+ database when it is created. <code class="command">initdb</code> determines those
+ settings for the template databases, which will serve as the default for
+ all other databases. By default, <code class="command">initdb</code> uses the
+ locale provider <code class="literal">libc</code>, takes the locale settings from
+ the environment, and determines the encoding from the locale settings.
+ This is almost always sufficient, unless there are special requirements.
+ </p><p>
+ To choose a different locale for the cluster, use the option
+ <code class="option">--locale</code>. There are also individual options
+ <code class="option">--lc-*</code> (see below) to set values for the individual locale
+ categories. Note that inconsistent settings for different locale
+ categories can give nonsensical results, so this should be used with care.
+ </p><p>
+ Alternatively, the ICU library can be used to provide locale services.
+ (Again, this only sets the default for subsequently created databases.) To
+ select this option, specify <code class="literal">--locale-provider=icu</code>.
+ To choose the specific ICU locale ID to apply, use the option
+ <code class="option">--icu-locale</code>. Note that
+ for implementation reasons and to support legacy code,
+ <code class="command">initdb</code> will still select and initialize libc locale
+ settings when the ICU locale provider is used.
+ </p><p>
+ When <code class="command">initdb</code> runs, it will print out the locale settings
+ it has chosen. If you have complex requirements or specified multiple
+ options, it is advisable to check that the result matches what was
+ intended.
+ </p><p>
+ More details about locale settings can be found in <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a>.
+ </p><p>
+ To alter the default encoding, use the <code class="option">--encoding</code>.
+ More details can be found in <a class="xref" href="multibyte.html" title="24.3. Character Set Support">Section 24.3</a>.
+ </p></div><div class="refsect1" id="id-1.9.5.3.6"><h2>Options</h2><p>
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-A <em class="replaceable"><code>authmethod</code></em></code><br /></span><span class="term"><code class="option">--auth=<em class="replaceable"><code>authmethod</code></em></code></span></dt><dd><p>
+ This option specifies the default authentication method for local
+ users used in <code class="filename">pg_hba.conf</code> (<code class="literal">host</code>
+ and <code class="literal">local</code> lines). See <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a>
+ for an overview of valid values.
+ </p><p>
+ <code class="command">initdb</code> will
+ prepopulate <code class="filename">pg_hba.conf</code> entries using the
+ specified authentication method for non-replication as well as
+ replication connections.
+ </p><p>
+ Do not use <code class="literal">trust</code> unless you trust all local users on your
+ system. <code class="literal">trust</code> is the default for ease of installation.
+ </p></dd><dt><span class="term"><code class="option">--auth-host=<em class="replaceable"><code>authmethod</code></em></code></span></dt><dd><p>
+ This option specifies the authentication method for local users via
+ TCP/IP connections used in <code class="filename">pg_hba.conf</code>
+ (<code class="literal">host</code> lines).
+ </p></dd><dt><span class="term"><code class="option">--auth-local=<em class="replaceable"><code>authmethod</code></em></code></span></dt><dd><p>
+ This option specifies the authentication method for local users via
+ Unix-domain socket connections used in <code class="filename">pg_hba.conf</code>
+ (<code class="literal">local</code> lines).
+ </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--pgdata=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ This option specifies the directory where the database cluster
+ should be stored. This is the only information required by
+ <code class="command">initdb</code>, but you can avoid writing it by
+ setting the <code class="envar">PGDATA</code> environment variable, which
+ can be convenient since the database server
+ (<code class="command">postgres</code>) can find the database
+ directory later by the same variable.
+ </p></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>encoding</code></em></code><br /></span><span class="term"><code class="option">--encoding=<em class="replaceable"><code>encoding</code></em></code></span></dt><dd><p>
+ Selects the encoding of the template databases. This will also
+ be the default encoding of any database you create later,
+ unless you override it then. The default is derived from the locale,
+ if the libc locale provider is used, or <code class="literal">UTF8</code> if the
+ ICU locale provider is used. The character sets supported by
+ the <span class="productname">PostgreSQL</span> server are described
+ in <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="24.3.1. Supported Character Sets">Section 24.3.1</a>.
+ </p></dd><dt id="APP-INITDB-ALLOW-GROUP-ACCESS"><span class="term"><code class="option">-g</code><br /></span><span class="term"><code class="option">--allow-group-access</code></span></dt><dd><p>
+ Allows users in the same group as the cluster owner to read all cluster
+ files created by <code class="command">initdb</code>. This option is ignored
+ on <span class="productname">Windows</span> as it does not support
+ <acronym class="acronym">POSIX</acronym>-style group permissions.
+ </p></dd><dt><span class="term"><code class="option">--icu-locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Specifies the ICU locale ID, if the ICU locale provider is used.
+ </p></dd><dt id="APP-INITDB-DATA-CHECKSUMS"><span class="term"><code class="option">-k</code><br /></span><span class="term"><code class="option">--data-checksums</code></span></dt><dd><p>
+ Use checksums on data pages to help detect corruption by the
+ I/O system that would otherwise be silent. Enabling checksums
+ may incur a noticeable performance penalty. If set, checksums
+ are calculated for all objects, in all databases. All checksum
+ failures will be reported in the
+ <a class="link" href="monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW" title="28.2.15. pg_stat_database">
+ <code class="structname">pg_stat_database</code></a> view.
+ See <a class="xref" href="checksums.html" title="30.2. Data Checksums">Section 30.2</a> for details.
+ </p></dd><dt><span class="term"><code class="option">--locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Sets the default locale for the database cluster. If this
+ option is not specified, the locale is inherited from the
+ environment that <code class="command">initdb</code> runs in. Locale
+ support is described in <a class="xref" href="locale.html" title="24.1. Locale Support">Section 24.1</a>.
+ </p></dd><dt><span class="term"><code class="option">--lc-collate=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-ctype=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-messages=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-monetary=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-numeric=<em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--lc-time=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
+ Like <code class="option">--locale</code>, but only sets the locale in
+ the specified category.
+ </p></dd><dt><span class="term"><code class="option">--no-locale</code></span></dt><dd><p>
+ Equivalent to <code class="option">--locale=C</code>.
+ </p></dd><dt><span class="term"><code class="option">--locale-provider={<code class="literal">libc</code>|<code class="literal">icu</code>}</code></span></dt><dd><p>
+ This option sets the locale provider for databases created in the
+ new cluster. It can be overridden in the <code class="command">CREATE
+ DATABASE</code> command when new databases are subsequently
+ created. The default is <code class="literal">libc</code>.
+ </p></dd><dt><span class="term"><code class="option">-N</code><br /></span><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ By default, <code class="command">initdb</code> will wait for all files to be
+ written safely to disk. This option causes <code class="command">initdb</code>
+ to return without waiting, which is faster, but means that a
+ subsequent operating system crash can leave the data directory
+ corrupt. Generally, this option is useful for testing, but should not
+ be used when creating a production installation.
+ </p></dd><dt><span class="term"><code class="option">--no-instructions</code></span></dt><dd><p>
+ By default, <code class="command">initdb</code> will write instructions for how
+ to start the cluster at the end of its output. This option causes
+ those instructions to be left out. This is primarily intended for use
+ by tools that wrap <code class="command">initdb</code> in platform-specific
+ behavior, where those instructions are likely to be incorrect.
+ </p></dd><dt><span class="term"><code class="option">--pwfile=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
+ Makes <code class="command">initdb</code> read the database superuser's password
+ from a file. The first line of the file is taken as the password.
+ </p></dd><dt><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--sync-only</code></span></dt><dd><p>
+ Safely write all database files to disk and exit. This does not
+ perform any of the normal <span class="application">initdb</span> operations.
+ Generally, this option is useful for ensuring reliable recovery after
+ changing <a class="xref" href="runtime-config-wal.html#GUC-FSYNC">fsync</a> from <code class="literal">off</code> to
+ <code class="literal">on</code>.
+ </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>config</code></em></code><br /></span><span class="term"><code class="option">--text-search-config=<em class="replaceable"><code>config</code></em></code></span></dt><dd><p>
+ Sets the default text search configuration.
+ See <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TEXT-SEARCH-CONFIG">default_text_search_config</a> for further information.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ Selects the user name of the database superuser. This defaults
+ to the name of the effective user running
+ <code class="command">initdb</code>. It is really not important what the
+ superuser's name is, but one might choose to keep the
+ customary name <span class="systemitem">postgres</span>, even if the operating
+ system user's name is different.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--pwprompt</code></span></dt><dd><p>
+ Makes <code class="command">initdb</code> prompt for a password
+ to give the database superuser. If you don't plan on using password
+ authentication, this is not important. Otherwise you won't be
+ able to use password authentication until you have a password
+ set up.
+ </p></dd><dt><span class="term"><code class="option">-X <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--waldir=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ This option specifies the directory where the write-ahead log
+ should be stored.
+ </p></dd><dt><span class="term"><code class="option">--wal-segsize=<em class="replaceable"><code>size</code></em></code></span></dt><dd><p>
+ Set the <em class="firstterm">WAL segment size</em>, in megabytes. This
+ is the size of each individual file in the WAL log. The default size
+ is 16 megabytes. The value must be a power of 2 between 1 and 1024
+ (megabytes). This option can only be set during initialization, and
+ cannot be changed later.
+ </p><p>
+ It may be useful to adjust this size to control the granularity of
+ WAL log shipping or archiving. Also, in databases with a high volume
+ of WAL, the sheer number of WAL files per directory can become a
+ performance and management problem. Increasing the WAL file size
+ will reduce the number of WAL files.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other, less commonly used, options are also available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d</code><br /></span><span class="term"><code class="option">--debug</code></span></dt><dd><p>
+ Print debugging output from the bootstrap backend and a few other
+ messages of lesser interest for the general public.
+ The bootstrap backend is the program <code class="command">initdb</code>
+ uses to create the catalog tables. This option generates a tremendous
+ amount of extremely boring output.
+ </p></dd><dt><span class="term"><code class="option">--discard-caches</code></span></dt><dd><p>
+ Run the bootstrap backend with the
+ <code class="literal">debug_discard_caches=1</code> option.
+ This takes a very long time and is only of use for deep debugging.
+ </p></dd><dt><span class="term"><code class="option">-L <em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Specifies where <code class="command">initdb</code> should find
+ its input files to initialize the database cluster. This is
+ normally not necessary. You will be told if you need to
+ specify their location explicitly.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-clean</code></span></dt><dd><p>
+ By default, when <code class="command">initdb</code>
+ determines that an error prevented it from completely creating the database
+ cluster, it removes any files it might have created before discovering
+ that it cannot finish the job. This option inhibits tidying-up and is
+ thus useful for debugging.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other options:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">initdb</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">initdb</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.5.3.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
+ Specifies the directory where the database cluster is to be
+ stored; can be overridden using the <code class="option">-D</code> option.
+ </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
+ Specifies whether to use color in diagnostic messages. Possible values
+ are <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></dd><dt><span class="term"><code class="envar">TZ</code></span></dt><dd><p>
+ Specifies the default time zone of the created database cluster. The
+ value should be a full time zone name
+ (see <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a>).
+ </p></dd></dl></div><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ also uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p></div><div class="refsect1" id="id-1.9.5.3.8"><h2>Notes</h2><p>
+ <code class="command">initdb</code> can also be invoked via
+ <code class="command">pg_ctl initdb</code>.
+ </p></div><div class="refsect1" id="id-1.9.5.3.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><span class="application">pg_ctl</span></span></a>, <a class="xref" href="app-postgres.html" title="postgres"><span class="refentrytitle"><span class="application">postgres</span></span></a>, <a class="xref" href="auth-pg-hba-conf.html" title="21.1. The pg_hba.conf File">Section 21.1</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="reference-server.html" title="PostgreSQL Server Applications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pgarchivecleanup.html" title="pg_archivecleanup">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PostgreSQL Server Applications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_archivecleanup</span></td></tr></table></div></body></html> \ No newline at end of file