initdb.sgml 10.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
<refentry id="APP-INITDB">
 <refmeta>
  <refentrytitle>
   <application>initdb</application>
  </refentrytitle>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   <application>initdb</application>
  </refname>
  <refpurpose>
   Create a new <productname>Postgres</productname> database installation
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1998-10-02</date>
  </refsynopsisdivinfo>
  <synopsis>
21 22 23 24 25
initdb [ --pgdata=<replaceable class="parameter">dbdir</replaceable> | -r <replaceable class="parameter">dbdir</replaceable> ]
    [ --pglib=<replaceable class="parameter">libdir</replaceable> | -l <replaceable class="parameter">libdir</replaceable> ]
    [ --template=<replaceable class="parameter">template</replaceable> | -t <replaceable class="parameter">template</replaceable> ]
    [ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ]
    [ --noclean | -n ] [ --debug | -d ]
26
  </synopsis>
27

28 29 30 31 32 33 34 35
  <refsect2 id="R2-APP-INITDB-1">
   <refsect2info>
    <date>1998-10-02</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
36

37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
    <variablelist>
     <varlistentry>
      <term>--pglib=<replaceable class="parameter">libdir</replaceable></term>
      <term>-l <replaceable class="parameter">libdir</replaceable></term>
      <term><envar>PGLIB</envar></term>
      <listitem>
       <para>
	Where are the files that make up <productname>Postgres</productname>? 
	Apart from files that
	have to go in particular directories because of their function, the
	files that make up the <productname>Postgres</productname> software 
	were installed in a directory
	called the <replaceable class="parameter">libdir</replaceable> directory.
	An example of a file that will be found
	there that <application>initdb</application>
	needs is <filename>global1.bki.source</filename>,
	which contains all the information that goes
	into the shared catalog tables.
       </para>
      </listitem>
     </varlistentry>
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 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
     <varlistentry>
      <term>--pgdata=<replaceable class="parameter">dbdir</replaceable></term>
      <term>-r <replaceable class="parameter">dbdir</replaceable></term>
      <term><envar>PGDATA</envar></term>
      <listitem>
       <para>
	Where in your Unix filesystem do you want the database data to go?
	The top level directory is called the <envar>PGDATA</envar> directory.
       </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 <productname>Postgres</productname> superuser
	for this database system?  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.
	Or just let it default to you (the Unix user who runs
	<application>initdb</application>).
       </para>
       <note>
	<para>
	 Only the Unix superuser (<literal>root</literal>)
	 can create a database system with an owner
	 different from the <productname>Postgres</productname> superuser.
	</para>
       </note>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    Other, less commonly used, parameters are also available:

    <variablelist>
     <varlistentry>
      <term>--template=<replaceable class="parameter">template</replaceable></term>
      <term>-t <replaceable class="parameter">template</replaceable></term>
      <listitem>
       <para>
	Replace the <literal>template1</literal>
	database in an existing database system, and don't touch anything else.
	This is useful when you need to upgrade your <literal>template1</literal>
	database using <application>initdb</application>
	from a newer release of <productname>Postgres</productname>, 
	or when your <literal>template1</literal>
	database has become corrupted by some system problem.  Normally the
	contents of <literal>template1</literal>
	remain constant throughout the life of the database system.  You can't
	destroy anything by running <application>initdb</application>
	with the 
	<option>--template</option>
	option.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>--noclean</term>
      <term>-n</term>
      <listitem>
       <para>
	By default, when <application>initdb</application>
	determines that error prevent it from completely creating the database
	system, it removes any files it may have created before determining
	that it can't finish the job.  That includes any core files left by
	the programs it invokes.  This option inhibits any tidying-up and is
	thus useful for debugging.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>--debug</term>
      <term>-d</term>
      <listitem>
       <para>
	Print debugging output from the bootstrap backend.  
	The bootstrap backend is the program <application>initdb</application>
	uses to create the catalog tables.  This option generates a tremendous
	amount of output.  It also turns off the final vacuuming step.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <para>
    Files are also input to <application>initdb</application>:

    <variablelist>
     <varlistentry>
      <term><application>postconfig</application></term>
      <listitem>
       <para>
	If appearing somewhere in the Unix command search path 
	(defined by the PATH environment variable).
	This is a program that specifies defaults for some of the
	command options.  See below.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><filename><envar>PGLIB</envar>/global1.bki.source</filename></term>
      <listitem>
       <para>
	Contents for the shared catalog tables in the new database system.  This
	file is part of the <productname>Postgres</productname> software.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><filename><envar>PGLIB</envar>/local1_template1.bki.source</filename></term>
      <listitem>
       <para>
	Contents for the template1 tables in the new database system.  This
	file is part of the <productname>Postgres</productname> software.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-APP-INITDB-2">
   <refsect2info>
    <date>1998-09-26</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    <application>initdb</application> will create files in the
    <envar>PGDATA</envar>
    data area which are the system tables and framework for a complete
    installation.
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-APP-INITDB-1">
  <refsect1info>
   <date>1998-09-26</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <application>initdb</application> creates a new 
   <productname>Postgres</productname> database system.
   A database system is a
   collection of databases that are all administered by the same Unix user
   and managed by a single postmaster.
  </para>
  <para>
   Creating a database system consists of creating the directories in which
   the database data will live, generating the shared catalog tables 
   (tables that don't belong to any particular database), and
   creating the <literal>template1</literal>
   database.  What is the <literal>template1</literal>
   database?  When you create a database, <productname>Postgres</productname> 
   does it by copying
   everything from the <literal>template1</literal>
   database.  It contains catalog tables filled in for things like the
   builtin types.
  </para>
  <para>
   After <application>initdb</application> 
   creates the database, it completes the initialization by running
   <application>vacuum</application>, which resets some optimization parameters.
  </para>
  <para>
   There are three ways to give parameters to <application>initdb</application>.

   <itemizedlist>
    <listitem>
     <para>
      You can use <application>initdb</application> command options.
     </para>
    </listitem>
    <listitem>
     <para>
      You can set environment
      variables before invoking <application>initdb</application>.
     </para>
    </listitem>

    <listitem>
     <para>
      You can have a program called <application>postconfig</application>
      in your Unix command search path.
261 262 263
      <application>initdb</application> invokes that program and that program then writes 
      <application>initdb</application> parameters to its standard output stream.
      This third option is not a common thing to do, however.
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   Command options always override parameters specified any other way.
   The values returned by <application>postconfig</application>
   override any environment variables, but your
   <application>postconfig</application> 
   program may base its output on the environment variables if you want
   their values to be used.
  </para>

  <para>
   The value that <application>postconfig</application> 
   outputs must have the format
   <synopsis>
<replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">var2</replaceable>=<replaceable class="parameter">value2</replaceable> ...
   </synopsis>

   It can output nothing if it doesn't want to supply any parameters.
   The <replaceable>var</replaceable> values are equal to 
   the corresponding environment variable
   names.  For example,
   <programlisting>
PGDATA=/tmp/postgres_test
   </programlisting>
   has the
   same effect as invoking <application>initdb</application>
   with an environment variable called <envar>PGDATA</envar> whose value is
   <filename>/tmp/postgres_test</filename>.
  </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:
-->