1INITDB(1) PostgreSQL Server Applications INITDB(1)
2
6 initdb - create a new PostgreSQL database cluster
7
10 initdb [ option... ] --pgdata | -D directory
11
13 initdb creates a new PostgreSQL database cluster. A database cluster is
14 a collection of databases that are managed by a single server instance.
15 Creating a database cluster consists of creating the directories in
17 which the database data will live, generating the shared catalog tables
18 (tables that belong to the whole cluster rather than to any particular
19 database), and creating the template1 and postgres databases. When you
20 later create a new database, everything in the template1 database is
21 copied. (Therefore, anything installed in template1 is automatically
22 copied into each database created later.) The postgres database is a
23 default database meant for use by users, utilities and third party
24 applications.
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 initdb initializes the database cluster's default locale and character
39 set encoding. The character set encoding, collation order (LC_COLLATE)
40 and character set classes (LC_CTYPE, e.g. upper, lower, digit) can be
41 set separately for a database when it is created. initdb determines
42 those settings for the template1 database, which will serve as the
43 default for all other databases.
44 To alter the default collation order or character set classes, use the
46 --lc-collate and --lc-ctype options. Collation orders other than C or
47 POSIX also have a performance penalty. For these reasons it is impor‐
48 tant to choose the right locale when running initdb.
49 The remaining locale categories can be changed later when the server is
51 started. You can also use --locale to set the default for all locale
52 categories, including collation order and character set classes. All
53 server locale values (lc_*) can be displayed via SHOW ALL. More
54 details can be found in in the documentation.
55 To alter the default encoding, use the --encoding. More details can be
57 found in in the documentation.
58
60 -A authmethod
61 --auth=authmethod
63 This option specifies the authentication method for local users
64 used in pg_hba.conf. Do not use trust unless you trust all local
65 users on your system. Trust is the default for ease of installa‐
66 tion.
67 -D directory
69 --pgdata=directory
71 This option specifies the directory where the database cluster
72 should be stored. This is the only information required by
73 initdb, but you can avoid writing it by setting the PGDATA envi‐
74 ronment variable, which can be convenient since the database
75 server (postgres) can find the database directory later by the
76 same variable.
77 -E encoding
79 --encoding=encoding
81 Selects the encoding of the template database. This will also be
82 the default encoding of any database you create later, unless
83 you override it there. The default is derived from the locale,
84 or SQL_ASCII if that does not work. The character sets supported
85 by the PostgreSQL server are described in in the documentation.
86 --locale=locale
88 Sets the default locale for the database cluster. If this option
89 is not specified, the locale is inherited from the environment
90 that initdb runs in. Locale support is described in in the docu‐
91 mentation.
92 --lc-collate=locale
94 --lc-ctype=locale
96 --lc-messages=locale
98 --lc-monetary=locale
100 --lc-numeric=locale
102 --lc-time=locale
104 Like --locale, but only sets the locale in the specified cate‐
105 gory.
106 -X directory
108 --xlogdir=directory
110 This option specifies the directory where the transaction log
111 should be stored.
112 -U username
114 --username=username
116 Selects the user name of the database superuser. This defaults
117 to the name of the effective user running initdb. It is really
118 not important what the superuser's name is, but one might choose
119 to keep the customary name postgres, even if the operating sys‐
120 tem user's name is different.
121 -W
123 --pwprompt
125 Makes initdb prompt for a password to give the database supe‐
126 ruser. If you don't plan on using password authentication, this
127 is not important. Otherwise you won't be able to use password
128 authentication until you have a password set up.
129 --pwfile=filename
131 Makes initdb read the database superuser's password from a file.
132 The first line of the file is taken as the password.
133 Other, less commonly used, parameters are also available:
135 -d
137 --debug
139 Print debugging output from the bootstrap backend and a few
140 other messages of lesser interest for the general public. The
141 bootstrap backend is the program initdb uses to create the cata‐
142 log tables. This option generates a tremendous amount of
143 extremely boring output.
144 -L directory
146 Specifies where initdb should find its input files to initialize
147 the database cluster. This is normally not necessary. You will
148 be told if you need to specify their location explicitly.
149 -n
151 --noclean
153 By default, when initdb determines that an error prevented it
154 from completely creating the database cluster, it removes any
155 files it might have created before discovering that it cannot
156 finish the job. This option inhibits tidying-up and is thus use‐
157 ful for debugging.
158
160 PGDATA Specifies the directory where the database cluster is to be
161 stored; can be overridden using the -D option.
162 This utility, like most other PostgreSQL utilities, also uses the envi‐
164 ronment variables supported by libpq (see in the documentation).
165
167 postgres(1)
168Application 2011-09-22 INITDB(1)