Provide a command ‘hydra-init’ to initialise/upgrade the database

For schema upgrades, hydra-init executes the files
src/sql/upgrade-<N>.sql, each of which upgrades the schema from
version N-1 to N.  The upgrades are wrapped in a transaction.

doc/manual/installation.xml

@@ -73,21 +73,23 @@
   <section>
     <title>Installation</title>
 
+<!--
     <para>
       Hydra can be installed using Nixpkgs:
 
       <screen>
-nix-env -Ai hydra -f /path/to/nixpkgs</screen>
+nix-env -f /path/to/nixpkgs -iA hydra</screen>
 
       This makes the tools available in your Nix user environment,
       <literal>$HOME/.nix-profile</literal> by default.
     </para>
+-->
 
     <para>
-      Alternatively, the latest development snapshot can be installed
+      The latest development snapshot of Hydra can be installed
       by visiting the URL <link
       xlink:href="http://hydra.nixos.org/view/hydra/unstable"><literal>http://hydra.nixos.org/view/hydra/unstable</literal></link>
-      and use the one-click install available at one of the build
+      and using the one-click install available at one of the build
       pages. You can also install Hydra through the channel by
       performing the following commands:
 
@@ -101,8 +103,10 @@ nix-env -i hydra</screen>
       Command completion should reveal a number of command-line tools from Hydra:
 
           <screen>
-hydra-build      hydra-evaluator     hydra-server
-hydra-eval-jobs  hydra-queue-runner  hydra-update-gc-roots</screen>
+hydra-build      hydra-init          hydra-update-gc-roots
+hydra-eval-jobs  hydra-queue-runner  
+hydra-evaluator  hydra-server
+</screen>
     </para>
   </section>
 
@@ -116,24 +120,46 @@ hydra-eval-jobs  hydra-queue-runner  hydra-update-gc-roots</screen>
 
     <para>
       To setup a PostgreSQL database with <emphasis>hydra</emphasis>
-      as database name and user name, issue the following commands:
+      as database name and user name, issue the following commands on
+      the PostgreSQL server:
 
       <screen>
-createdb hydra
-echo "CREATE USER hydra WITH PASSWORD '&lt;your-password&gt;' ;" | psql hydra
-cat $prefix/share/hydra/sql/hydra-postgresql.sql | psql hydra
-echo "GRANT ALL ON DATABASE hydra TO hydra;" | psql hydra</screen>
+createuser -S -D -R -P hydra
+createdb -O hydra hydra</screen>
 
       Note that <emphasis>$prefix</emphasis> is the location of Hydra
       in the nix store.
     </para>
 
     <para>
-      For SQLite, the following command is all it takes to create the
-      database:
+      Hydra uses an environment variable to know which database should
+      be used, and a variable which point to a location that holds
+      some state. To set these variables for a PostgreSQL database,
+      add the following to the file <filename>~/.profile</filename> of
+      the user running the Hydra services.
 
       <screen>
-cat $prefix/share/hydra/sql/hydra-sqlite.sql | sqlite3 /path/to/hydra.sqlite</screen>
+export HYDRA_DBI="dbi:Pg:dbname=hydra;host=dbserver.example.org;user=hydra;"
+export HYDRA_DATA=/var/lib/hydra</screen>
+
+      You can provide the username and password in the file
+      <filename>~/.pgpass</filename>, e.g.
+
+      <screen>
+dbserver.example.org:*:hydra:hydra:password</screen>
+
+      Make sure that the <emphasis>HYDRA_DATA</emphasis> directory
+      exists and is writable for the user which will run the Hydra
+      services.  For a SQLite database, the
+      <varname>HYDRA_DBI</varname> should be set to something like
+      <literal>dbi:SQLite:/path/to/hydra.sqlite</literal>
+    </para>
+
+    <para>
+      Having set these environment variables, you can now initialise
+      the database by doing:
+      <screen>
+hydra-init</screen>
     </para>
 
     <para>
@@ -148,23 +174,17 @@ echo "INSERT INTO UserRoles(userName, role) values('root', 'admin');" | psql hyd
       /path/to/hydra.sqlite</command>.
     </para>
 
-    <para>
-      Hydra uses an environment variable to know which database should
-      be used, and a variable which point to a location that holds
-      some state. To set these variables for a PostgreSQL database,
-      add the following to the <filename>.profile</filename> of the
-      user running the Hydra services.
+  </section>
 
+  <section>
+    <title>Upgrading</title>
+
+    <para>If you're upgrading Hydra from a previous version, you
+    should do the following to perform any necessary database schema migrations:
       <screen>
-export HYDRA_DBI="dbi:Pg:dbname=hydra;host=localhost;"
-export HYDRA_DATA=/var/lib/hydra</screen> 
-
-      Make sure that the <emphasis>HYDRA_DATA</emphasis> directory
-      exists and is writable for the user which will run the Hydra
-      services.  For a SQLite database, the
-      <varname>HYDRA_DBI</varname> should be set to something like
-      <literal>dbi:SQLite:/path/to/hydra.sqlite</literal>
+hydra-init</screen>
     </para>
+
   </section>
 
   <section>