diff options
Diffstat (limited to 'doc/src/sgml/html/app-initdb.html')
| -rw-r--r-- | doc/src/sgml/html/app-initdb.html | 251 |
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..970c12b --- /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.4 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.4 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 |