start.sgml

PostgreSQL7.4.6 for Linux

      from operating system user accounts.  If you connect to a
      database, you can choose what
      <productname>PostgreSQL</productname> user name to connect as;
      if you don't, it will default to the same name as your current
      operating system account.  As it happens, there will always be a
      <productname>PostgreSQL</productname> user account that has the
      same name as the operating system user that started the server,
      and it also happens that that user always has permission to
      create databases.  Instead of logging in as that user you can
      also specify the <option>-U</option> option everywhere to select
      a <productname>PostgreSQL</productname> user name to connect as.
     </para>
    </footnote>
   </para>

   <para>
    You can also create databases with other names.
    <productname>PostgreSQL</productname> allows you to create any
    number of databases at a given site.  Database names must have an
    alphabetic first character and are limited to 63 characters in
    length.  A convenient choice is to create a database with the same
    name as your current user name.  Many tools assume that database
    name as the default, so it can save you some typing.  To create
    that database, simply type
<screen>
<prompt>$</prompt> <userinput>createdb</userinput>
</screen>
   </para>

   <para>
    If you do not want to use your database anymore you can remove it.
    For example, if you are the owner (creator) of the database
    <literal>mydb</literal>, you can destroy it using the following
    command:
<screen>
<prompt>$</prompt> <userinput>dropdb mydb</userinput>
</screen>
    (For this command, the database name does not default to the user
    account name.  You always need to specify it.)  This action
    physically removes all files associated with the database and
    cannot be undone, so this should only be done with a great deal of
    forethought.
   </para>

   <para>
    More about <command>createdb</command> and <command>dropdb</command> may
    be found in <xref linkend="APP-CREATEDB"> and <xref linkend="APP-DROPDB">
    respectively.
   </para>
  </sect1>


  <sect1 id="tutorial-accessdb">
   <title>Accessing a Database</title>

   <indexterm zone="tutorial-accessdb">
    <primary>psql</primary>
   </indexterm>

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

    <itemizedlist spacing="compact" mark="bullet">
     <listitem>
      <para>
       Running the <productname>PostgreSQL</productname> interactive
       terminal program, called <application><firstterm>psql</></application>, which allows you
       to interactively enter, edit, and execute
       <acronym>SQL</acronym> commands.
      </para>
     </listitem>

     <listitem>
      <para>
       Using an existing graphical frontend tool like
       <application>PgAccess</application> or an office suite with
       <acronym>ODBC</acronym> support to create and manipulate a
       database.  These possibilities are not covered in this
       tutorial.
      </para>
     </listitem>

     <listitem>
      <para>
       Writing a custom application, using one of the several
       available language bindings.  These possibilities are discussed
       further in <xref linkend="client-interfaces">.
      </para>
     </listitem>
    </itemizedlist>

    You probably want to start up <command>psql</command>, to try out
    the examples in this tutorial.  It can be activated for the
    <literal>mydb</literal> database by typing the command:
<screen>
<prompt>$</prompt> <userinput>psql mydb</userinput>
</screen>
    If you leave off the database name then it will default to your
    user account name.  You already discovered this scheme in the
    previous section.
   </para>

   <para>
    In <command>psql</command>, you will be greeted with the following
    message:
<screen>
Welcome to psql &version;, the PostgreSQL interactive terminal.
 
Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help on internal slash commands
       \g or terminate with semicolon to execute query
       \q to quit
 
mydb=&gt;
</screen>
    <indexterm><primary>superuser</primary></indexterm>
    The last line could also be
<screen>
mydb=#
</screen>
    That would mean you are a database superuser, which is most likely
    the case if you installed <productname>PostgreSQL</productname>
    yourself.  Being a superuser means that you are not subject to
    access controls.  For the purpose of this tutorial this is not of
    importance.
   </para>

   <para>
    If you have encountered problems starting <command>psql</command>
    then go back to the previous section.  The diagnostics of
    <command>psql</command> and <command>createdb</command> are
    similar, and if the latter worked the former should work as well.
   </para>

   <para>
    The last line printed out by <command>psql</command> is the
    prompt, and it indicates that <command>psql</command> is listening
    to you and that you can type <acronym>SQL</acronym> queries into a
    work space maintained by <command>psql</command>.  Try out these
    commands:
    <indexterm><primary>version</primary></indexterm>
<screen>
<prompt>mydb=&gt;</prompt> <userinput>SELECT version();</userinput>
                            version
----------------------------------------------------------------
 PostgreSQL &version; on i586-pc-linux-gnu, compiled by GCC 2.96
(1 row)

<prompt>mydb=&gt;</prompt> <userinput>SELECT current_date;</userinput>
    date
------------
 2002-08-31
(1 row)

<prompt>mydb=&gt;</prompt> <userinput>SELECT 2 + 2;</userinput>
 ?column?
----------
        4
(1 row)
</screen>
   </para>

   <para>
    The <command>psql</command> program has a number of internal
    commands that are not SQL commands.  They begin with the backslash
    character, <quote><literal>\</literal></quote>.  Some of these
    commands were listed in the welcome message.  For example,
    you can get help on the syntax of various
    <productname>PostgreSQL</productname> <acronym>SQL</acronym>
    commands by typing:
<screen>
<prompt>mydb=&gt;</prompt> <userinput>\h</userinput>
</screen>
   </para>

   <para>
    To get out of <command>psql</command>, type
<screen>
<prompt>mydb=&gt;</prompt> <userinput>\q</userinput>
</screen>
    and <command>psql</command> will quit and return you to your
    command shell. (For more internal commands, type
    <literal>\?</literal> at the <command>psql</command> prompt.)  The
    full capabilities of <command>psql</command> are documented in
    <xref linkend="app-psql">.  If <productname>PostgreSQL</> is
    installed correctly you can also type <literal>man psql</literal>
    at the operating system shell prompt to see the documentation.  In
    this tutorial we will not use these features explicitly, but you
    can use them yourself when you see fit.
   </para>

  </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:
-->