1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
<refentry id="APP-INITLOCATION">
<refmeta>
<refentrytitle>
<application>initlocation</application>
</refentrytitle>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
<application>initlocation</application>
</refname>
<refpurpose>
Create a secondary <productname>Postgres</productname> database storage area
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1998-10-02</date>
</refsynopsisdivinfo>
<synopsis>
initlocation [ --location=<replaceable class="parameter">er">al</replaceable>ble> | -D <replaceable class="parameter">altdir</replaceable> ]
[ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ]
[ <replaceable class="parameter">altdir</replaceable> ]
</synopsis>
<refsect2 id="R2-APP-INITLOCATION-1">
<refsect2info>
<date>1998-10-02</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>--location=<replaceable class="parameter">altdir</replaceable></term>
<term>-D <replaceable class="parameter">altdir</replaceable></term>
<term><replaceable class="parameter">altdir</replaceable></term>
<listitem>
<para>
Where in your Unix filesystem do you want alternate databases to go?
The top level directory is called the <envar>PGDATA</envar> directory, so you
might want to point your first alternate location at
<envar>PGDATA2</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--username=<replaceable class="parameter">name</replaceable></term>
<term>-u <replaceable class="parameter">name</replaceable></term>
<term><envar>PGUSER</envar></term>
<listitem>
<para>
Who will be the Unix filesystem owner of this database storage area?
The
<productname>Postgres</productname> superuser is a Unix user
who owns all files that store the database
system and also owns the postmaster and backend processes that access them.
Usually, this is the user who should run <application>initlocation</application>
and who will thus have ownership of the directories and files.
</para>
<note>
<para>
Only the Unix superuser can create a database system with a
different user as the <productname>Postgres</productname> superuser.
Specifying a user other than the <productname>Postgres</productname> superuser
may lead to database security and data integrity problems. Refer to the
<citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle>
for more information.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-APP-INITLOCATION-2">
<refsect2info>
<date>1998-09-26</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<application>initlocation</application> will create directories in
the specified place.
<variablelist>
<varlistentry>
<term><computeroutput>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
</computeroutput></term>
<listitem>
<para>
Successful completion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
We are initializing the database area with username postgres (uid=500).
This user will own all the files and must also own the server process.
Creating Postgres database system directory /usr/local/src/testlocation
mkdir: cannot make directory `<replaceable class="parameter">altdir</replaceable>': Permission denied
</computeroutput></term>
<listitem>
<para>
You do not have filesystem permission to write to the specified directory area.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
Valid username not given. You must specify the username for
the Postgres superuser for the database system you are
initializing, either with the --username option or by default
to the USER environment variable.
</computeroutput></term>
<listitem>
<para>
The username which you have specified is not the
<productname>Postgres</productname> superuser.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
Can't tell what username to use. You don't have the USER
environment variable set to your username and didn't specify the
--username option
</computeroutput></term>
<listitem>
<para>
Specify the <option>--username</option> command line option.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-APP-INITLOCATION-1">
<refsect1info>
<date>1998-09-26</date>
</refsect1info>
<title>
Description
</title>
<para>
<application>initlocation</application>
creates a new <productname>Postgres</productname> secondary database storage area.
A secondary storage area contains a required tree of directories with
the correct file permissions on those directories.
</para>
<para>
Creating a database storage area consists of creating the directories in which
database data might live.
</para>
<para>
There are two kinds of arguments for <application>initlocation</application>.
First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>).
This environment variable should be known to the backend for later use in
<command>CREATE DATABASE/WITH LOCATION</command>
or
<command>createdb -D <replaceable class="parameter">altdir</replaceable></command>.
However, <emphasis>the backend daemon must have this variable in it's
environment</emphasis> for this to succeed.
Second, you may be able to specify an explicit
absolute path to the top directory of the storage area. However,this second
option is possible only if explicitly enabled during the
<productname>Postgres</productname> installation. It is usually disabled
to alleviate security and data integrity concerns.
</para>
<note>
<para>
<productname>Postgres</productname> will add <filename>/base/</filename>
to the specified path to create the storage area.
</para>
<para>
The backend requires that any argument to <option>WITH LOCATION</option> which is
in all uppercase and which has no path delimiters is an environment variable.
</para>
</note>
</refsect1>
<refsect1 id="R1-APP-INITLOCATION-2">
<refsect1info>
<date>1998-09-26</date>
</refsect1info>
<title>
Usage
</title>
<para>
To create a database in an alternate location, using an environment variable:
<programlisting>
% setenv PGDATA2 /opt/postgres/data
% initlocation PGDATA2
% createdb -D PGDATA2
</programlisting>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->