diff options
| author | Marc G. Fournier | 1997-01-15 15:16:25 +0000 |
|---|---|---|
| committer | Marc G. Fournier | 1997-01-15 15:16:25 +0000 |
| commit | 59bb41a235761a605708e7d6387518ea178a72d5 (patch) | |
| tree | 03e1d79e2e428c9ac68bf0004dd92870c06bc3f5 /doc/manual/start.html | |
| parent | f02bd9335010684a64fcd9bc0f86615839d14fc4 (diff) | |
Import of PostgreSQL User Manual
Diffstat (limited to 'doc/manual/start.html')
| -rw-r--r-- | doc/manual/start.html | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/doc/manual/start.html b/doc/manual/start.html new file mode 100644 index 00000000000..db9960661b6 --- /dev/null +++ b/doc/manual/start.html @@ -0,0 +1,231 @@ +<HTML> +<HEAD> + <TITLE>The POSTGRES95 User Manual - GETTING STARTED</TITLE> +</HEAD> + +<BODY> + +<font size=-1> +<A HREF="pg95user.html">[ TOC ]</A> +<A HREF="architec.html">[ Previous ]</A> +<A HREF="query.html">[ Next ]</A> +</font> +<HR> +<H1>3. GETTING STARTED WITH POSTGRES</H1> +<HR> + This section discusses how to start POSTGRES and set up + your own environment so that you can use frontend + applications. We assume POSTGRES has already been + successfully installed. (Refer to the installation notes + for how to install POSTGRES.) +<p> + Some of the steps listed in this section will apply to + all POSTGRES users, and some will apply primarily to + the site database administrator. This site administrator + is the person who installed the software, created + the database directories and started the <B>postmaster</B> + process. This person does not have to be the UNIX + superuser, "root," or the computer system administrator. + In this section, items for end users are labelled + "User" and items intended for the site administrator + are labelled "Admin." + Throughout this manual, any examples that begin with + the character ``%'' are commands that should be typed + at the UNIX shell prompt. Examples that begin with the + character ``*'' are commands in the POSTGRES query + language, POSTGRES <B>SQL</B>. + +<H2><A NAME="setting-up-your-environment">3.1. Admin/User: Setting Up Your Environment</A></H2> + <IMG SRC="figure02.gif" ALT="Figure 2. POSTGRES file layout."> + Figure 2. shows how the POSTGRES distribution is laid + out when installed in the default way. For simplicity, + we will assume that POSTGRES has been installed in the + directory /usr/local/postgres95. Therefore, wherever + you see the directory /usr/local/postgres95 you should + substitute the name of the directory where POSTGRES is + actually installed. + All POSTGRES commands are installed in the directory + /usr/local/postgres95/bin. 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 +<pre> % set path = ( /usr/local/postgres95/bin $path ) +</pre> + in the .login file in your home directory. If you use + a variant of the Bourne shell, such as sh, ksh, or + bash, then you would add +<pre> + % PATH=/usr/local/postgres95/bin:$PATH + % export PATH +</pre> + to the .profile file in your home directory. + From now on, we will assume that you have added the + POSTGRES bin directory to your path. In addition, we + will make frequent reference to "setting a shell + variable" or "setting an environment variable" 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. + +<H2><A NAME="starting-the-postmaster">3.2. Admin: Starting the <B>Postmaster</A></B></H2> + It should be clear from the preceding discussion that + nothing can happen to a database unless the <B>postmaster</B> + process is running. As the site administrator, there + are a number of things you should remember before + starting the <B>postmaster</B>. These are discussed in the + section of this manual titled, "Administering POSTGRES." + However, if POSTGRES has been installed by following + the installation instructions exactly as written, the + following simple command is all you should + need to start the <B>postmaster</B>: +<pre> % postmaster & +</pre> + The <B>postmaster</B> occasionally prints out messages which + are often helpful during troubleshooting. If you wish + to view debugging messages from the <B>postmaster</B>, you can + start it with the -d option and redirect the output to + the log file: +<pre> % postmaster -d >& pm.log & +</pre> + If you do not wish to see these messages, you can type +<pre> % postmaster -S +</pre> + and the <B>postmaster</B> will be "S"ilent. Notice that there + is no ampersand ("&") at the end of the last example. + +<H2><A NAME="adding-and-deleting-users">3.3. Admin: Adding and Deleting Users</A></H2> + The createuser command enables specific users to access + POSTGRES. The destroyuser command removes users and + prevents them from accessing POSTGRES. Note that these + commands only affect users with respect to POSTGRES; + they have no effect administration of users that the + operating system manages. + +<H2><A NAME="starting-applications">3.4. User: Starting Applications</A></H2> + Assuming that your site administrator has properly + started the <B>postmaster</B> process and authorized you to + use the database, you (as a user) may begin to start up + applications. As previously mentioned, you should add + /usr/local/postgres95/bin to your shell search path. + In most cases, this is all you should have to do in + terms of preparation.<A HREF="#1">1</A> + If you get the following error message from a POSTGRES + command (such as <B>psql</B> or createdb): +<pre> connectDB() failed: Is the postmaster running at 'localhost' on port '4322'? +</pre> + it is usually because (1) the <B>postmaster</B> is not running, or (2) you are attempting to connect to the wrong + server host. + If you get the following error message: +<pre> FATAL 1:Feb 17 23:19:55:process userid (2360) != + database owner (268) +</pre> + it means that the site administrator started the <B>postmaster</B> as the wrong user. Tell him to restart it as + the POSTGRES superuser. + +<H2><A NAME="managing-a-database">3.5. User: Managing a Database</A></H2> + Now that POSTGRES is up and running we can create some + databases to experiment with. Here, we describe the + basic commands for managing a database. + +<H3><A NAME="creating-a-database">3.5.1. Creating a Database</A></H3> + Let's say you want to create a database named mydb. + You can do this with the following command: +<pre> % createdb mydb +</pre> + + POSTGRES 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 16 characters in length. + Not every user has authorization to become a database + administrator. If POSTGRES 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. + +<H3><A NAME="accessing-a-database">3.5.2. Accessing a Database</A></H3> + Once you have constructed a database, you can access it + by: + <UL> + <LI>running the POSTGRES terminal monitor programs ( + monitor or <B>psql</B>) which allows you to interactively + enter, edit, and execute <B>SQL</B> commands. + <LI>writing a C program using the LIBPQ subroutine + library. This allows you to submit <B>SQL</B> commands + from C and get answers and status messages back to + your program. This interface is discussed further + in section ??. + </UL> + You might want to start up <B>psql</B>, to try out the examples in this manual. It can be activated for the mydb + database by typing the command: +<pre> % psql mydb +</pre> + You will be greeted with the following message: +<pre> Welcome to the POSTGRES95 interactive sql monitor: + + 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: mydb + + mydb=> +</pre> This prompt indicates that the terminal monitor is listening to you and that you can type <B>SQL</B> queries into a + workspace maintained by the terminal monitor. + The <B>psql</B> program responds to escape codes that begin + with the backslash character, "\". For example, you + can get help on the syntax of various POSTGRES <B>SQL</B> commands by typing: +<pre> mydb=> \h +</pre> + Once you have finished entering your queries into the + workspace, you can pass the contents of the workspace + to the POSTGRES server by typing: +<pre> mydb=> \g +</pre> + This tells the server to process the query. If you + terminate your query with a semicolon, the \g is not + necessary. <B>psql</B> will automatically process semicolon terminated queries. + To read queries from a file, say myFile, instead of + entering them interactively, type: +<pre> mydb=> \i fileName +</pre> + To get out of <B>psql</B> and return to UNIX, type +<pre> mydb=> \q +</pre> + and <B>psql</B> will quit and return you to your command + shell. (For more escape codes, type \h at the monitor + prompt.) + White space (i.e., spaces, tabs and newlines) may be + used freely in <B>SQL</B> queries. Comments are denoted by + <b>--</b>. Everything after the dashes up to the end of the + line is ignored. + +<H3><A NAME="detroying-a-database">3.5.3. Destroying a Database</A></H3> + If you are the database administrator for the database + mydb, you can destroy it using the following UNIX command: +<pre> % destroydb mydb +</pre> + 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 fore-thought. + +<p> +<HR> + +<A NAME="1"><B>1.</B></A> 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 <B>PGHOST</B> environment variable to the name +of the database server machine. The environment variable +<B>PGPORT</B> 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 <B>postmaster</B>, you should immediately consult your site administrator to make sure that your +environment is properly set up. + +<HR> +<font size=-1> +<A HREF="pg95user.html">[ TOC ]</A> +<A HREF="architec.html">[ Previous ]</A> +<A HREF="query.html">[ Next ]</A> +</font> +</BODY> +</HTML> |