start.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.11 2000/05/02 20:01:52 thomas Exp $
-->

 <chapter id="start">
  <title>Getting Started</title>

  <abstract>
   <para>
    How to begin work with <productname>Postgres</productname> for a new user.
   </para>
  </abstract>

  <para>
   Some  of the steps required to use <productname>Postgres</productname>
   can be performed by any Postgres user, and some must be done by
   the site database administrator.  This site administrator 
   is the person who installed the  software,  created
   the  database  directories  and  started the
   <application>postmaster</application>
   process.  This person does not  have  to  be  the  Unix
   superuser ("root")
   or the computer system administrator; a person can install and use
   <productname>Postgres</productname> without any special accounts or 
   privileges.
  </para>

  <para>
   If you are installing <productname>Postgres</productname> yourself, then
   refer to the Administrator's Guide for instructions on
   installation, and return
   to this guide when the installation is complete.
  </para>

  <para>
   Throughout this manual, any examples  that  begin  with
   the  character  "<literal>%</literal>" are commands that should be typed
   at the Unix shell prompt.  Examples that begin with the
   character "<literal>*</literal>" are commands in the Postgres query 
   language, Postgres <acronym>SQL</acronym>.
  </para>

  <sect1>
   <title>Setting Up Your Environment</title>

   <para>
    This section discusses how to set up
    your own environment  so  that  you  can  use  frontend
    applications.  We assume <productname>Postgres</productname> has
    already been 
    successfully installed and started; refer to the Administrator's Guide
    and the installation  notes
    for how to install Postgres.
   </para>

   <para>
    <productname>Postgres</productname> is a client/server
    application. As a user,
    you only need access to the client portions of the installation
    (an example
    of a client application is the interactive monitor
    <application>psql</application>).
    For simplicity,
    we will assume that <productname>Postgres</productname> has been
    installed in the
    directory  <filename>/usr/local/pgsql</filename>.   Therefore, wherever
    you see the directory <filename>/usr/local/pgsql</filename> you  should
    substitute  the name of the directory where
    <productname>Postgres</productname> is
    actually installed.
    All <productname>Postgres</productname> commands are installed  in
    the directory
    <filename>/usr/local/pgsql/bin</filename>.   Therefore,  you should add
    this directory to your shell command path.  If you  use
    a variant of the Berkeley C shell, such as csh or tcsh,
    you would add

    <programlisting>
% set path = ( /usr/local/pgsql/bin path )
    </programlisting>

    in the <filename>.login</filename> file in your home directory.
    If you use
    a  variant  of  the  Bourne  shell, such as sh, ksh, or
    bash, then you would add

    <programlisting>
% PATH=/usr/local/pgsql/bin:$PATH
% export PATH
    </programlisting>

    to the .profile file in your home directory.
    From now on, we will assume that  you  have  added  the
    <productname>Postgres</productname>  bin  directory to your path.
    In addition, we
    will make frequent reference to <quote>setting a shell  
     variable</quote>  or  <quote>setting an environment
     variable</quote> throughout
    this document.  If you did  not  fully  understand  the
    last  paragraph  on  modifying  your  search  path, you
    should consult the Unix manual pages that describe your
    shell before going any further.
   </para>

   <para>
    If your site administrator has not set things up in the
    default  way,  you may have some more work to do.  For example, if
    the database
    server machine is a remote machine, you
    will need to set the <acronym>PGHOST</acronym> environment
    variable to the name
    of the database server machine.   The  environment  variable
    <acronym>PGPORT</acronym> may also have to be set.  The bottom
    line is this: if
    you try to start an application  program  and  it  complains
    that it cannot connect to the <application>postmaster</application>,
    you should immediately consult your site administrator to make
    sure that your
    environment is properly set up.
   </para>

  </sect1>

  <sect1>
   <title>Starting the Interactive Monitor (psql)</title>

   <para>
    Assuming that  your  site  administrator  has  properly
    started  the  <application>postmaster</application>  process and
    authorized you to
    use the database, you (as a user) may begin to start up
    applications.   As previously mentioned, you should add
    <filename>/usr/local/pgsql/bin</filename> to your  shell  search path.
    In  most  cases,  this  is all you should have to do in
    terms of preparation.
   </para>

   <para>
    Two different styles of connections
    are supported. The site administrator will have chosen to allow
    TCP/IP network connections
    or will have restricted database access to local (same-machine)
    socket connections only.
    These choices become significant if you encounter problems in
    connecting to a database, since you will want to confirm that you
    are choosing an allowed connection option.
   </para>

   <para>
    If  you get the following error message from a
    <productname>Postgres</productname>
    command (such as <application>psql</application> or
    <application>createdb</application>):

    <programlisting>
% psql template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting connections
    at 'UNIX Socket' on port '5432'?
    </programlisting>

    or

    <programlisting>
% psql -h localhost template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting TCP/IP
    (with -i) connections at 'localhost' on port '5432'?
    </programlisting>

    it is usually because

    <itemizedlist mark="bullet" spacing="compact">
     <listitem>
      <para>
       the <application>postmaster</application>  is  not  running,
       or
      </para>
     </listitem>

     <listitem>
      <para>
       you are attempting to connect to the wrong server host.
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    If you get the following error message:

    <programlisting>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
    </programlisting>

    it means that the site administrator started the
    <application>postmaster</application>
    as  the  wrong user.  Tell him to restart it as
    the <productname>Postgres</productname> superuser.
   </para>
  </sect1>

  <sect1>
   <title>Managing a Database</title>

   <para>
    Now that <productname>Postgres</productname> is up and running we
    can create  some
    databases  to  experiment  with.  Here, we describe the
    basic commands for managing a database.
   </para>

   <para>
    Most <productname>Postgres</productname>
    applications assume that the database name, if not specified, is
    the same as the name on your computer
    account.
   </para>

   <para>
    If your database administrator has set up your account without
    database creation privileges,
    then she should have told you what the name of your database is. If
    this is the case, then you
    can skip the sections on creating and destroying databases.
   </para>

   <sect2>
    <title>Creating a Database</title>

    <para>
     Let's say you want to create  a  database  named
     <database>mydb</database>.
     You can do this with the following command:
     <programlisting>
