begriffs open source - ai-pg/blob - full-docs/txt/app-initdb.txt

   1
   2 initdb
   3
   4    initdb — create a new PostgreSQL database cluster
   5
   6 Synopsis
   7
   8    initdb [option...] [ --pgdata | -D ] directory
   9
  10 Description
  11
  12    initdb creates a new PostgreSQL database cluster.
  13
  14    Creating a database cluster consists of creating the directories in
  15    which the cluster data will live, generating the shared catalog tables
  16    (tables that belong to the whole cluster rather than to any particular
  17    database), and creating the postgres, template1, and template0
  18    databases. The postgres database is a default database meant for use by
  19    users, utilities and third party applications. template1 and template0
  20    are meant as source databases to be copied by later CREATE DATABASE
  21    commands. template0 should never be modified, but you can add objects
  22    to template1, which by default will be copied into databases created
  23    later. See Section 22.3 for more details.
  24
  25    Although initdb will attempt to create the specified data directory, it
  26    might not have permission if the parent directory of the desired data
  27    directory is root-owned. To initialize in such a setup, create an empty
  28    data directory as root, then use chown to assign ownership of that
  29    directory to the database user account, then su to become the database
  30    user to run initdb.
  31
  32    initdb must be run as the user that will own the server process,
  33    because the server needs to have access to the files and directories
  34    that initdb creates. Since the server cannot be run as root, you must
  35    not run initdb as root either. (It will in fact refuse to do so.)
  36
  37    For security reasons the new cluster created by initdb will only be
  38    accessible by the cluster owner by default. The --allow-group-access
  39    option allows any user in the same group as the cluster owner to read
  40    files in the cluster. This is useful for performing backups as a
  41    non-privileged user.
  42
  43    initdb initializes the database cluster's default locale and character
  44    set encoding. These can also be set separately for each database when
  45    it is created. initdb determines those settings for the template
  46    databases, which will serve as the default for all other databases.
  47
  48    By default, initdb uses the locale provider libc (see Section 23.1.4).
  49    The libc locale provider takes the locale settings from the
  50    environment, and determines the encoding from the locale settings.
  51
  52    To choose a different locale for the cluster, use the option --locale.
  53    There are also individual options --lc-* and --icu-locale (see below)
  54    to set values for the individual locale categories. Note that
  55    inconsistent settings for different locale categories can give
  56    nonsensical results, so this should be used with care.
  57
  58    Alternatively, initdb can use the ICU library to provide locale
  59    services by specifying --locale-provider=icu. The server must be built
  60    with ICU support. To choose the specific ICU locale ID to apply, use
  61    the option --icu-locale. Note that for implementation reasons and to
  62    support legacy code, initdb will still select and initialize libc
  63    locale settings when the ICU locale provider is used.
  64
  65    When initdb runs, it will print out the locale settings it has chosen.
  66    If you have complex requirements or specified multiple options, it is
  67    advisable to check that the result matches what was intended.
  68
  69    More details about locale settings can be found in Section 23.1.
  70
  71    To alter the default encoding, use the --encoding. More details can be
  72    found in Section 23.3.
  73
  74 Options
  75
  76    -A authmethod
  77           --auth=authmethod #
  78           This option specifies the default authentication method for
  79           local users used in pg_hba.conf (host and local lines). See
  80           Section 20.1 for an overview of valid values.
  81
  82           initdb will prepopulate pg_hba.conf entries using the specified
  83           authentication method for non-replication as well as replication
  84           connections.
  85
  86           Do not use trust unless you trust all local users on your
  87           system. trust is the default for ease of installation.
  88
  89    --auth-host=authmethod #
  90           This option specifies the authentication method for local users
  91           via TCP/IP connections used in pg_hba.conf (host lines).
  92
  93    --auth-local=authmethod #
  94           This option specifies the authentication method for local users
  95           via Unix-domain socket connections used in pg_hba.conf (local
  96           lines).
  97
  98    -D directory
  99           --pgdata=directory #
 100           This option specifies the directory where the database cluster
 101           should be stored. This is the only information required by
 102           initdb, but you can avoid writing it by setting the PGDATA
 103           environment variable, which can be convenient since the database
 104           server (postgres) can find the data directory later by the same
 105           variable.
 106
 107    -E encoding
 108           --encoding=encoding #
 109           Selects the encoding of the template databases. This will also
 110           be the default encoding of any database you create later, unless
 111           you override it then. The character sets supported by the
 112           PostgreSQL server are described in Section 23.3.1.
 113
 114           By default, the template database encoding is derived from the
 115           locale. If --no-locale is specified (or equivalently, if the
 116           locale is C or POSIX), then the default is UTF8 for the ICU
 117           provider and SQL_ASCII for the libc provider.
 118
 119    -g
 120           --allow-group-access #
 121           Allows users in the same group as the cluster owner to read all
 122           cluster files created by initdb. This option is ignored on
 123           Windows as it does not support POSIX-style group permissions.
 124
 125    --icu-locale=locale #
 126           Specifies the ICU locale when the ICU provider is used. Locale
 127           support is described in Section 23.1.
 128
 129    --icu-rules=rules #
 130           Specifies additional collation rules to customize the behavior
 131           of the default collation. This is supported for ICU only.
 132
 133    -k
 134           --data-checksums #
 135           Use checksums on data pages to help detect corruption by the I/O
 136           system that would otherwise be silent. This is enabled by
 137           default; use --no-data-checksums to disable checksums.
 138
 139           Enabling checksums might incur a small performance penalty. If
 140           set, checksums are calculated for all objects, in all databases.
 141           All checksum failures will be reported in the pg_stat_database
 142           view. See Section 28.2 for details.
 143
 144    --locale=locale #
 145           Sets the default locale for the database cluster. If this option
 146           is not specified, the locale is inherited from the environment
 147           that initdb runs in. Locale support is described in
 148           Section 23.1.
 149
 150           If --locale-provider is builtin, --locale or --builtin-locale
 151           must be specified and set to C, C.UTF-8 or PG_UNICODE_FAST.
 152
 153    --lc-collate=locale
 154           --lc-ctype=locale
 155           --lc-messages=locale
 156           --lc-monetary=locale
 157           --lc-numeric=locale
 158           --lc-time=locale #
 159           Like --locale, but only sets the locale in the specified
 160           category.
 161
 162    --no-locale #
 163           Equivalent to --locale=C.
 164
 165    --builtin-locale=locale #
 166           Specifies the locale name when the builtin provider is used.
 167           Locale support is described in Section 23.1.
 168
 169    --locale-provider={builtin|libc|icu} #
 170           This option sets the locale provider for databases created in
 171           the new cluster. It can be overridden in the CREATE DATABASE
 172           command when new databases are subsequently created. The default
 173           is libc (see Section 23.1.4).
 174
 175    --no-data-checksums #
 176           Do not enable data checksums.
 177
 178    --pwfile=filename #
 179           Makes initdb read the bootstrap superuser's password from a
 180           file. The first line of the file is taken as the password.
 181
 182    -T config
 183           --text-search-config=config #
 184           Sets the default text search configuration. See
 185           default_text_search_config for further information.
 186
 187    -U username
 188           --username=username #
 189           Sets the user name of the bootstrap superuser. This defaults to
 190           the name of the operating-system user running initdb.
 191
 192    -W
 193           --pwprompt #
 194           Makes initdb prompt for a password to give the bootstrap
 195           superuser. If you don't plan on using password authentication,
 196           this is not important. Otherwise you won't be able to use
 197           password authentication until you have a password set up.
 198
 199    -X directory
 200           --waldir=directory #
 201           This option specifies the directory where the write-ahead log
 202           should be stored.
 203
 204    --wal-segsize=size #
 205           Set the WAL segment size, in megabytes. This is the size of each
 206           individual file in the WAL log. The default size is 16
 207           megabytes. The value must be a power of 2 between 1 and 1024
 208           (megabytes). This option can only be set during initialization,
 209           and cannot be changed later.
 210
 211           It may be useful to adjust this size to control the granularity
 212           of WAL log shipping or archiving. Also, in databases with a high
 213           volume of WAL, the sheer number of WAL files per directory can
 214           become a performance and management problem. Increasing the WAL
 215           file size will reduce the number of WAL files.
 216
 217    Other, less commonly used, options are also available:
 218
 219    -c name=value
 220           --set name=value #
 221           Forcibly set the server parameter name to value during initdb,
 222           and also install that setting in the generated postgresql.conf
 223           file, so that it will apply during future server runs. This
 224           option can be given more than once to set several parameters. It
 225           is primarily useful when the environment is such that the server
 226           will not start at all using the default parameters.
 227
 228    -d
 229           --debug #
 230           Print debugging output from the bootstrap backend and a few
 231           other messages of lesser interest for the general public. The
 232           bootstrap backend is the program initdb uses to create the
 233           catalog tables. This option generates a tremendous amount of
 234           extremely boring output.
 235
 236    --discard-caches #
 237           Run the bootstrap backend with the debug_discard_caches=1
 238           option. This takes a very long time and is only of use for deep
 239           debugging.
 240
 241    -L directory #
 242           Specifies where initdb should find its input files to initialize
 243           the database cluster. This is normally not necessary. You will
 244           be told if you need to specify their location explicitly.
 245
 246    -n
 247           --no-clean #
 248           By default, when initdb determines that an error prevented it
 249           from completely creating the database cluster, it removes any
 250           files it might have created before discovering that it cannot
 251           finish the job. This option inhibits tidying-up and is thus
 252           useful for debugging.
 253
 254    -N
 255           --no-sync #
 256           By default, initdb will wait for all files to be written safely
 257           to disk. This option causes initdb to return without waiting,
 258           which is faster, but means that a subsequent operating system
 259           crash can leave the data directory corrupt. Generally, this
 260           option is useful for testing, but should not be used when
 261           creating a production installation.
 262
 263    --no-sync-data-files #
 264           By default, initdb safely writes all database files to disk.
 265           This option instructs initdb to skip synchronizing all files in
 266           the individual database directories, the database directories
 267           themselves, and the tablespace directories, i.e., everything in
 268           the base subdirectory and any other tablespace directories.
 269           Other files, such as those in pg_wal and pg_xact, will still be
 270           synchronized unless the --no-sync option is also specified.
 271
 272           Note that if --no-sync-data-files is used in conjunction with
 273           --sync-method=syncfs, some or all of the aforementioned files
 274           and directories will be synchronized because syncfs processes
 275           entire file systems.
 276
 277           This option is primarily intended for internal use by tools that
 278           separately ensure the skipped files are synchronized to disk.
 279
 280    --no-instructions #
 281           By default, initdb will write instructions for how to start the
 282           cluster at the end of its output. This option causes those
 283           instructions to be left out. This is primarily intended for use
 284           by tools that wrap initdb in platform-specific behavior, where
 285           those instructions are likely to be incorrect.
 286
 287    -s
 288           --show #
 289           Show internal settings and exit, without doing anything else.
 290           This can be used to debug the initdb installation.
 291
 292    --sync-method=method #
 293           When set to fsync, which is the default, initdb will recursively
 294           open and synchronize all files in the data directory. The search
 295           for files will follow symbolic links for the WAL directory and
 296           each configured tablespace.
 297
 298           On Linux, syncfs may be used instead to ask the operating system
 299           to synchronize the whole file systems that contain the data
 300           directory, the WAL files, and each tablespace. See
 301           recovery_init_sync_method for information about the caveats to
 302           be aware of when using syncfs.
 303
 304           This option has no effect when --no-sync is used.
 305
 306    -S
 307           --sync-only #
 308           Safely write all database files to disk and exit. This does not
 309           perform any of the normal initdb operations. Generally, this
 310           option is useful for ensuring reliable recovery after changing
 311           fsync from off to on.
 312
 313    Other options:
 314
 315    -V
 316           --version #
 317           Print the initdb version and exit.
 318
 319    -?
 320           --help #
 321           Show help about initdb command line arguments, and exit.
 322
 323 Environment
 324
 325    PGDATA #
 326           Specifies the directory where the database cluster is to be
 327           stored; can be overridden using the -D option.
 328
 329    PG_COLOR #
 330           Specifies whether to use color in diagnostic messages. Possible
 331           values are always, auto and never.
 332
 333    TZ #
 334           Specifies the default time zone of the created database cluster.
 335           The value should be a full time zone name (see Section 8.5.3).
 336
 337 Notes
 338
 339    initdb can also be invoked via pg_ctl initdb.
 340
 341 See Also
 342
 343    pg_ctl, postgres, Section 20.1