mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-21 22:33:22 +02:00
2150c2edf1
hosting product, on both shared and dedicated machines. We currently offer Oracle and MySQL, and it would be a nice middle-ground. However, as shipped, PostgreSQL lacks the following features we need that MySQL has: 1. The ability to listen only on a particular IP address. Each hosting customer has their own IP address, on which all of their servers (http, ftp, real media, etc.) run. 2. The ability to place the Unix-domain socket in a mode 700 directory. This allows us to automatically create an empty database, with an empty DBA password, for new or upgrading customers without having to interactively set a DBA password and communicate it to (or from) the customer. This in turn cuts down our install and upgrade times. 3. The ability to connect to the Unix-domain socket from within a change-rooted environment. We run CGI programs chrooted to the user's home directory, which is another reason why we need to be able to specify where the Unix-domain socket is, instead of /tmp. 4. The ability to, if run as root, open a pid file in /var/run as root, and then setuid to the desired user. (mysqld -u can almost do this; I had to patch it, too). The patch below fixes problem 1-3. I plan to address #4, also, but haven't done so yet. These diffs are big enough that they should give the PG development team something to think about in the meantime :-) Also, I'm about to leave for 2 weeks' vacation, so I thought I'd get out what I have, which works (for the problems it tackles), now. With these changes, we can set up and run PostgreSQL with scripts the same way we can with apache or proftpd or mysql. In summary, this patch makes the following enhancements: 1. Adds an environment variable PGUNIXSOCKET, analogous to MYSQL_UNIX_PORT, and command line options -k --unix-socket to the relevant programs. 2. Adds a -h option to postmaster to set the hostname or IP address to listen on instead of the default INADDR_ANY. 3. Extends some library interfaces to support the above. 4. Fixes a few memory leaks in PQconnectdb(). The default behavior is unchanged from stock 7.0.2; if you don't use any of these new features, they don't change the operation. David J. MacKenzie
430 lines
14 KiB
Plaintext
430 lines
14 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.14 2000/11/13 15:18:07 momjian 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 id="start-env">
|
|
<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> or <acronym>PGUNIXSOCKET</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 id="start-psql">
|
|
<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 id="start-manage-db">
|
|
<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
|
|
NOTICE: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:
|
|
-->
|