% createdb mydb
     </programlisting>
    </para>

    <para>
     If you do not have the privileges required to create a database,
     you will see
     the following:
     <programlisting>
% createdb mydb
WARN:user "your username" is not allowed to create/destroy databases
createdb: database creation failed on mydb.
     </programlisting>
    </para>

    <para>
     <productname>Postgres</productname>  allows  you to create any
     number of databases
     at a  given  site  and  you  automatically  become  the
     database  administrator  of  the database you just created.
     Database names must  have  an  alphabetic  first
     character and are limited to 32 characters in length.
     Not  every  user has authorization to become a database
     administrator.  If <productname>Postgres</productname> refuses to 
     create databases
     for you, then the site administrator needs to grant you
     permission to  create  databases.   Consult  your  site
     administrator if this occurs.
    </para>
   </sect2>

   <sect2>
    <title>Accessing a Database</title>

    <para>
     Once you have constructed a database, you can access it
     by:

     <itemizedlist spacing="compact" mark="bullet">
      <listitem>
       <para>
	Running the <productname>Postgres</productname>  terminal
	monitor  programs
	(e.g. <application>psql</application>) which allows you to
	interactively
        enter, edit, and execute <acronym>SQL</acronym> commands.
       </para>
      </listitem>

      <listitem>
       <para>
	Using an existing native frontend tool like
	<application>pgaccess</application> or
	<application>ApplixWare</application> (via
	<acronym>ODBC</acronym>) to create and manipulate a 
	database.
       </para>
      </listitem>

      <listitem>
       <para>
	Using a language like perl or tcl which has a supported
	interface for <productname>Postgres</productname>. Some of
	these languages also have convenient and powerful GUI toolkits 
	which can help you construct custom
	applications. <application>pgaccess</application>, mentioned
	above, is one such application written in tk/tcl and can be
	used as an example.
       </para>
      </listitem>

      <listitem>
       <para>
	Writing a <acronym>C</acronym>  program  using
	the  LIBPQ  subroutine
        library.   This  allows  you  to submit
	<acronym>SQL</acronym> commands
        from <acronym>C</acronym> and get answers and
	status messages  back  to
        your  program.   This interface is discussed further
        in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
       </para>
      </listitem>
     </itemizedlist>

     You might want to start up <application>psql</application>, 
     to try out the examples in this manual.
     It can be activated for the <database>mydb</database>
     database by typing the command:
     <programlisting>
% psql mydb
     </programlisting>

     You will be greeted with the following message:
     <programlisting>
Welcome to the POSTGRESQL interactive sql monitor:
  Please read the file COPYRIGHT for copyright terms of POSTGRESQL

   type \? for help on slash commands
   type \q to quit
   type \g or terminate with semicolon to execute query
 You are currently connected to the database: template1

mydb=>
     </programlisting>
    </para>

    <para>
     This prompt indicates that the terminal monitor is listening
     to you and that you can type <acronym>SQL</acronym> queries into a
     workspace maintained by the terminal monitor.
     The <application>psql</application> program responds to escape
     codes  that  begin
     with  the  backslash  character, "<literal>\</literal>"  For example, you
     can get help on the syntax of various
     <productname>Postgres</productname> <acronym>SQL</acronym>
     commands by typing:
     <programlisting>
mydb=> \h
     </programlisting>
    </para>

    <para>
     Once  you  have finished entering your queries into the
     workspace, you can pass the contents of  the  workspace
     to the <productname>Postgres</productname> server by typing:
     <programlisting>
mydb=> \g
     </programlisting>

     This  tells  the  server  to process the query.  If you
     terminate your query with a semicolon, the  "<literal>\g</literal>" is  not
     necessary.
     <application>psql</application> will automatically process
     semicolon terminated queries.
     To read queries from a file,  say  myFile,  instead  of
     entering them interactively, type:
     <programlisting>
mydb=> \i fileName
     </programlisting>

     To get out of <application>psql</application> and return to Unix, type
     <programlisting>
mydb=> \q
     </programlisting>

     and  <application>psql</application>  will  quit  and  return
     you to your command
     shell. (For more escape codes, type <command>\h</command> at  the 
     monitor prompt.)
     White  space  (i.e.,  spaces, tabs and newlines) may be
     used freely in <acronym>SQL</acronym> queries.  Single-line
     comments  are  denoted  by
     "<literal>--</literal>".   Everything  after the dashes up to the end of the
     line is ignored. Multiple-line comments, and comments within a line,
     are denoted by "<literal>/* ... */</literal>".
    </para>
   </sect2>

   <sect2>
    <title>Destroying a Database</title>

    <para>
     If you are the database administrator for the  database
     <database>mydb</database>,  you can destroy it using the
     following Unix command:
     <programlisting>
% dropdb mydb
     </programlisting>
     This action physically removes all of  the  Unix  files
     associated  with  the database and cannot be undone, so
     this should only be done with a  great  deal  of  forethought.
    </para>
   </sect2>
  </sect1>

 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:t
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:
-->