diff options
Diffstat (limited to 'doc/src/sgml/man1/initdb.1')
| -rw-r--r-- | doc/src/sgml/man1/initdb.1 | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/doc/src/sgml/man1/initdb.1 b/doc/src/sgml/man1/initdb.1 new file mode 100644 index 0000000..6e2d62a --- /dev/null +++ b/doc/src/sgml/man1/initdb.1 @@ -0,0 +1,460 @@ +'\" t +.\" Title: initdb +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2024 +.\" Manual: PostgreSQL 16.2 Documentation +.\" Source: PostgreSQL 16.2 +.\" Language: English +.\" +.TH "INITDB" "1" "2024" "PostgreSQL 16.2" "PostgreSQL 16.2 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +initdb \- create a new PostgreSQL database cluster +.SH "SYNOPSIS" +.HP \w'\fBinitdb\fR\ 'u +\fBinitdb\fR [\fIoption\fR...] [\fB\-\-pgdata\fR | \fB\-D\fR]\fI directory\fR +.SH "DESCRIPTION" +.PP +\fBinitdb\fR +creates a new +PostgreSQL +database cluster\&. +.PP +Creating a database cluster consists of creating the +directories +in which the cluster data will live, generating the shared catalog tables (tables that belong to the whole cluster rather than to any particular database), and creating the +postgres, +template1, and +template0 +databases\&. The +postgres +database is a default database meant for use by users, utilities and third party applications\&. +template1 +and +template0 +are meant as source databases to be copied by later +\fBCREATE DATABASE\fR +commands\&. +template0 +should never be modified, but you can add objects to +template1, which by default will be copied into databases created later\&. See +Section\ \&23.3 +for more details\&. +.PP +Although +\fBinitdb\fR +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 +\fBchown\fR +to assign ownership of that directory to the database user account, then +\fBsu\fR +to become the database user to run +\fBinitdb\fR\&. +.PP +\fBinitdb\fR +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 +\fBinitdb\fR +creates\&. Since the server cannot be run as root, you must not run +\fBinitdb\fR +as root either\&. (It will in fact refuse to do so\&.) +.PP +For security reasons the new cluster created by +\fBinitdb\fR +will only be accessible by the cluster owner by default\&. The +\fB\-\-allow\-group\-access\fR +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\&. +.PP +\fBinitdb\fR +initializes the database cluster\*(Aqs default locale and character set encoding\&. These can also be set separately for each database when it is created\&. +\fBinitdb\fR +determines those settings for the template databases, which will serve as the default for all other databases\&. +.PP +By default, +\fBinitdb\fR +uses the locale provider +libc +(see +Section\ \&24.1.4)\&. The +libc +locale provider takes the locale settings from the environment, and determines the encoding from the locale settings\&. +.PP +To choose a different locale for the cluster, use the option +\fB\-\-locale\fR\&. There are also individual options +\fB\-\-lc\-*\fR +and +\fB\-\-icu\-locale\fR +(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\&. +.PP +Alternatively, +\fBinitdb\fR +can use the ICU library to provide locale services by specifying +\-\-locale\-provider=icu\&. The server must be built with ICU support\&. To choose the specific ICU locale ID to apply, use the option +\fB\-\-icu\-locale\fR\&. Note that for implementation reasons and to support legacy code, +\fBinitdb\fR +will still select and initialize libc locale settings when the ICU locale provider is used\&. +.PP +When +\fBinitdb\fR +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\&. +.PP +More details about locale settings can be found in +Section\ \&24.1\&. +.PP +To alter the default encoding, use the +\fB\-\-encoding\fR\&. More details can be found in +Section\ \&24.3\&. +.SH "OPTIONS" +.PP +.PP +\fB\-A \fR\fB\fIauthmethod\fR\fR +.br +\fB\-\-auth=\fR\fB\fIauthmethod\fR\fR +.RS 4 +This option specifies the default authentication method for local users used in +pg_hba\&.conf +(host +and +local +lines)\&. See +Section\ \&21.1 +for an overview of valid values\&. +.sp +\fBinitdb\fR +will prepopulate +pg_hba\&.conf +entries using the specified authentication method for non\-replication as well as replication connections\&. +.sp +Do not use +trust +unless you trust all local users on your system\&. +trust +is the default for ease of installation\&. +.RE +.PP +\fB\-\-auth\-host=\fR\fB\fIauthmethod\fR\fR +.RS 4 +This option specifies the authentication method for local users via TCP/IP connections used in +pg_hba\&.conf +(host +lines)\&. +.RE +.PP +\fB\-\-auth\-local=\fR\fB\fIauthmethod\fR\fR +.RS 4 +This option specifies the authentication method for local users via Unix\-domain socket connections used in +pg_hba\&.conf +(local +lines)\&. +.RE +.PP +\fB\-D \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-pgdata=\fR\fB\fIdirectory\fR\fR +.RS 4 +This option specifies the directory where the database cluster should be stored\&. This is the only information required by +\fBinitdb\fR, but you can avoid writing it by setting the +\fBPGDATA\fR +environment variable, which can be convenient since the database server (\fBpostgres\fR) can find the data directory later by the same variable\&. +.RE +.PP +\fB\-E \fR\fB\fIencoding\fR\fR +.br +\fB\-\-encoding=\fR\fB\fIencoding\fR\fR +.RS 4 +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 character sets supported by the +PostgreSQL +server are described in +Section\ \&24.3.1\&. +.sp +By default, the template database encoding is derived from the locale\&. If +\fB\-\-no\-locale\fR +is specified (or equivalently, if the locale is +C +or +POSIX), then the default is +UTF8 +for the ICU provider and +SQL_ASCII +for the +libc +provider\&. +.RE +.PP +\fB\-g\fR +.br +\fB\-\-allow\-group\-access\fR +.RS 4 +Allows users in the same group as the cluster owner to read all cluster files created by +\fBinitdb\fR\&. This option is ignored on +Windows +as it does not support +POSIX\-style group permissions\&. +.RE +.PP +\fB\-\-icu\-locale=\fR\fB\fIlocale\fR\fR +.RS 4 +Specifies the ICU locale when the ICU provider is used\&. Locale support is described in +Section\ \&24.1\&. +.RE +.PP +\fB\-\-icu\-rules=\fR\fB\fIrules\fR\fR +.RS 4 +Specifies additional collation rules to customize the behavior of the default collation\&. This is supported for ICU only\&. +.RE +.PP +\fB\-k\fR +.br +\fB\-\-data\-checksums\fR +.RS 4 +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 +pg_stat_database +view\&. See +Section\ \&30.2 +for details\&. +.RE +.PP +\fB\-\-locale=\fR\fB\fIlocale\fR\fR +.RS 4 +Sets the default locale for the database cluster\&. If this option is not specified, the locale is inherited from the environment that +\fBinitdb\fR +runs in\&. Locale support is described in +Section\ \&24.1\&. +.RE +.PP +\fB\-\-lc\-collate=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-ctype=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-messages=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-monetary=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-numeric=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-time=\fR\fB\fIlocale\fR\fR +.RS 4 +Like +\fB\-\-locale\fR, but only sets the locale in the specified category\&. +.RE +.PP +\fB\-\-no\-locale\fR +.RS 4 +Equivalent to +\fB\-\-locale=C\fR\&. +.RE +.PP +\fB\-\-locale\-provider={\fR\fBlibc\fR\fB|\fR\fBicu\fR\fB}\fR +.RS 4 +This option sets the locale provider for databases created in the new cluster\&. It can be overridden in the +\fBCREATE DATABASE\fR +command when new databases are subsequently created\&. The default is +libc +(see +Section\ \&24.1.4)\&. +.RE +.PP +\fB\-N\fR +.br +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBinitdb\fR +will wait for all files to be written safely to disk\&. This option causes +\fBinitdb\fR +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\&. +.RE +.PP +\fB\-\-no\-instructions\fR +.RS 4 +By default, +\fBinitdb\fR +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 +\fBinitdb\fR +in platform\-specific behavior, where those instructions are likely to be incorrect\&. +.RE +.PP +\fB\-\-pwfile=\fR\fB\fIfilename\fR\fR +.RS 4 +Makes +\fBinitdb\fR +read the bootstrap superuser\*(Aqs password from a file\&. The first line of the file is taken as the password\&. +.RE +.PP +\fB\-S\fR +.br +\fB\-\-sync\-only\fR +.RS 4 +Safely write all database files to disk and exit\&. This does not perform any of the normal +initdb +operations\&. Generally, this option is useful for ensuring reliable recovery after changing +fsync +from +off +to +on\&. +.RE +.PP +\fB\-T \fR\fB\fIconfig\fR\fR +.br +\fB\-\-text\-search\-config=\fR\fB\fIconfig\fR\fR +.RS 4 +Sets the default text search configuration\&. See +default_text_search_config +for further information\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +Sets the user name of the +bootstrap superuser\&. This defaults to the name of the operating\-system user running +\fBinitdb\fR\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-pwprompt\fR +.RS 4 +Makes +\fBinitdb\fR +prompt for a password to give the bootstrap superuser\&. If you don\*(Aqt plan on using password authentication, this is not important\&. Otherwise you won\*(Aqt be able to use password authentication until you have a password set up\&. +.RE +.PP +\fB\-X \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-waldir=\fR\fB\fIdirectory\fR\fR +.RS 4 +This option specifies the directory where the write\-ahead log should be stored\&. +.RE +.PP +\fB\-\-wal\-segsize=\fR\fB\fIsize\fR\fR +.RS 4 +Set the +WAL segment size, 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\&. +.sp +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\&. +.RE +.PP +Other, less commonly used, options are also available: +.PP +\fB\-c \fR\fB\fIname\fR\fR\fB=\fR\fB\fIvalue\fR\fR +.br +\fB\-\-set \fR\fB\fIname\fR\fR\fB=\fR\fB\fIvalue\fR\fR +.RS 4 +Forcibly set the server parameter +\fIname\fR +to +\fIvalue\fR +during +\fBinitdb\fR, and also install that setting in the generated +postgresql\&.conf +file, so that it will apply during future server runs\&. This option can be given more than once to set several parameters\&. It is primarily useful when the environment is such that the server will not start at all using the default parameters\&. +.RE +.PP +\fB\-d\fR +.br +\fB\-\-debug\fR +.RS 4 +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 +\fBinitdb\fR +uses to create the catalog tables\&. This option generates a tremendous amount of extremely boring output\&. +.RE +.PP +\fB\-\-discard\-caches\fR +.RS 4 +Run the bootstrap backend with the +debug_discard_caches=1 +option\&. This takes a very long time and is only of use for deep debugging\&. +.RE +.PP +\fB\-L \fR\fB\fIdirectory\fR\fR +.RS 4 +Specifies where +\fBinitdb\fR +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\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-clean\fR +.RS 4 +By default, when +\fBinitdb\fR +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\&. +.RE +.PP +Other options: +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +initdb +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +initdb +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATA\fR +.RS 4 +Specifies the directory where the database cluster is to be stored; can be overridden using the +\fB\-D\fR +option\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +\fBTZ\fR +.RS 4 +Specifies the default time zone of the created database cluster\&. The value should be a full time zone name (see +Section\ \&8.5.3)\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "NOTES" +.PP +\fBinitdb\fR +can also be invoked via +\fBpg_ctl initdb\fR\&. +.SH "SEE ALSO" +\fBpg_ctl\fR(1), \fBpostgres\fR(1), Section\ \&21.1 |