1INITDB(1) PostgreSQL 16.1 Documentation INITDB(1)
2
6 initdb - create a new PostgreSQL database cluster
7
9 initdb [option...] [--pgdata | -D] directory
10
12 initdb creates a new PostgreSQL database cluster.
13 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 23.3 for more details.
24 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 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 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 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 By default, initdb uses the locale provider libc (see Section 24.1.4).
49 The libc locale provider takes the locale settings from the
50 environment, and determines the encoding from the locale settings.
51 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 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 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 More details about locale settings can be found in Section 24.1.
70 To alter the default encoding, use the --encoding. More details can be
72 found in Section 24.3.
73
75 -A authmethod
76 --auth=authmethod
77 This option specifies the default authentication method for local
78 users used in pg_hba.conf (host and local lines). See Section 21.1
79 for an overview of valid values.
80 initdb will prepopulate pg_hba.conf entries using the specified
82 authentication method for non-replication as well as replication
83 connections.
84 Do not use trust unless you trust all local users on your system.
86 trust is the default for ease of installation.
87 --auth-host=authmethod
89 This option specifies the authentication method for local users via
90 TCP/IP connections used in pg_hba.conf (host lines).
91 --auth-local=authmethod
93 This option specifies the authentication method for local users via
94 Unix-domain socket connections used in pg_hba.conf (local lines).
95 -D directory
97 --pgdata=directory
98 This option specifies the directory where the database cluster
99 should be stored. This is the only information required by initdb,
100 but you can avoid writing it by setting the PGDATA environment
101 variable, which can be convenient since the database server
102 (postgres) can find the data directory later by the same variable.
103 -E encoding
105 --encoding=encoding
106 Selects the encoding of the template databases. This will also be
107 the default encoding of any database you create later, unless you
108 override it then. The character sets supported by the PostgreSQL
109 server are described in Section 24.3.1.
110 By default, the template database encoding is derived from the
112 locale. If --no-locale is specified (or equivalently, if the locale
113 is C or POSIX), then the default is UTF8 for the ICU provider and
114 SQL_ASCII for the libc provider.
115 -g
117 --allow-group-access
118 Allows users in the same group as the cluster owner to read all
119 cluster files created by initdb. This option is ignored on Windows
120 as it does not support POSIX-style group permissions.
121 --icu-locale=locale
123 Specifies the ICU locale when the ICU provider is used. Locale
124 support is described in Section 24.1.
125 --icu-rules=rules
127 Specifies additional collation rules to customize the behavior of
128 the default collation. This is supported for ICU only.
129 -k
131 --data-checksums
132 Use checksums on data pages to help detect corruption by the I/O
133 system that would otherwise be silent. Enabling checksums may incur
134 a noticeable performance penalty. If set, checksums are calculated
135 for all objects, in all databases. All checksum failures will be
136 reported in the pg_stat_database view. See Section 30.2 for
137 details.
138 --locale=locale
140 Sets the default locale for the database cluster. If this option is
141 not specified, the locale is inherited from the environment that
142 initdb runs in. Locale support is described in Section 24.1.
143 --lc-collate=locale
145 --lc-ctype=locale
146 --lc-messages=locale
147 --lc-monetary=locale
148 --lc-numeric=locale
149 --lc-time=locale
150 Like --locale, but only sets the locale in the specified category.
151 --no-locale
153 Equivalent to --locale=C.
154 --locale-provider={libc|icu}
156 This option sets the locale provider for databases created in the
157 new cluster. It can be overridden in the CREATE DATABASE command
158 when new databases are subsequently created. The default is libc
159 (see Section 24.1.4).
160 -N
162 --no-sync
163 By default, initdb will wait for all files to be written safely to
164 disk. This option causes initdb to return without waiting, which is
165 faster, but means that a subsequent operating system crash can
166 leave the data directory corrupt. Generally, this option is useful
167 for testing, but should not be used when creating a production
168 installation.
169 --no-instructions
171 By default, initdb will write instructions for how to start the
172 cluster at the end of its output. This option causes those
173 instructions to be left out. This is primarily intended for use by
174 tools that wrap initdb in platform-specific behavior, where those
175 instructions are likely to be incorrect.
176 --pwfile=filename
178 Makes initdb read the bootstrap superuser's password from a file.
179 The first line of the file is taken as the password.
180 -S
182 --sync-only
183 Safely write all database files to disk and exit. This does not
184 perform any of the normal initdb operations. Generally, this option
185 is useful for ensuring reliable recovery after changing fsync from
186 off to on.
187 -T config
189 --text-search-config=config
190 Sets the default text search configuration. See
191 default_text_search_config for further information.
192 -U username
194 --username=username
195 Selects the user name of the bootstrap superuser. This defaults to
196 the name of the cluster owner.
197 -W
199 --pwprompt
200 Makes initdb prompt for a password to give the bootstrap superuser.
201 If you don't plan on using password authentication, this is not
202 important. Otherwise you won't be able to use password
203 authentication until you have a password set up.
204 -X directory
206 --waldir=directory
207 This option specifies the directory where the write-ahead log
208 should be stored.
209 --wal-segsize=size
211 Set the WAL segment size, in megabytes. This is the size of each
212 individual file in the WAL log. The default size is 16 megabytes.
213 The value must be a power of 2 between 1 and 1024 (megabytes). This
214 option can only be set during initialization, and cannot be changed
215 later.
216 It may be useful to adjust this size to control the granularity of
218 WAL log shipping or archiving. Also, in databases with a high
219 volume of WAL, the sheer number of WAL files per directory can
220 become a performance and management problem. Increasing the WAL
221 file size will reduce the number of WAL files.
222 Other, less commonly used, options are also available:
224 -c name=value
226 --set name=value
227 Forcibly set the server parameter name to value during initdb, and
228 also install that setting in the generated postgresql.conf file, so
229 that it will apply during future server runs. This option can be
230 given more than once to set several parameters. It is primarily
231 useful when the environment is such that the server will not start
232 at all using the default parameters.
233 -d
235 --debug
236 Print debugging output from the bootstrap backend and a few other
237 messages of lesser interest for the general public. The bootstrap
238 backend is the program initdb uses to create the catalog tables.
239 This option generates a tremendous amount of extremely boring
240 output.
241 --discard-caches
243 Run the bootstrap backend with the debug_discard_caches=1 option.
244 This takes a very long time and is only of use for deep debugging.
245 -L directory
247 Specifies where initdb should find its input files to initialize
248 the database cluster. This is normally not necessary. You will be
249 told if you need to specify their location explicitly.
250 -n
252 --no-clean
253 By default, when initdb determines that an error prevented it from
254 completely creating the database cluster, it removes any files it
255 might have created before discovering that it cannot finish the
256 job. This option inhibits tidying-up and is thus useful for
257 debugging.
258 Other options:
260 -V
262 --version
263 Print the initdb version and exit.
264 -?
266 --help
267 Show help about initdb command line arguments, and exit.
268
270 PGDATA
271 Specifies the directory where the database cluster is to be stored;
272 can be overridden using the -D option.
273 PG_COLOR
275 Specifies whether to use color in diagnostic messages. Possible
276 values are always, auto and never.
277 TZ
279 Specifies the default time zone of the created database cluster.
280 The value should be a full time zone name (see Section 8.5.3).
281 This utility, like most other PostgreSQL utilities, also uses the
283 environment variables supported by libpq (see Section 34.15).
284
286 initdb can also be invoked via pg_ctl initdb.
287
289 pg_ctl(1), postgres(1), Section 21.1
290PostgreSQL 16.1 2023 INITDB(1)