1INITDB(1) PostgreSQL 15.4 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. A database cluster is
13 a collection of databases that are managed by a single server instance.
14 Creating a database cluster consists of creating the directories in
16 which the database data will live, generating the shared catalog tables
17 (tables that belong to the whole cluster rather than to any particular
18 database), and creating the postgres, template1, and template0
19 databases. The postgres database is a default database meant for use by
20 users, utilities and third party applications. template1 and template0
21 are meant as source databases to be copied by later CREATE DATABASE
22 commands. template0 should never be modified, but you can add objects
23 to template1, which by default will be copied into databases created
24 later. See Section 23.3 for more details.
25 Although initdb will attempt to create the specified data directory, it
27 might not have permission if the parent directory of the desired data
28 directory is root-owned. To initialize in such a setup, create an empty
29 data directory as root, then use chown to assign ownership of that
30 directory to the database user account, then su to become the database
31 user to run initdb.
32 initdb must be run as the user that will own the server process,
34 because the server needs to have access to the files and directories
35 that initdb creates. Since the server cannot be run as root, you must
36 not run initdb as root either. (It will in fact refuse to do so.)
37 For security reasons the new cluster created by initdb will only be
39 accessible by the cluster owner by default. The --allow-group-access
40 option allows any user in the same group as the cluster owner to read
41 files in the cluster. This is useful for performing backups as a
42 non-privileged user.
43 initdb initializes the database cluster's default locale and character
45 set encoding. These can also be set separately for each database when
46 it is created. initdb determines those settings for the template
47 databases, which will serve as the default for all other databases. By
48 default, initdb uses the locale provider libc, takes the locale
49 settings from the environment, and determines the encoding from the
50 locale settings. This is almost always sufficient, unless there are
51 special requirements.
52 To choose a different locale for the cluster, use the option --locale.
54 There are also individual options --lc-* (see below) to set values for
55 the individual locale categories. Note that inconsistent settings for
56 different locale categories can give nonsensical results, so this
57 should be used with care.
58 Alternatively, the ICU library can be used to provide locale services.
60 (Again, this only sets the default for subsequently created databases.)
61 To select this option, specify --locale-provider=icu. To choose the
62 specific ICU locale ID to apply, use the option --icu-locale. Note that
63 for implementation reasons and to support legacy code, initdb will
64 still select and initialize libc locale settings when the ICU locale
65 provider is used.
66 When initdb runs, it will print out the locale settings it has chosen.
68 If you have complex requirements or specified multiple options, it is
69 advisable to check that the result matches what was intended.
70 More details about locale settings can be found in Section 24.1.
72 To alter the default encoding, use the --encoding. More details can be
74 found in Section 24.3.
75
77 -A authmethod
78 --auth=authmethod
79 This option specifies the default authentication method for local
80 users used in pg_hba.conf (host and local lines). See Section 21.1
81 for an overview of valid values.
82 initdb will prepopulate pg_hba.conf entries using the specified
84 authentication method for non-replication as well as replication
85 connections.
86 Do not use trust unless you trust all local users on your system.
88 trust is the default for ease of installation.
89 --auth-host=authmethod
91 This option specifies the authentication method for local users via
92 TCP/IP connections used in pg_hba.conf (host lines).
93 --auth-local=authmethod
95 This option specifies the authentication method for local users via
96 Unix-domain socket connections used in pg_hba.conf (local lines).
97 -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 initdb,
102 but you can avoid writing it by setting the PGDATA environment
103 variable, which can be convenient since the database server
104 (postgres) can find the database directory later by the same
105 variable.
106 -E encoding
108 --encoding=encoding
109 Selects the encoding of the template databases. This will also be
110 the default encoding of any database you create later, unless you
111 override it then. The default is derived from the locale, if the
112 libc locale provider is used, or UTF8 if the ICU locale provider is
113 used. The character sets supported by the PostgreSQL server are
114 described in Section 24.3.1.
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 ID, if the ICU locale provider is used.
124 -k
126 --data-checksums
127 Use checksums on data pages to help detect corruption by the I/O
128 system that would otherwise be silent. Enabling checksums may incur
129 a noticeable performance penalty. If set, checksums are calculated
130 for all objects, in all databases. All checksum failures will be
131 reported in the pg_stat_database view. See Section 30.2 for
132 details.
133 --locale=locale
135 Sets the default locale for the database cluster. If this option is
136 not specified, the locale is inherited from the environment that
137 initdb runs in. Locale support is described in Section 24.1.
138 --lc-collate=locale
140 --lc-ctype=locale
141 --lc-messages=locale
142 --lc-monetary=locale
143 --lc-numeric=locale
144 --lc-time=locale
145 Like --locale, but only sets the locale in the specified category.
146 --no-locale
148 Equivalent to --locale=C.
149 --locale-provider={libc|icu}
151 This option sets the locale provider for databases created in the
152 new cluster. It can be overridden in the CREATE DATABASE command
153 when new databases are subsequently created. The default is libc.
154 -N
156 --no-sync
157 By default, initdb will wait for all files to be written safely to
158 disk. This option causes initdb to return without waiting, which is
159 faster, but means that a subsequent operating system crash can
160 leave the data directory corrupt. Generally, this option is useful
161 for testing, but should not be used when creating a production
162 installation.
163 --no-instructions
165 By default, initdb will write instructions for how to start the
166 cluster at the end of its output. This option causes those
167 instructions to be left out. This is primarily intended for use by
168 tools that wrap initdb in platform-specific behavior, where those
169 instructions are likely to be incorrect.
170 --pwfile=filename
172 Makes initdb read the database superuser's password from a file.
173 The first line of the file is taken as the password.
174 -S
176 --sync-only
177 Safely write all database files to disk and exit. This does not
178 perform any of the normal initdb operations. Generally, this option
179 is useful for ensuring reliable recovery after changing fsync from
180 off to on.
181 -T config
183 --text-search-config=config
184 Sets the default text search configuration. See
185 default_text_search_config for further information.
186 -U username
188 --username=username
189 Selects the user name of the database superuser. This defaults to
190 the name of the effective user running initdb. It is really not
191 important what the superuser's name is, but one might choose to
192 keep the customary name postgres, even if the operating system
193 user's name is different.
194 -W
196 --pwprompt
197 Makes initdb prompt for a password to give the database superuser.
198 If you don't plan on using password authentication, this is not
199 important. Otherwise you won't be able to use password
200 authentication until you have a password set up.
201 -X directory
203 --waldir=directory
204 This option specifies the directory where the write-ahead log
205 should be stored.
206 --wal-segsize=size
208 Set the WAL segment size, in megabytes. This is the size of each
209 individual file in the WAL log. The default size is 16 megabytes.
210 The value must be a power of 2 between 1 and 1024 (megabytes). This
211 option can only be set during initialization, and cannot be changed
212 later.
213 It may be useful to adjust this size to control the granularity of
215 WAL log shipping or archiving. Also, in databases with a high
216 volume of WAL, the sheer number of WAL files per directory can
217 become a performance and management problem. Increasing the WAL
218 file size will reduce the number of WAL files.
219 Other, less commonly used, options are also available:
221 -d
223 --debug
224 Print debugging output from the bootstrap backend and a few other
225 messages of lesser interest for the general public. The bootstrap
226 backend is the program initdb uses to create the catalog tables.
227 This option generates a tremendous amount of extremely boring
228 output.
229 --discard-caches
231 Run the bootstrap backend with the debug_discard_caches=1 option.
232 This takes a very long time and is only of use for deep debugging.
233 -L directory
235 Specifies where initdb should find its input files to initialize
236 the database cluster. This is normally not necessary. You will be
237 told if you need to specify their location explicitly.
238 -n
240 --no-clean
241 By default, when initdb determines that an error prevented it from
242 completely creating the database cluster, it removes any files it
243 might have created before discovering that it cannot finish the
244 job. This option inhibits tidying-up and is thus useful for
245 debugging.
246 Other options:
248 -V
250 --version
251 Print the initdb version and exit.
252 -?
254 --help
255 Show help about initdb command line arguments, and exit.
256
258 PGDATA
259 Specifies the directory where the database cluster is to be stored;
260 can be overridden using the -D option.
261 PG_COLOR
263 Specifies whether to use color in diagnostic messages. Possible
264 values are always, auto and never.
265 TZ
267 Specifies the default time zone of the created database cluster.
268 The value should be a full time zone name (see Section 8.5.3).
269 This utility, like most other PostgreSQL utilities, also uses the
271 environment variables supported by libpq (see Section 34.15).
272
274 initdb can also be invoked via pg_ctl initdb.
275
277 pg_ctl(1), postgres(1), Section 21.1
278PostgreSQL 15.4 2023 INITDB(1)