From 30e355fc80996db0334e9d8d28b05dc299500a3e Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Fri, 7 Apr 2000 13:30:58 +0000 Subject: [PATCH] Fix path to initdb in installation instructions. General cleanup for 7.0. --- doc/src/sgml/advanced.sgml | 60 ++- doc/src/sgml/func.sgml | 106 +++- doc/src/sgml/install.sgml | 1042 +++++++++++++++++++----------------- doc/src/sgml/intro.sgml | 24 +- doc/src/sgml/legal.sgml | 14 +- doc/src/sgml/notation.sgml | 27 +- doc/src/sgml/ports.sgml | 53 +- doc/src/sgml/query.sgml | 121 +++-- doc/src/sgml/sql.sgml | 142 +++-- doc/src/sgml/start.sgml | 533 ++++++++++-------- doc/src/sgml/y2k.sgml | 7 +- 11 files changed, 1233 insertions(+), 896 deletions(-) diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index 3142c32739..af7030e392 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -1,5 +1,5 @@ @@ -106,10 +106,10 @@ SELECT c.name, c.altitude Here the * after cities indicates that the query should be run over cities and all classes below cities in the inheritance hierarchy. Many of the commands that we - have already discussed (select, - update and delete) + have already discussed (SELECT, + UPDATE and DELETE) support this * notation, as do others, like - alter. + ALTER. @@ -118,7 +118,8 @@ SELECT c.name, c.altitude One of the tenets of the relational model is that the - attributes of a relation are atomic. Postgres does not + attributes of a relation are atomic. + Postgres does not have this restriction; attributes can themselves contain sub-values that can be accessed from the query language. For example, you can create attributes that @@ -129,7 +130,8 @@ SELECT c.name, c.altitude Arrays - Postgres allows attributes of an instance to be defined + Postgres allows attributes of an + instance to be defined as fixed-length or variable-length multi-dimensional arrays. Arrays of any base type or user-defined type can be created. To illustrate their use, we first create a @@ -149,11 +151,14 @@ CREATE TABLE SAL_EMP ( a text string (name), a one-dimensional array of int4 (pay_by_quarter), which represents the employee's - salary by quarter and a two-dimensional array of text + salary by quarter and a two-dimensional array of + text (schedule), which represents the employee's weekly - schedule. Now we do some INSERTSs; note that when + schedule. Now we do some INSERTSs; + note that when appending to an array, we enclose the values within - braces and separate them by commas. If you know C, + braces and separate them by commas. If you know + C, this is not unlike the syntax for initializing structures. @@ -168,7 +173,8 @@ INSERT INTO SAL_EMP '{{"talk", "consult"}, {"meeting"}}'); - By default, Postgres uses the "one-based" numbering + By default, Postgres uses the + "one-based" numbering convention for arrays -- that is, an array of n elements starts with array[1] and ends with array[n]. Now, we can run some queries on SAL_EMP. First, we @@ -228,6 +234,11 @@ SELECT SAL_EMP.schedule[1:2][1:1] + More Advanced Features - Postgres has many features not touched upon in this + Postgres has many features not touched + upon in this tutorial introduction, which has been oriented toward newer users of SQL. - These are discussed in more detail in both the User's and Programmer's Guides. + These are discussed in more detail in both the User's and + Programmer's Guides. + - - Installation + + Installation - - + + Installation instructions for - PostgreSQL 7.0. - - + PostgreSQL 7.0. + + - - If you haven't gotten the PostgreSQL distribution, - get it from ftp.postgresql.org, + + If you haven't gotten the PostgreSQL distribution, + get it from ftp.postgresql.org, then unpack it: - -gunzip postgresql-7.0.tar.gz -tar -xf postgresql-7.0.tar -mv postgresql-7.0 /usr/src - - - - Before you start + +> gunzip postgresql-7.0.tar.gz +> tar -xf postgresql-7.0.tar +> mv postgresql-7.0 /usr/src + + - - Building PostgreSQL requires GNU - make. It will not - work with other make programs. On GNU/Linux systems + + Before you start + + + Building PostgreSQL requires GNU + make. It will not + work with other make programs. On GNU/Linux systems GNU make is the default tool, on other systems you may find that - GNU make is installed under the name gmake. + GNU make is installed under the name + gmake. We will use that name from now on to indicate GNU - make, no matter what name it has on your system. - To test for GNU make enter + make, no matter what name it has on your system. + To test for GNU make enter -gmake --version +> gmake --version - If you need to get GNU make, you can - find it at ftp://ftp.gnu.org. - + If you need to get GNU + make, you can + find it at ftp://ftp.gnu.org. + - + Up to date information on supported platforms is at http://www.postgresql.org/docs/admin/ports.htm. - In general, most Unix-compatible platforms with modern libraries should be able to run - PostgreSQL. In the doc subdirectory + In general, most Unix-compatible platforms with modern libraries + should be able to run + PostgreSQL. In the + doc subdirectory of the distribution are several platform-specific FAQ and README documents you might wish to consult if you are having trouble. - Although the minimum required memory for running PostgreSQL - can be as little as 8MB, there are noticeable speed improvements when expanding memory + Although the minimum required memory for running + PostgreSQL + can be as little as 8MB, there are noticeable speed improvements + when expanding memory up to 96MB or beyond. The rule is you can never have too much memory. - + Check that you have sufficient disk space. You will need about 30 Mbytes for the source tree during compilation and about 5 Mbytes for the installation directory. An empty database takes about 1 Mbyte, otherwise they take about five times the amount of space that a flat text file with the same data would take. If you run the regression tests you will temporarily need an extra 20MB. - + - + To check for disk space, use -df -k +> df -k - Considering today's prices for hard disks, getting a large and fast hard disk should + Considering today's prices for hard disks, getting a large and + fast hard disk should probably be in your plans before putting a database into production use. - + - -Installation Procedure + + Installation Procedure - -<ProductName>PostgreSQL</ProductName> Installation + + <productname>PostgreSQL</productname> Installation - -For a fresh install or upgrading from previous releases of -PostgreSQL: - + + For a fresh install or upgrading from previous releases of + PostgreSQL: + - - -Create the PostgreSQL superuser account. -This is the user the server will run as. For production use you -should create a separate, unprivileged account (postgres is -commonly used). If you do not have root access or just want to play around, -your own user account is enough. - - -Running PostgreSQL as root, bin, -or any other account with special access rights is a security risk; -don't do it. The postmaster will in fact refuse -to start as root. - - -You need not do the building and installation itself under this account -(although you can). You will be told when you need to login as the -database superuser. - - + + + Create the PostgreSQL superuser account. + This is the user the server will run as. For production use you + should create a separate, unprivileged account + (postgres is + commonly used). If you do not have root access or just want to play around, + your own user account is enough. + + + Running PostgreSQL as + terateral>, bin, + or any other account with special access rights is a security risk; + don't do it. The postmaster will in fact refuse + to start as root. + + + You need not do the building and installation itself under this account + (although you can). You will be told when you need to login as the + database superuser. + + - - -Configure the source code for your system. It is this step at which -you can specify your actual installation path for the build process -and make choices about what gets installed. Change into the src -subdirectory and type: - -./configure - -followed by any options you might want to give it. For a first installation -you should be able to do fine without any. -For a complete list of options, type: - -./configure --help - - Some of the more commonly used ones are: - - - --prefix=BASEDIR - - - Selects a different base directory for the installation of - PostgreSQL. The default is /usr/local/pgsql. - - - + + + Configure the source code for your system. It is this step at which + you can specify your actual installation path for the build process + and make choices about what gets installed. Change into the + src + subdirectory and type: + +> ./configure + + followed by any options you might want to give it. For a first installation + you should be able to do fine without any. + For a complete list of options, type: + +> ./configure --help + + Some of the more commonly used ones are: + + + --prefix=BASEDIR + + + Selects a different base directory for the installation of + PostgreSQL. The default is + /usr/local/pgsql. + + + - - --enable-locale - - - If you want to use locales. - - - + + --enable-locale + + + If you want to use locales. + + + - - --enable-multibyte - - - Allows the use of multibyte character encodings. This is primarily for - languages like Japanese, Korean, or Chinese. - - - + + --enable-multibyte + + + Allows the use of multibyte character encodings. This is primarily for + languages like Japanese, Korean, or Chinese. + + + - - --with-perl - - - Builds the Perl interface and plperl extension language. - Please note that the Perl interface needs to be - installed into the usual place for Perl modules (typically under - /usr/lib/perl), so you must have root access - to perform the installation step. (It is often easiest to leave out - initially, and then build and install the - Perl interface after completing the installation of PostgreSQL - itself.) - - - + + --with-perl + + + Builds the Perl interface and plperl extension language. + Please note that the Perl interface needs to be + installed into the usual place for Perl modules (typically under + /usr/lib/perl), so you must have root access + to perform the installation step. (It is often easiest to leave out + initially, and then build and install the + Perl interface after completing the installation of PostgreSQL + itself.) + + + - - --with-odbc - - - Builds the ODBC driver package. - - - + + --with-odbc + + + Builds the ODBC driver package. + + + - - --with-tcl - - - Builds interface libraries and programs requiring - Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh. - - - - + + --with-tcl + + + Builds interface libraries and programs requiring + Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh. + + + + - - + + - - -Compile the program. Type - -gmake - -The compilation process can take anywhere from 10 minutes to an hour. -Your mileage will most certainly vary. Remember to use GNU make. - + + + Compile the program. Type + +> gmake + + The compilation process can take anywhere from 10 minutes to an hour. + Your mileage will most certainly vary. Remember to use GNU make. + - -The last line displayed will hopefully be - + + The last line displayed will hopefully be + All of PostgreSQL is successfully made. Ready to install. - - - + + + - - -If you want to test the newly built server before you install it, -you can run the regression tests at this point. The regression tests -are a test suite to verify that PostgreSQL -runs on your machine in the way the developers expected it to. -For detailed instructions see . -(Be sure to use the "parallel regress test" method, since the sequential -method only works with an already-installed server.) - - + + + If you want to test the newly built server before you install it, + you can run the regression tests at this point. The regression tests + are a test suite to verify that PostgreSQL + runs on your machine in the way the developers expected it to. + For detailed instructions see . + (Be sure to use the "parallel regress test" method, since the sequential + method only works with an already-installed server.) + + - - -If you are not upgrading an existing system then skip to -. - + + + If you are not upgrading an existing system then skip to + . + - -You now need to back up your existing database. -To dump your fairly recent post-6.0 database installation, type - -pg_dumpall > db.out - -If you wish to preserve object id's (oids), then use the -o -option when running pg_dumpall. -However, unless you have a -special reason for doing this (such as using OIDs as keys -in tables), don't do it. - + + You now need to back up your existing database. + To dump your fairly recent post-6.0 database installation, type + +> pg_dumpall > db.out + + If you wish to preserve object id's (oids), then use the -o + option when running pg_dumpall. + However, unless you have a + special reason for doing this (such as using OIDs as keys + in tables), don't do it. + - -Make sure to use the pg_dumpall -command from the version you are currently running. -7.0's pg_dumpall will not work on older databases. -However, if you are still using 6.0, do not use the -pg_dumpall script from 6.0 or everything will be -owned by the PostgreSQL superuser after you -reload. In that case -you should grab pg_dumpall from a later -6.x.x release. -If you are upgrading from a version prior to -Postgres95 v1.09 then you must back up your database, -install Postgres95 v1.09, restore your database, -then back it up again. - + + Make sure to use the pg_dumpall + command from the version you are currently running. + 7.0's pg_dumpall will not work on older databases. + However, if you are still using 6.0, do not use the + pg_dumpall script from 6.0 or everything will be + owned by the PostgreSQL superuser after you + reload. In that case + you should grab pg_dumpall from a later + 6.x.x release. + If you are upgrading from a version prior to + Postgres95 v1.09 then you must back + up your database, + install Postgres95 v1.09, restore your database, + then back it up again. + - - - You must make sure that your database is not updated in the middle of - your backup. If necessary, bring down postmaster, edit the permissions - in file /usr/local/pgsql/data/pg_hba.conf - to allow only you on, then - bring postmaster back up. - - - + + + You must make sure that your database is not updated in the middle of + your backup. If necessary, bring down postmaster, edit the permissions + in file /usr/local/pgsql/data/pg_hba.conf + to allow only you on, then + bring postmaster back up. + + + - - -If you are upgrading an existing system then kill the database server now. Type - -ps ax | grep postmaster - -or - -ps -e | grep postmaster - -(It depends on your system which one of these two works. No harm can be done -by typing the wrong one.) -This should list the process numbers for a number of processes, similar -to this: - + + + If you are upgrading an existing system then kill the database + server now. Type + +> ps ax | grep postmaster + + or + +> ps -e | grep postmaster + + (It depends on your system which one of these two works. No harm can be done + by typing the wrong one.) + This should list the process numbers for a number of processes, similar + to this: + 263 ? SW 0:00 (postmaster) 777 p1 S 0:00 grep postmaster - -Type the following line, with pid -replaced by the process id for process postmaster -(263 in the above case). (Do not use the id for the process "grep postmaster".) - -kill pid - - + + Type the following line, with pid + replaced by the process id for process postmaster + (263 in the above case). (Do not use the id for the process + "grep postmaster".) + +> kill pid + + - - -On systems which have PostgreSQL started at boot time, there -is probably a startup file that will accomplish the same thing. For example, on a -Redhat Linux system one might find that - -/etc/rc.d/init.d/postgres.init stop - -works. - - + + + On systems which have PostgreSQL + started at boot time, there + is probably a startup file that will accomplish the same + thing. For example, on a + Redhat Linux system one might find that + +> /etc/rc.d/init.d/postgres.init stop + + works. + + - -Also move the old directories out of the way. Type the following: - -mv /usr/local/pgsql /usr/local/pgsql.old - -(substitute your particular paths). - + + Also move the old directories out of the way. Type the following: + +> mv /usr/local/pgsql /usr/local/pgsql.old + + (substitute your particular paths). + - + - - -Install the PostgreSQL executable files and -libraries. Type - -gmake install - - - -You should do this step as the user that you want the installed executables -to be owned by. This does not have to be the same as the database superuser; -some people prefer to have the installed files be owned by root. - - + + + Install the PostgreSQL executable files and + libraries. Type + +> gmake install + + + + You should do this step as the user that you want the installed executables + to be owned by. This does not have to be the same as the database superuser; + some people prefer to have the installed files be owned by root. + + - - -If necessary, tell your system how to find the new shared libraries. -How to do this varies between platforms. The most widely usable method -is to set the environment variable -LD_LIBRARY_PATH: - -LD_LIBRARY_PATH=/usr/local/pgsql/lib -export LD_LIBRARY_PATH - -on sh, ksh, bash, zsh or - -setenv LD_LIBRARY_PATH /usr/local/pgsql/lib - -on csh or tcsh. -You might want to put this into a shell startup file such as -/etc/profile. - + + + If necessary, tell your system how to find the new shared libraries. + How to do this varies between platforms. The most widely usable method + is to set the environment variable + LD_LIBRARY_PATH: + +> LD_LIBRARY_PATH=/usr/local/pgsql/lib +> export LD_LIBRARY_PATH + + on sh, ksh, bash, zsh or + +> setenv LD_LIBRARY_PATH /usr/local/pgsql/lib + + on csh or tcsh. + You might want to put this into a shell startup file such as + /etc/profile. + - -On some systems the following is the preferred method, but you must have root -access. Edit file /etc/ld.so.conf to add a line - -/usr/local/pgsql/lib - -Then run command /sbin/ldconfig. - + + On some systems the following is the preferred method, but you must have root + access. Edit file /etc/ld.so.conf to add a line + +/usr/local/pgsql/lib + + Then run command /sbin/ldconfig. + - -If in doubt, refer to the manual pages of your system. If you later on get -a message like - + + If in doubt, refer to the manual pages of your system. If you later on get + a message like + psql: error in loading shared libraries libpq.so.2.1: cannot open shared object file: No such file or directory - -then the above was necessary. Simply do this step then. - - + + then the above was necessary. Simply do this step then. + + - - -Create the database installation (the working data files). -To do this you must log in to your -PostgreSQL superuser account. It will not -work as root. - -mkdir /usr/local/pgsql/data -chown postgres /usr/local/pgsql/data -su - postgres -/usr/local/pgsql/initdb -D /usr/local/pgsql/data - - - -The option specifies the location where the data will be -stored. You can use any path you want, it does not have to be under -the installation directory. Just make sure that the superuser account -can write to the directory (or create it, if it doesn't already exist) -before starting initdb. -(If you have already been doing the installation up to now as the PostgreSQL -superuser, you may have to log in as root temporarily to create the data -directory underneath a root-owned directory.) - - + + + Create the database installation (the working data files). + To do this you must log in to your + PostgreSQL superuser account. It will not + work as root. + +> mkdir /usr/local/pgsql/data +> chown postgres /usr/local/pgsql/data +> su - postgres +> /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data + + + + The option specifies the location where the data will be + stored. You can use any path you want, it does not have to be under + the installation directory. Just make sure that the superuser account + can write to the directory (or create it, if it doesn't already exist) + before starting initdb. + (If you have already been doing the installation up to now as the + PostgreSQL + superuser, you may have to log in as root temporarily to create the data + directory underneath a root-owned directory.) + + - - -The previous step should have told you how to start up the database server. -Do so now. The command should look something like - -/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data - -This will start the server in the foreground. To make it detach to -the background, you can use the option, but then you won't -see any log messages the server produces. A better way to put the server -in the background is - -nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \ + + + The previous step should have told you how to start up the database server. + Do so now. The command should look something like + +> /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data + + This will start the server in the foreground. To make it detach to + the background, you can use the option, but then you won't + see any log messages the server produces. A better way to put the server + in the background is + +> nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \ </dev/null >>server.log 2>>1 & - - - + + + - - -If you are upgrading from an existing installation, dump your data back in: - -/usr/local/pgsql/bin/psql -d template1 -f db.out - -You also might want to copy over the old pg_hba.conf -file and any other files you might have had set up for authentication, such -as password files. - - - + + + If you are upgrading from an existing installation, dump your data back in: + +> /usr/local/pgsql/bin/psql -d template1 -f db.out + + You also might want to copy over the old pg_hba.conf + file and any other files you might have had set up for authentication, such + as password files. + + + - -This concludes the installation proper. To make your life more productive and enjoyable -you should look at the following optional steps and suggestions. - + + This concludes the installation proper. To make your life more + productive and enjoyable + you should look at the following optional steps and suggestions. + - - - -Life will be more convenient if you set up some environment variables. First of all -you probably want to include /usr/local/pgsql/bin (or equivalent) -into your PATH. To do this, add the following to your shell startup -file, such as ~/.bash_profile (or /etc/profile, -if you want it to affect every user): - -PATH=$PATH:/usr/local/pgsql/bin - - - -Furthermore, if you set PGDATA in the environment of the PostgreSQL -superuser, you can omit the for postmaster -and initdb. - - + + + + Life will be more convenient if you set up some environment + variables. First of all + you probably want to include + /usr/local/pgsql/bin (or equivalent) + into your PATH. To do this, add the following to + your shell startup + file, such as ~/.bash_profile (or + /etc/profile, + if you want it to affect every user): + +> PATH=$PATH:/usr/local/pgsql/bin + + + + Furthermore, if you set PGDATA in the environment + of the PostgreSQL + superuser, you can omit the for + postmaster + and initdb. + + - - -You probably want to install the man and -HTML documentation. Type - -cd /usr/src/pgsql/postgresql-7.0/doc -gmake install - -This will install files under /usr/local/pgsql/doc -and /usr/local/pgsql/man. To enable your system -to find the man documentation, you need to -add a line like the following to a shell startup file: - -MANPATH=$MANPATH:/usr/local/pgsql/man - - + + + You probably want to install the man and + HTML documentation. Type + +> cd /usr/src/pgsql/postgresql-7.0/doc +> gmake install + + This will install files under /usr/local/pgsql/doc + and /usr/local/pgsql/man. To enable your system + to find the man documentation, you need to + add a line like the following to a shell startup file: + +> MANPATH=$MANPATH:/usr/local/pgsql/man + + - -The documentation is also available in Postscript format. If you have -a Postscript printer, or have your machine already set up to accept -Postscript files using a print filter, then to print the User's Guide -simply type - -cd /usr/local/pgsql/doc -gunzip -c user.ps.tz | lpr - -Here is how you might do it if you have Ghostscript on your system and are -writing to a laserjet printer. - -gunzip -c user.ps.gz | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- | lpr - -Printer setups can vary wildly from system to system. -If in doubt, consult your manuals or your local expert. - + + The documentation is also available in Postscript format. If you have + a Postscript printer, or have your machine already set up to accept + Postscript files using a print filter, then to print the User's Guide + simply type + +> cd /usr/local/pgsql/doc +> gunzip -c user.ps.tz | lpr + + Here is how you might do it if you have Ghostscript on your system and are + writing to a laserjet printer. + +> gunzip -c user.ps.gz \ + | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \ + | lpr + + Printer setups can vary wildly from system to system. + If in doubt, consult your manuals or your local expert. + - -The Adminstrator's Guide should probably be your first reading if you -are completely new to PostgreSQL, as it contains -information about how to set up database users and authentication. - - + + The Adminstrator's Guide should probably be your first reading if you + are completely new to PostgreSQL, as it contains + information about how to set up database users and authentication. + + - - -Usually, you will want to modify your computer so that it will automatically -start the database server whenever it boots. -This is not required; the PostgreSQL server can -be run successfully from non-privileged accounts without root intervention. - - -Different systems have different conventions for starting up daemons at boot time, -so you are advised to familiarize yourself with them. -Most systems have a file /etc/rc.local or -/etc/rc.d/rc.local which is almost certainly no bad place -to put such a command. -Whatever you do, postmaster must be run by the PostgreSQL -superuser (postgres) and not by root or -any other user. Therefore you probably always want to form your command lines -along the lines of su -c '...' postgres. - - -It might be advisable to keep a log of the server output. To start the server that way -try: - -nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres & - - + + + Usually, you will want to modify your computer so that it will automatically + start the database server whenever it boots. + This is not required; the PostgreSQL server can + be run successfully from non-privileged accounts without root intervention. + + + Different systems have different conventions for starting up + daemons at boot time, + so you are advised to familiarize yourself with them. + Most systems have a file /etc/rc.local or + /etc/rc.d/rc.local which is almost + certainly no bad place + to put such a command. + Whatever you do, postmaster must be run by the + PostgreSQL + superuser (postgres) and not by + root or + any other user. Therefore you probably always want to form your command lines + along the lines of su -c '...' postgres. + + + It might be advisable to keep a log of the server output. To + start the server that way + try: + +> nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres & + + - -Here are a few more operating system specific suggestions. + + Here are a few more operating system specific suggestions. - - - -Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris - 2.5.1 to contain the following single line: - -su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" - - - + + + + Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris + 2.5.1 to contain the following single line: + +> su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" + + + - - -In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to - contain the following lines and make it chmod 755 and chown - root:bin. + + + In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to + contain the following lines and make it chmod 755 and chown + root:bin. - + #!/bin/sh [ -x /usr/local/pgsql/bin/postmaster ] && { su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster @@ -550,57 +583,58 @@ In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to -S -o -F > /usr/local/pgsql/errlog' & echo -n ' pgsql' } - + - You may put the line breaks as shown above. The shell is smart - enough to keep parsing beyond end-of-line if there is an - expression unfinished. The exec saves one layer of shell under - the postmaster process so the parent is init. - - + You may put the line breaks as shown above. The shell is smart + enough to keep parsing beyond end-of-line if there is an + expression unfinished. The exec saves one layer of shell under + the postmaster process so the parent is init. + + - - -In RedHat Linux add a file /etc/rc.d/init.d/postgres.init -which is based on the example in contrib/linux/. -Then make a softlink to this file from - /etc/rc.d/rc5.d/S98postgres.init. - - + + + In RedHat Linux add a file + /etc/rc.d/init.d/postgres.init + which is based on the example in contrib/linux/. + Then make a softlink to this file from + /etc/rc.d/rc5.d/S98postgres.init. + + - + - - + + - - -Run the regression tests against the installed server (using the sequential -test method). If you didn't run the tests before installation, you should -definitely do it now. -For detailed instructions see . - - + + + Run the regression tests against the installed server (using the sequential + test method). If you didn't run the tests before installation, you should + definitely do it now. + For detailed instructions see . + + - + - -To start playing around, set up the paths as explained above -and start the server. To create a database, type - -createdb testdb - -Then enter - -psql testdb - -to connect to that database. At the prompt you can enter SQL commands -and start experimenting. - + + To start playing around, set up the paths as explained above + and start the server. To create a database, type + +> createdb testdb + + Then enter + +> psql testdb + + to connect to that database. At the prompt you can enter SQL commands + and start experimenting. + - - - + + @@ -16,7 +16,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma Postgres release 4.2. The Postgres project, led by Professor Michael Stonebraker, was sponsored by the - Defense Advanced Research Projects Agency (DARPA), the + Defense Advanced Research Projects Agency + (DARPA), the Army Research Office (ARO), the National Science Foundation (NSF), and ESL, Inc. @@ -37,7 +38,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma models in part because of its "Spartan simplicity". However, as mentioned, this simplicity often makes the implementation of certain applications very difficult. - Postgres offers substantial additional + Postgres offers substantial additional power by incorporating the following four additional basic concepts in such a way that users can easily extend the system: @@ -62,13 +63,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma - These features put Postgres into the category of databases - referred to as object-relational. Note that this is distinct - from those referred to as object-oriented, which in general - are not as well suited to supporting the traditional relational database languages. - So, although Postgres has some object-oriented features, - it is firmly in the relational database world. In fact, some commercial databases - have recently incorporated features pioneered by Postgres. + These features put Postgres into the + category of databases referred to as + object-relational. Note that this is distinct + from those referred to as object-oriented, + which in general are not as well suited to supporting the + traditional relational database languages. + So, although Postgres has some + object-oriented features, it is firmly in the relational database + world. In fact, some commercial databases have recently + incorporated features pioneered by Postgres. diff --git a/doc/src/sgml/legal.sgml b/doc/src/sgml/legal.sgml index 02da480b49..41436347ee 100644 --- a/doc/src/sgml/legal.sgml +++ b/doc/src/sgml/legal.sgml @@ -1,5 +1,5 @@ @@ -7,7 +7,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas PostgreSQL is Copyright © 1996-2000 - by the PostgreSQL Inc. + by PostgreSQL Inc. and is distributed under the terms of the Berkeley license. @@ -35,14 +35,22 @@ $Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas maintainance, support, updates, enhancements, or modifications. + + + + All trademarks are the property of their respective owners. + @@ -25,13 +25,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho binaries and database files. As the database superuser, all protection mechanisms may be bypassed and any data accessed arbitrarily. - In addition, the Postgres superuser is allowed to execute + In addition, the Postgres superuser is + allowed to execute some support programs which are generally not available to all users. Note that the Postgres superuser is not - the same as the Unix superuser (which will be referred to as root). - The superuser should have a non-zero user identifier (UID) - for security reasons. + the same as the Unix superuser (which will be referred to as + root). + The superuser should have a non-zero user identifier + (UID) for security reasons. @@ -82,18 +84,21 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho In a command synopsis, brackets ([ and ]) indicate an optional phrase or keyword. Anything in braces - ({ and }) and containing vertical bars (|) + ({ and }) and containing vertical bars + (|) indicates that you must choose one. - In examples, parentheses (( and )) are used to group boolean + In examples, parentheses (( and )) are + used to group boolean expressions. | is the boolean operator OR. Examples will show commands executed from various accounts and programs. - Commands executed from the root account will be preceeded with >. + Commands executed from the root account will be preceeded with + >. Commands executed from the Postgres superuser account will be preceeded with %, while commands executed from an unprivileged user's account will be preceeded with @@ -104,8 +109,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho - At the time of writing (Postgres v6.5) the notation for - flagging commands is not universally consistant throughout the documentation set. + At the time of writing (Postgres v7.0) + the notation for + flagging commands is not universally consistant throughout the + documentation set. Please report problems to the Documentation Mailing List. diff --git a/doc/src/sgml/ports.sgml b/doc/src/sgml/ports.sgml index c90eb4cc41..ee2b760ba3 100644 --- a/doc/src/sgml/ports.sgml +++ b/doc/src/sgml/ports.sgml @@ -32,15 +32,15 @@ AIX 4.3.2 RS6000 - v6.5 - 1999-05-26 + v7.0 + 2000-04-05 (Andreas Zeugswetter) - BSDI + BSDI 4.01 x86 - v6.5 - 1999-05-25 + v7.0 + 2000-04-04 (Bruce Momjian @@ -60,12 +60,11 @@ (Pedro J. Lobo) - FreeBSD 2.2.x-4.0 + FreeBSD 4.0 x86 - v6.5 - 1999-05-25 - (Tatsuo Ishii, - Marc Fournier) + v7.0 + 2000-04-04 + (Marc Fournier) HPUX @@ -136,17 +135,17 @@ (Tatsuo Ishii) - Linux 2.0.x + Linux 2.2.5 Sparc - v6.4 - 1998-10-25 + v7.0 + 2000-04-02 (Tom Szybist) - LinuxPPC R4 2.2.1/libc5 + LinuxPPC R4 PPC603e v7.0 - 2000-03-26 + 2000-04-04 Powerbook 2400c (Tatsuo Ishii) @@ -250,20 +249,20 @@ (Frank Ridderbusch) - Windows + Windows/Win32 x86 - v6.4 - 1999-01-06 - Client-side libraries or ODBC/JDBC. No server yet. + v7.0 + 2000-04-02 + Client-side libraries or ODBC/JDBC. No server-side. (Magnus Hagander - Windows NT + WinNT/Cygwin x86 - v6.5 - 1999-05-26 + v7.0 + 2000-03-30 Working with the Cygwin library. - (Daniel Horak) + (Daniel Horak) @@ -273,8 +272,9 @@ For Windows NT, - the server-side port of Postgres has recently been - accomplished. The Cygnus library is required to compile it. + the server-side port of Postgres uses + the RedHat/Cygnus Cygwin library and + toolset. @@ -289,7 +289,8 @@ - At the time of publication, the following platforms have been tested: + At the time of publication, the following platforms have not been + tested for v7.0: Obsolete Platforms diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml index 11b603f652..971be24838 100644 --- a/doc/src/sgml/query.sgml +++ b/doc/src/sgml/query.sgml @@ -1,5 +1,5 @@ @@ -8,20 +8,21 @@ $Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.9 2000/03/31 03:27:41 thomas The Postgres query language is a variant of the SQL3 draft next-generation standard. It - has many extensions such as an extensible type system, + has many extensions to SQL92 such as an + extensible type system, inheritance, functions and production rules. These are - features carried over from the original Postgres query - language, PostQuel. This section provides an overview + features carried over from the original + Postgres query + language, PostQuel. + This section provides an overview of how to use Postgres SQL to perform simple operations. This manual is only intended to give you an idea of our flavor of SQL and is in no way a complete tutorial on SQL. Numerous books have been written on - SQL, including - -[MELT93] and [DATE97]. + SQL92, including + and + . You should be aware that some language features are extensions to the ANSI standard. @@ -111,22 +112,26 @@ CREATE TABLE weather ( - Note that both keywords and identifiers are case-insensitive; identifiers can become - case-sensitive by surrounding them with double-quotes as allowed + Note that both keywords and identifiers are case-insensitive; + identifiers can preserve case by surrounding them with + double-quotes as allowed by SQL92. - Postgres SQL supports the usual + Postgres SQL + supports the usual SQL types int, float, real, smallint, char(N), varchar(N), date, time, and timestamp, as well as other types of general utility and a rich set of geometric types. As we will - see later, Postgres can be customized with an + see later, Postgres can be customized + with an arbitrary number of user-defined data types. Consequently, type names are not syntactical keywords, except where required to support special cases in the SQL92 standard. - So far, the Postgres CREATE command + So far, the Postgres + CREATE command looks exactly like the command used to create a table in a traditional relational system. However, we will presently see that @@ -139,7 +144,7 @@ CREATE TABLE weather ( Populating a Class with Instances - The insert statement is used to populate a class with + The INSERT statement is used to populate a class with instances: @@ -149,9 +154,10 @@ INSERT INTO weather - You can also use the copy command to perform load large + You can also use the COPY command to perform load large amounts of data from flat (ASCII) files. - This is usually faster because the data is read (or written) as a single atomic + This is usually faster because the data is read (or written) as a + single atomic transaction directly to or from the target table. An example would be: @@ -159,7 +165,8 @@ COPY weather FROM '/home/user/weather.txt' USING DELIMITERS '|'; - where the path name for the source file must be available to the backend server + where the path name for the source file must be available to the + backend server machine, not the client, since the backend server reads the file directly. @@ -170,7 +177,7 @@ COPY weather FROM '/home/user/weather.txt' The weather class can be queried with normal relational selection and projection queries. A SQL - select + SELECT statement is used to do this. The statement is divided into a target list (the part that lists the attributes to be returned) and a qualification (the part that specifies @@ -192,7 +199,8 @@ SELECT * FROM weather; |Hayward | 37 | 54 | | 11-29-1994 | +--------------+---------+---------+------+------------+ - You may specify any arbitrary expressions in the target list. For example, you can do: + You may specify any arbitrary expressions in the target list. For + example, you can do: SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather; @@ -200,7 +208,8 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather; Arbitrary Boolean operators - (and, or and not) are + (AND, OR and + NOT) are allowed in the qualification of any query. For example, @@ -235,16 +244,16 @@ SELECT DISTINCT city Redirecting SELECT Queries - Any select query can be redirected to a new class + Any SELECT query can be redirected to a new class SELECT * INTO TABLE temp FROM weather; - This forms an implicit create command, creating a new + This forms an implicit CREATE command, creating a new class temp with the attribute names and types specified - in the target list of the select into command. We can + in the target list of the SELECT INTO command. We can then, of course, perform any operations on the resulting class that we can perform on other classes. @@ -269,7 +278,8 @@ SELECT * INTO TABLE temp FROM weather; This is only a conceptual model. The actual join may - be performed in a more efficient manner, but this is invisible to the user. + be performed in a more efficient manner, but this is invisible + to the user. @@ -307,16 +317,18 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high, sometimes recomputes the same target list several times; this frequently happens when Boolean expressions are connected with an "or". To remove such duplicates, you must use - the select distinct statement. + the SELECT DISTINCT statement. - In this case, both W1 and W2 are surrogates for an + In this case, both W1 and + W2 are surrogates for an instance of the class weather, and both range over all instances of the class. (In the terminology of most - database systems, W1 and W2 are known as range variables.) + database systems, W1 and W2 + are known as range variables.) A query can contain an arbitrary number of class names and surrogates. @@ -326,7 +338,8 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high, Updates - You can update existing instances using the update command. + You can update existing instances using the + UPDATE command. Suppose you discover the temperature readings are all off by 2 degrees as of Nov 28, you may update the data as follow: @@ -343,7 +356,7 @@ UPDATE weather Deletions - Deletions are performed using the delete command: + Deletions are performed using the DELETE command: DELETE FROM weather WHERE city = 'Hayward'; @@ -354,7 +367,7 @@ DELETE FROM weather WHERE city = 'Hayward'; DELETE FROM classname; - Without a qualification, delete will simply + Without a qualification, DELETE will simply remove all instances of the given class, leaving it empty. The system will not request confirmation before doing this. @@ -365,7 +378,7 @@ DELETE FROM classname; Using Aggregate Functions - Like most other query languages, + Like most other relational database products, PostgreSQL supports aggregate functions. An aggregate function computes a single result from multiple input rows. @@ -377,20 +390,20 @@ DELETE FROM classname; It is important to understand the interaction between aggregates and - SQL's where and having clauses. - The fundamental difference between where and - having is this: where selects + SQL's WHERE and HAVING clauses. + The fundamental difference between WHERE and + HAVING is this: WHERE selects input rows before groups and aggregates are computed (thus, it controls which rows go into the aggregate computation), whereas - having selects group rows after groups and + HAVING selects group rows after groups and aggregates are computed. Thus, the - where clause may not contain aggregate functions; + WHERE clause may not contain aggregate functions; it makes no sense to try to use an aggregate to determine which rows will be inputs to the aggregates. On the other hand, - having clauses always contain aggregate functions. - (Strictly speaking, you are allowed to write a having + HAVING clauses always contain aggregate functions. + (Strictly speaking, you are allowed to write a HAVING clause that doesn't use aggregates, but it's wasteful; the same condition - could be used more efficiently at the where stage.) + could be used more efficiently at the WHERE stage.) @@ -408,13 +421,17 @@ SELECT max(temp_lo) FROM weather; SELECT city FROM weather WHERE temp_lo = max(temp_lo); - but this will not work since the aggregate max() can't be used in - where. However, as is often the case the query can be + but this will not work since the aggregate + max can't be used in + WHERE. However, as is often the case the query can be restated to accomplish the intended result; here by using a subselect: + -SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather); +SELECT city FROM weather + WHERE temp_lo = (SELECT max(temp_lo) FROM weather); + This is OK because the sub-select is an independent computation that computes its own aggregate separately from what's happening in the outer select. @@ -422,24 +439,29 @@ SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather); Aggregates are also very useful in combination with - group by clauses. For example, we can get the + GROUP BY clauses. For example, we can get the maximum low temperature observed in each city with + SELECT city, max(temp_lo) FROM weather GROUP BY city; + which gives us one output row per city. We can filter these grouped - rows using having: + rows using HAVING: + SELECT city, max(temp_lo) FROM weather GROUP BY city HAVING min(temp_lo) < 0; + which gives us the same results for only the cities that have some below-zero readings. Finally, if we only care about cities whose - names begin with 'P', we might do + names begin with "P", we might do + SELECT city, max(temp_lo) FROM weather @@ -447,11 +469,12 @@ SELECT city, max(temp_lo) GROUP BY city HAVING min(temp_lo) < 0; + Note that we can apply the city-name restriction in - where, since it needs no aggregate. This is - more efficient than adding the restriction to having, + WHERE, since it needs no aggregate. This is + more efficient than adding the restriction to HAVING, because we avoid doing the grouping and aggregate calculations - for all rows that fail the where check. + for all rows that fail the WHERE check. diff --git a/doc/src/sgml/sql.sgml b/doc/src/sgml/sql.sgml index 1df0a41c8a..e030d4dbf8 100644 --- a/doc/src/sgml/sql.sgml +++ b/doc/src/sgml/sql.sgml @@ -1,5 +1,5 @@ @@ -7,18 +7,28 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E - This chapter originally appeared as a part of + This chapter introduces the mathematical concepts behind + relational databases. It is not required reading, so if you bog + down or want to get straight to some simple examples feel free to + jump ahead to the next chapter and come back when you have more + time and patience. This stuff is supposed to be fun! + + + + This material originally appeared as a part of Stefan Simkovics' Master's Thesis (). - SQL has become the most popular relational query language. + SQL has become the most popular relational query + language. The name SQL is an abbreviation for Structured Query Language. In 1974 Donald Chamberlin and others defined the - language SEQUEL (Structured English Query Language) at IBM + language SEQUEL (Structured English Query + Language) at IBM Research. This language was first implemented in an IBM prototype called SEQUEL-XRM in 1974-75. In 1976-77 a revised version of SEQUEL called SEQUEL/2 was defined and the name was changed to @@ -28,13 +38,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E A new prototype called System R was developed by IBM in 1977. System R - implemented a large subset of SEQUEL/2 (now SQL) and a number of + implemented a large subset of SEQUEL/2 (now SQL) + and a number of changes were made to SQL during the project. System R was installed in a number of user sites, both internal IBM sites and also some selected customer sites. Thanks to the success and acceptance of System R at those user sites IBM started to develop commercial products that - implemented the SQL language based on the System R technology. + implemented the SQL language based on the System + R technology. @@ -48,16 +60,20 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E - SQL is also an official standard now. In 1982 the American National - Standards Institute (ANSI) chartered its Database Committee X3H2 to + SQL is also an official standard now. In 1982 + the American National + Standards Institute (ANSI) chartered its + Database Committee X3H2 to develop a proposal for a standard relational language. This proposal was ratified in 1986 and consisted essentially of the IBM dialect of SQL. In 1987 this ANSI standard was also accepted as an international standard by the International Organization for Standardization (ISO). - This original standard version of SQL is often referred to, - informally, as "SQL/86". In 1989 the original standard was extended + This original standard version of SQL is often + referred to, + informally, as "SQL/86". In 1989 the original + standard was extended and this new standard is often, again informally, referred to as "SQL/89". Also in 1989, a related standard called Database Language Embedded SQL @@ -73,12 +89,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E ratified standard - "International Standard ISO/IEC 9075:1992, Database Language SQL" - in late 1992. SQL/92 is the version - normally meant when people refer to "the SQL standard". A detailed + normally meant when people refer to "the SQL + standard". A detailed description of SQL/92 is given in . At the time of writing this document a new standard informally referred to as SQL3 - is under development. It is planned to make SQL a Turing-complete + is under development. It is planned to make SQL + a Turing-complete language, i.e. all computable queries (e.g. recursive queries) will be possible. This is a very complex task and therefore the completion of the new standard can not be expected before 1999. @@ -100,8 +118,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E - A relational database is a database that is perceived by its - users as a collection of tables (and nothing else but tables). + A relational database is a database that is + perceived by its + users as a collection of tables (and + nothing else but tables). A table consists of rows and columns where each row represents a record and each column represents an attribute of the records contained in the table. @@ -154,13 +174,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E - The tables PART and SUPPLIER may be regarded as entities and - SELLS may be regarded as a relationship between a particular + The tables PART and SUPPLIER may be regarded as + entities and + SELLS may be regarded as a relationship + between a particular part and a particular supplier. - As we will see later, SQL operates on tables like the ones just + As we will see later, SQL operates on tables + like the ones just defined but before that we will study the theory of the relational model. @@ -171,7 +194,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E The mathematical concept underlying the relational model is the - set-theoretic relation which is a subset of the Cartesian + set-theoretic relation which is a subset of + the Cartesian product of a list of domains. This set-theoretic relation gives the model its name (do not confuse it with the relationship from the Entity-Relationship model). @@ -184,7 +208,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E - SIM98 + for a more detailed description). For more information about system catalogs refer to - DATE. + . @@ -1815,10 +1861,10 @@ The only tuple returned by both parts of the query is the one having $SNO=2$. For a detailed discussion on embedded SQL refer to - [], - [], + , + , or - []. + . diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml index 5589eca7f3..ccb43fbb0f 100644 --- a/doc/src/sgml/start.sgml +++ b/doc/src/sgml/start.sgml @@ -1,250 +1,333 @@ - -Getting Started + + Getting Started - - -How to begin work with Postgres for a new user. - - + + + How to begin work with Postgres for a new user. + + - - Some of the steps required to use Postgres - 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 postmaster - process. This person does not have to be the Unix - superuser (root) - or the computer system administrator; a person can install and use -Postgres without any special accounts or privileges. - + + Some of the steps required to use Postgres + 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 + postmaster + process. This person does not have to be the Unix + superuser (root) + or the computer system administrator; a person can install and use + Postgres without any special accounts or + privileges. + - -If you are installing Postgres yourself, then -refer to the Administrator's Guide for instructions on installation, and return -to this guide when the installation is complete. - + + If you are installing Postgres yourself, then + refer to the Administrator's Guide for instructions on + installation, and return + to this guide when the installation is complete. + - - 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 SQL. - + + 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 SQL. + - -Setting Up Your Environment + + Setting Up Your Environment - - This section discusses how to set up - your own environment so that you can use frontend - applications. We assume Postgres has already been - successfully installed and started; refer to the Administrator's Guide -and the installation notes - for how to install Postgres. - + + This section discusses how to set up + your own environment so that you can use frontend + applications. We assume Postgres has + already been + successfully installed and started; refer to the Administrator's Guide + and the installation notes + for how to install Postgres. + - -Postgres 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 psql). - For simplicity, - we will assume that Postgres has been installed in the - directory /usr/local/pgsql. Therefore, wherever - you see the directory /usr/local/pgsql you should - substitute the name of the directory where Postgres is - actually installed. - All Postgres commands are installed in the directory - /usr/local/pgsql/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 - + + Postgres 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 + psql). + For simplicity, + we will assume that Postgres has been + installed in the + directory /usr/local/pgsql. Therefore, wherever + you see the directory /usr/local/pgsql you should + substitute the name of the directory where + Postgres is + actually installed. + All Postgres commands are installed in + the directory + /usr/local/pgsql/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 + + % set path = ( /usr/local/pgsql/bin path ) - - 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 - + + + 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 + + % PATH=/usr/local/pgsql/bin:$PATH % export PATH - - 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. - + - -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 PGHOST environment variable to the name -of the database server machine. The environment variable -PGPORT 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 postmaster, - you should immediately consult your site administrator to make sure that your -environment is properly set up. - + 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. + - + + 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 PGHOST environment + variable to the name + of the database server machine. The environment variable + PGPORT 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 postmaster, + you should immediately consult your site administrator to make + sure that your + environment is properly set up. + - -Starting the Interactive Monitor (psql) + - - Assuming that your site administrator has properly - started the postmaster 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/pgsql/bin to your shell search path. - In most cases, this is all you should have to do in - terms of preparation. - + + Starting the Interactive Monitor (psql) - -As of Postgres v6.3, 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. - + + Assuming that your site administrator has properly + started the postmaster 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/pgsql/bin to your shell search path. + In most cases, this is all you should have to do in + terms of preparation. + - - If you get the following error message from a Postgres - command (such as psql or createdb): + + 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. + - + + If you get the following error message from a + Postgres + command (such as psql or + createdb): + + % psql template1 Connection to database 'postgres' failed. connectDB() failed: Is the postmaster running and accepting connections at 'UNIX Socket' on port '5432'? - + -or + or - + % 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'? - + - it is usually because (1) the postmaster is not running, - or (2) you are attempting to connect to the wrong server host. - If you get the following error message: + it is usually because - + + + + the postmaster is not running, + or + + + + + + you are attempting to connect to the wrong server host. + + + + + + + If you get the following error message: + + FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) - + - it means that the site administrator started the postmaster - as the wrong user. Tell him to restart it as - the Postgres superuser. - - + it means that the site administrator started the + postmaster + as the wrong user. Tell him to restart it as + the Postgres superuser. + + - -Managing a Database + + Managing a Database - - 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. - + + 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. + - -Most Postgres -applications assume that the database name, if not specified, is the same as the name on your computer -account. - + + Most Postgres + applications assume that the database name, if not specified, is + the same as the name on your computer + account. + - -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. - + + 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. + - -Creating a Database + + Creating a Database - - Let's say you want to create a database named mydb. + + Let's say you want to create a database named + mydb. You can do this with the following command: - + % createdb mydb - - + + - -If you do not have the privileges required to create a database, you will see -the following: - + + If you do not have the privileges required to create a database, + you will see + the following: + % createdb mydb WARN:user "your username" is not allowed to create/destroy databases createdb: database creation failed on mydb. - - + + - - Postgres allows you to create any number of databases + + 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 + 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 Postgres refuses to create databases + 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. - - + + - -Accessing a Database + + Accessing a Database - + Once you have constructed a database, you can access it by: - - - -running the Postgres terminal monitor programs - (e.g. psql) which allows you to interactively - enter, edit, and execute SQL commands. - - - - - writing a C program using the LIBPQ subroutine - library. This allows you to submit SQL commands - from C and get answers and status messages back to + + + + Running the Postgres terminal + monitor programs + (e.g. psql) which allows you to + interactively + enter, edit, and execute SQL commands. + + + + + + Using an existing native frontend tool like + pgaccess or + ApplixWare (via + ODBC) to create and manipulate a + database. + + + + + + Using a language like perl or tcl which has a supported + interface for Postgres. Some of + these languages also have convenient and powerful GUI toolkits + which can help you construct custom + applications. pgaccess, mentioned + above, is one such application written in tk/tcl and can be + used as an example. + + + + + + Writing a C program using + the LIBPQ subroutine + library. This allows you to submit + SQL commands + from C and get answers and + status messages back to your program. This interface is discussed further in The PostgreSQL Programmer's Guide. - - - + + + -You might want to start up psql, -to try out the examples in this manual. - It can be activated for the mydb + You might want to start up psql, + to try out the examples in this manual. + It can be activated for the mydb database by typing the command: - + % psql mydb - + You will be greeted with the following message: - + Welcome to the POSTGRESQL interactive sql monitor: Please read the file COPYRIGHT for copyright terms of POSTGRESQL @@ -254,71 +337,79 @@ Welcome to the POSTGRESQL interactive sql monitor: You are currently connected to the database: template1 mydb=> - - + + - -This prompt indicates that the terminal monitor is listening - to you and that you can type SQL queries into a + + This prompt indicates that the terminal monitor is listening + to you and that you can type SQL queries into a workspace maintained by the terminal monitor. - The psql program responds to escape codes that begin - with the backslash character, \ For example, you + The psql program responds to escape + codes that begin + with the backslash character, \ For example, you can get help on the syntax of various - Postgres SQL commands by typing: - + Postgres SQL + commands by typing: + mydb=> \h - + + + Once you have finished entering your queries into the workspace, you can pass the contents of the workspace - to the Postgres server by typing: - + to the Postgres server by typing: + mydb=> \g - + This tells the server to process the query. If you - terminate your query with a semicolon, the \g is not + terminate your query with a semicolon, the \g is not necessary. - psql will automatically process semicolon terminated queries. + psql will automatically process + semicolon terminated queries. To read queries from a file, say myFile, instead of entering them interactively, type: - + mydb=> \i fileName - + - To get out of psql and return to Unix, type - + To get out of psql and return to Unix, type + mydb=> \q - + - and psql will quit and return you to your command - shell. (For more escape codes, type \h at the monitor - prompt.) + and psql 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 SQL queries. Single-line comments are denoted by - --. Everything after the dashes up to the end of the + used freely in SQL queries. Single-line + comments are denoted by + --. Everything after the dashes up to the end of the line is ignored. Multiple-line comments, and comments within a line, - are denoted by /* ... */ - - - - -Destroying a Database + are denoted by /* ... */ + + - + + Destroying a Database + + If you are the database administrator for the database - mydb, you can destroy it using the following Unix command: - + mydb, you can destroy it using the + following Unix command: + % dropdb mydb - + 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. - - - + + + - + @@ -11,7 +11,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 th Written by Thomas Lockhart - on 1998-10-22. + on 1998-10-22. Updated 2000-03-31. @@ -25,7 +25,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 th - The author of this statement, a volunteer on the Postgres + The author of this statement, a volunteer on the + Postgres support team since November, 1996, is not aware of any problems in the Postgres code base related to time transitions around Jan 1, 2000 (Y2K).