From: Thomas G. Lockhart Date: Thu, 20 May 1999 05:39:29 +0000 (+0000) Subject: Rearrange and consolidate the Admin Guide. X-Git-Tag: REL6_5~203 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=32cfa65e492b0250c8d26256524c5dfdfecb1a09;p=postgresql Rearrange and consolidate the Admin Guide. Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides. --- diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index 7850f4f85c..9bf1f39465 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -1,11 +1,19 @@ - (last updated 1999-04-08) + (last updated 1999-05-19) - PostgreSQL is copyright (C) 1998-9 + PostgreSQL is copyright (©) 1998-9 by the Postgres Global Development Group. @@ -131,12 +140,13 @@ Your name here... &ports; &config; + &layout; &install; &installw; &runtime; &security; - &options; &start-ag; + &trouble; &recovery; ®ress; &release; @@ -155,7 +165,7 @@ Don't bother with an index until we get some index entries. diff --git a/doc/src/sgml/layout.sgml b/doc/src/sgml/layout.sgml new file mode 100644 index 0000000000..398b5f92a9 --- /dev/null +++ b/doc/src/sgml/layout.sgml @@ -0,0 +1,78 @@ + +System Layout + + +
+<ProductName>Postgres</ProductName> file layout + +
+ + +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/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 + +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 you have 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 must go back and make sure that your +environment is properly set up. + + + + + diff --git a/doc/src/sgml/pg_options.sgml b/doc/src/sgml/pg_options.sgml index 434cf68077..a95cf03f25 100644 --- a/doc/src/sgml/pg_options.sgml +++ b/doc/src/sgml/pg_options.sgml @@ -1,45 +1,45 @@ - - - - -Massimo -Dal Zotto - - -Transcribed 1998-10-16 - - -Using pg_options - - - - -Contributed by Massimo Dal Zotto - - - - -The optional file data/pg_options contains runtime -options used by the backend to control trace messages and other backend -tunable parameters. -What makes this file interesting is the fact that it is re-read by a backend -when it receives a SIGHUP signal, making thus possible to change run-time -options on the fly without needing to restart -Postgres. -The options specified in this file may be debugging flags used by the trace -package (backend/utils/misc/trace.c) or numeric -parameters which can be used by the backend to control its behaviour. -New options and parameters must be defined in -backend/utils/misc/trace.c and -backend/include/utils/trace.h. - - -For example suppose we want to add conditional trace messages and a tunable -numeric parameter to the code in file foo.c. -All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into -backend/include/utils/trace.h: - - + + + + + Massimo + Dal Zotto + + + Transcribed 1998-10-16 + + + pg_options + + + + + Contributed by Massimo Dal Zotto + + + + + The optional file data/pg_options contains runtime + options used by the backend to control trace messages and other backend + tunable parameters. + What makes this file interesting is the fact that it is re-read by a backend + when it receives a SIGHUP signal, making thus possible to change run-time + options on the fly without needing to restart + Postgres. + The options specified in this file may be debugging flags used by the trace + package (backend/utils/misc/trace.c) or numeric + parameters which can be used by the backend to control its behaviour. + New options and parameters must be defined in + backend/utils/misc/trace.c and + backend/include/utils/trace.h. + + + For example suppose we want to add conditional trace messages and a tunable + numeric parameter to the code in file foo.c. + All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into + backend/include/utils/trace.h: + + /* file trace.h */ enum pg_option_enum { ... @@ -48,23 +48,23 @@ enum pg_option_enum { NUM_PG_OPTIONS /* must be the last item of enum */ }; - + -and a corresponding line in backend/utils/misc/trace.c: + and a corresponding line in backend/utils/misc/trace.c: - + /* file trace.c */ static char *opt_names[] = { ... "foo", /* trace foo functions */ "fooparam" /* foo tunable parameter */ }; - + -Options in the two files must be specified in exactly the same order. -In the foo source files we can now reference the new flags with: + Options in the two files must be specified in exactly the same order. + In the foo source files we can now reference the new flags with: - + /* file foo.c */ #include "trace.h" #define foo_param pg_options[OPT_FOO_PARAM] @@ -77,54 +77,54 @@ foo_function(int x, int y) do_more_foo(x, y); } } - - - -Existing files using private trace flags can be changed by simply adding -the following code: + + + + Existing files using private trace flags can be changed by simply adding + the following code: - + #include "trace.h" /* int my_own_flag = 0; -- removed */ #define my_own_flag pg_options[OPT_MY_OWN_FLAG] - - - -All pg_options are initialized to zero at backend startup. If we need a -different default value we must add some initialization code at the beginning -of PostgresMain. + + + + All pg_options are initialized to zero at backend startup. If we need a + different default value we must add some initialization code at the beginning + of PostgresMain. -Now we can set the foo_param and enable foo trace by writing values into the -data/pg_options file: + Now we can set the foo_param and enable foo trace by writing values into the + data/pg_options file: - + # file pg_options ... foo=1 fooparam=17 - - - -The new options will be read by all new backends when they are started. -To make effective the changes for all running backends we need to send a -SIGHUP to the postmaster. The signal will be automatically sent to all the -backends. We can also activate the changes only for a specific backend by -sending the SIGHUP directly to it. - - -pg_options can also be specified with the switch of -Postgres: - - + + + + The new options will be read by all new backends when they are started. + To make effective the changes for all running backends we need to send a + SIGHUP to the postmaster. The signal will be automatically sent to all the + backends. We can also activate the changes only for a specific backend by + sending the SIGHUP directly to it. + + + pg_options can also be specified with the switch of + Postgres: + + postgres options -T "verbose=2,query,hostlookup-" - - - -The functions used for printing errors and debug messages can now make use -of the syslog(2) facility. Message printed to stdout -or stderr are prefixed by a timestamp containing also the backend pid: - - + + + + The functions used for printing errors and debug messages can now make use + of the syslog(2) facility. Message printed to stdout + or stderr are prefixed by a timestamp containing also the backend pid: + + #timestamp #pid #message 980127.17:52:14.173 [29271] StartTransactionCommand 980127.17:52:14.174 [29271] ProcessUtility: drop table t; @@ -134,518 +134,103 @@ or stderr are prefixed by a timestamp containing also the backend pid: 980127.19:52:14.292 [29286] Async_NotifyFrontEnd 980127.19:52:14.413 [29286] Async_NotifyFrontEnd done 980127.19:52:14.466 [29286] Async_NotifyHandler done - - - -This format improves readability of the logs and allows people to understand -exactly which backend is doing what and at which time. It also makes -easier to write simple awk or perl scripts which monitor the log to -detect database errors or problem, or to compute transaction time statistics. - - -Messages printed to syslog use the log facility LOG_LOCAL0. -The use of syslog can be controlled with the syslog pg_option. -Unfortunately many functions call directly printf() -to print their messages to stdout or stderr and this output can't be -redirected to syslog or have timestamps in it. -It would be advisable that all calls to printf would be replaced with the -PRINTF macro and output to stderr be changed to use EPRINTF instead so that -we can control all output in a uniform way. - - - -The new pg_options mechanism is more convenient than defining new backend -option switches because: - - - - -we don't have to define a different switch for each thing we want to control. -All options are defined as keywords in an external file stored in the data -directory. - - - - - -we don't have to restart Postgres to change - the setting of some option. -Normally backend options are specified to the postmaster and passed to each -backend when it is started. Now they are read from a file. - - - - - -we can change options on the fly while a backend is running. We can thus -investigate some problem by activating debug messages only when the problem -appears. We can also try different values for tunable parameters. - - - - -The format of the pg_options file is as follows: - - + + + + This format improves readability of the logs and allows people to understand + exactly which backend is doing what and at which time. It also makes + easier to write simple awk or perl scripts which monitor the log to + detect database errors or problem, or to compute transaction time statistics. + + + Messages printed to syslog use the log facility LOG_LOCAL0. + The use of syslog can be controlled with the syslog pg_option. + Unfortunately many functions call directly printf() + to print their messages to stdout or stderr and this output can't be + redirected to syslog or have timestamps in it. + It would be advisable that all calls to printf would be replaced with the + PRINTF macro and output to stderr be changed to use EPRINTF instead so that + we can control all output in a uniform way. + + + + The new pg_options mechanism is more convenient than defining new backend + option switches because: + + + + + we don't have to define a different switch for each thing we want to control. + All options are defined as keywords in an external file stored in the data + directory. + + + + + + we don't have to restart Postgres to change + the setting of some option. + Normally backend options are specified to the postmaster and passed to each + backend when it is started. Now they are read from a file. + + + + + + we can change options on the fly while a backend is running. We can thus + investigate some problem by activating debug messages only when the problem + appears. We can also try different values for tunable parameters. + + + + + The format of the pg_options file is as follows: + + # comment option=integer_value # set value for option option # set option = 1 option+ # set option = 1 option- # set option = 0 - - -Note that keyword can also be -an abbreviation of the option name defined in -backend/utils/misc/trace.c. - - - -The options currently defined in -backend/utils/misc/trace.c are the following: - - - - -all - - - -Global trace flag. Allowed values are: - - - - - -0 - - - -Trace messages enabled individually - - - - - - -1 - - - -Enable all trace messages - - - - - - --1 - - - -Disable all trace messages - - - - - - - - - - -verbose - - - -Verbosity flag. Allowed values are: - - - - - -0 - - - -No messages. This is the default. - - - - - - -1 - - - -Print information messages. - - - - - - -2 - - - -Print more information messages. - - - - - - - - - - -query - - - -Query trace flag. Allowed values are: - - - - - -0 - - - -Don't print query. - - - - - - -1 - - - -Print a condensed query in one line. - - - - - - -4 - - - -Print the full query. - - - - - - - - - - -plan - - - -Print query plan. - - - - - - -parse - - - -Print parser output. - - - - - - -rewritten - - - -Print rewritten query. - - - - - - -parserstats - - - -Print parser statistics. - - - - - - -plannerstats - - - -Print planner statistics. - - - - - - -executorstats - - - -Print executor statistics. - - - - - - -shortlocks - - - -Currently unused but needed to enable features in the future. - - - - - - -locks - - - -Trace locks. - - - - - - -userlocks - - - -Trace user locks. - - - - - - -spinlocks - - - -Trace spin locks. - - - - - - -notify - - - -Trace notify functions. - - - - - - -malloc - - - -Currently unused. - - - - - - -palloc - - - -Currently unused. - - - - - - -lock_debug_oidmin - - - -Minimum relation oid traced by locks. - - - - - - -lock_debug_relid - - - -oid, if not zero, of relation traced by locks. - - - - - - -lock_read_priority - - - -Currently unused. - - - - - - -deadlock_timeout - - - -Deadlock check timer. - - - - - - -syslog - - - -syslog flag. Allowed values are: - - - - - -0 - - - -Messages to stdout/stderr. - - - - - - -1 - - - -Messages to stdout/stderr and syslog. - - - - - - -2 - - - -Messages only to syslog. - - - - - - - - - - -hostlookup - - - -Enable hostname lookup in ps_status. - - - - - - -showportnumber - - - -Show port number in ps_status. - - - - - - -notifyunlock - - - -Unlock of pg_listener after notify. - - - - - - -notifyhack - - - -Remove duplicate tuples from pg_listener. - - - - - - -For example my pg_options file contains the following values: - - -verbose=2 -query -hostlookup -showportnumber - - - - - - -Some of the existing code using private variables and option switches has -been changed to make use of the pg_options feature, mainly in -postgres.c. It would be advisable to modify -all existing code -in this way, so that we can get rid of many of the switches on -the Postgres command line -and can have more tunable options -with a unique place to put option values. - - - + + + Note that keyword can also be + an abbreviation of the option name defined in + backend/utils/misc/trace.c. + + + + Refer to The Administrator's Guide chapter + on runtime options for a complete list of currently supported + options. + + + + Some of the existing code using private variables and option switches has + been changed to make use of the pg_options feature, mainly in + postgres.c. It would be advisable to modify + all existing code + in this way, so that we can get rid of many of the switches on + the Postgres command line + and can have more tunable options + with a unique place to put option values. + + + + + diff --git a/doc/src/sgml/pgaccess.sgml b/doc/src/sgml/pgaccess.sgml deleted file mode 100644 index 90e02cd044..0000000000 --- a/doc/src/sgml/pgaccess.sgml +++ /dev/null @@ -1,8 +0,0 @@ - -<Command>pgaccess</Command> - - -This section needs to be written. Volunteers? - - - diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 5d7e1e6a8c..1db1f03dea 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,11 +1,19 @@ - (last updated 1998-02-23) + (last updated 1998-05-19) @@ -242,21 +250,18 @@ Your name here... - &sql; - &environ; - &manage; - &syntax; + &sql; + &syntax; &datatype; &oper; &func; &typeconv; - &keys; + &keys; &array; &inherit; - &query-ug; + &environ; + &manage; &storage; - &psql; - &pgaccess; &commands; @@ -274,7 +279,6 @@ Your name here... &installw; &runtime; &security; - &options; &start-ag; &recovery; ®ress; @@ -331,6 +335,7 @@ Your name here... &arch-dev; + &options; &geqo; &protocol; &signals; diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index b71dd862f1..c29876f369 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,10 +1,18 @@ @@ -87,6 +96,7 @@ Bigger updates to the installation instructions (install and config). + @@ -96,23 +106,23 @@ Bigger updates to the installation instructions (install and config). -PostgreSQL Programmer's Guide - - Covering v6.4 for general release - - - The PostgreSQL Development Team - + PostgreSQL Programmer's Guide + + Covering v6.5 for general release + + + The PostgreSQL Development Team + - - Thomas - Lockhart - - Caltech/JPL - - + + Thomas + Lockhart + + Caltech/JPL + + @@ -121,17 +131,17 @@ Bigger updates to the installation instructions (install and config). TGL --> - (last updated 1998-10-27) - + (last updated 1999-05-19) + - - -PostgreSQL is copyright (C) 1998 -by the Postgres Global Development Group. - - + + + PostgreSQL is copyright (©) 1998-9 + by the Postgres Global Development Group. + + - + - -Summary - - -Postgres, - developed originally in the UC Berkeley Computer Science Department, - pioneered many of the object-relational concepts - now becoming available in some commercial databases. -It provides SQL92/SQL3 language support, - transaction integrity, and type extensibility. - PostgreSQL is a public-domain, - open source descendant of this original Berkeley code. - - - -&intro-pg; -&arch-pg; -&extend; -&xfunc; -&xtypes; -&xoper; -&xaggr; -&rules; -&xindex; -&gist; -&xplang; -&dfunc; + + Summary + + + Postgres, + developed originally in the UC Berkeley Computer Science Department, + pioneered many of the object-relational concepts + now becoming available in some commercial databases. + It provides SQL92/SQL3 language support, + transaction integrity, and type extensibility. + PostgreSQL is a public-domain, + open source descendant of this original Berkeley code. + + + + &intro-pg; + &arch-pg; + &extend; + &xfunc; + &xtypes; + &xoper; + &xaggr; + &rules; + &xindex; + &gist; + &xplang; + &dfunc; @@ -183,33 +193,34 @@ Disable it until we put in some info. &func-ref; --> -&trigger; -&spi; -&lobj; -&libpq; -&libpqpp; -&libpgtcl; -&ecpg; -&odbc; -&jdbc; - + &trigger; + &spi; + &lobj; + &libpq; + &libpqpp; + &libpgtcl; + &ecpg; + &odbc; + &jdbc; + - -&arch-dev; -&geqo; -&protocol; -&signals; -&compiler; -&bki; -&page; + + &arch-dev; + &options; + &geqo; + &protocol; + &signals; + &compiler; + &bki; + &page; -&docguide; + &docguide; -&biblio; + &biblio; [MELT93] and [DATE97]. - You should be aware that some language features -are not part of the ANSI standard. - - - -Interactive Monitor - - - In the examples that follow, we assume that you have - created the mydb database as described in the previous - subsection and have started psql. - Examples in this manual can also be found in - /usr/local/pgsql/src/tutorial/. Refer to the - README file in that directory for how to use them. To - start the tutorial, do the following: - - + You should be aware that some language features + are extensions to the ANSI standard. + + + + Interactive Monitor + + + In the examples that follow, we assume that you have + created the mydb database as described in the previous + subsection and have started psql. + Examples in this manual can also be found in + /usr/local/pgsql/src/tutorial/. Refer to the + README file in that directory for how to use them. To + start the tutorial, do the following: + + % cd /usr/local/pgsql/src/tutorial % psql -s mydb Welcome to the POSTGRESQL interactive sql monitor: @@ -44,54 +46,55 @@ Welcome to the POSTGRESQL interactive sql monitor: You are currently connected to the database: postgres mydb=> \i basics.sql - - - - - The \i command read in queries from the specified - files. The -s option puts you in single step mode which - pauses before sending a query to the backend. Queries - in this section are in the file basics.sql. - - - -psql -has a variety of \d commands for showing system information. -Consult these commands for more details; -for a listing, type \? at the psql prompt. - - - - -Concepts - - - The fundamental notion in Postgres is that of a class, - which is a named collection of object instances. Each - instance has the same collection of named attributes, - and each attribute is of a specific type. Furthermore, - each instance has a permanent object identifier (OID) - that is unique throughout the installation. Because - SQL syntax refers to tables, we will use the terms - table and class interchangeably. - Likewise, an SQL row is an - instance and SQL columns - are attributes. - As previously discussed, classes are grouped into - databases, and a collection of databases managed by a - single postmaster process constitutes an installation - or site. - - - - -Creating a New Class - - - You can create a new class by specifying the class - name, along with all attribute names and their types: - - + + + + + The \i command read in queries from the specified + files. The -s option puts you in single step mode which + pauses before sending a query to the backend. Queries + in this section are in the file basics.sql. + + + + psql + has a variety of \d commands for showing system information. + Consult these commands for more details; + for a listing, type \? at the psql prompt. + + + + + Concepts + + + The fundamental notion in Postgres is that of a class, + which is a named collection of object instances. Each + instance has the same collection of named attributes, + and each attribute is of a specific type. Furthermore, + each instance has a permanent object identifier + (OID) + that is unique throughout the installation. Because + SQL syntax refers to tables, we will use the terms + table and class interchangeably. + Likewise, an SQL row is an + instance and SQL columns + are attributes. + As previously discussed, classes are grouped into + databases, and a collection of databases managed by a + single postmaster process constitutes an installation + or site. + + + + + Creating a New Class + + + You can create a new class by specifying the class + name, along with all attribute names and their types: + + CREATE TABLE weather ( city varchar(80), temp_lo int, -- low temperature @@ -99,66 +102,82 @@ CREATE TABLE weather ( prcp real, -- precipitation date date ); - - - - - Note that both keywords and identifiers are case-insensitive; identifiers can become -case-sensitive by surrounding them with double-quotes as allowed by SQL92. - 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 - 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 looks exactly like - the command used to create a table in a traditional - relational system. However, we will presently see that - classes have properties that are extensions of the - relational model. - - - - -Populating a Class with Instances - - - The insert statement is used to populate a class with - instances: - - + + + + + Note that both keywords and identifiers are case-insensitive; identifiers can become + case-sensitive by surrounding them with double-quotes as allowed + by SQL92. + 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 + 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 + looks exactly like + the command used to create a table in a traditional + relational system. However, we will presently see that + classes have properties that are extensions of the + relational model. + + + + + Populating a Class with Instances + + + The insert statement is used to populate a class with + instances: + + INSERT INTO weather VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994') - - - - - You can also use the copy command to perform load large - amounts of data from flat (ASCII) files. - - - - -Querying a Class - - - The weather class can be queried with normal relational - selection and projection queries. A SQL 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 - any restrictions). For example, to retrieve all the - rows of weather, type: - + + + + + 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 + transaction directly to or from the target table. An example would be: + + +COPY INTO weather FROM '/home/user/weather.txt' + USING DELIMITERS '|'; + + + 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. + + + + + + + + Querying a Class + + + The weather class can be queried with normal relational + selection and projection queries. A SQL 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 + any restrictions). For example, to retrieve all the + rows of weather, type: + SELECT * FROM WEATHER; - + - and the output should be: - + and the output should be: + +--------------+---------+---------+------+------------+ |city | temp_lo | temp_hi | prcp | date | +--------------+---------+---------+------+------------+ @@ -168,89 +187,91 @@ 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; - - + + - - Arbitrary Boolean operators - (and, or and not) are - allowed in the qualification of any query. For example, + + Arbitrary Boolean operators + (and, or and not) are + allowed in the qualification of any query. For example, - + SELECT * FROM weather WHERE city = 'San Francisco' AND prcp > 0.0; - + +results in: + +--------------+---------+---------+------+------------+ |city | temp_lo | temp_hi | prcp | date | +--------------+---------+---------+------+------------+ |San Francisco | 46 | 50 | 0.25 | 11-27-1994 | +--------------+---------+---------+------+------------+ - - + + - - As a final note, you can specify that the results of a - select can be returned in a sorted order - or with duplicate instances removed. + + As a final note, you can specify that the results of a + select can be returned in a sorted order + or with duplicate instances removed. - + SELECT DISTINCT city FROM weather ORDER BY city; - - - + + + - -Redirecting SELECT Queries + + 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 - class temp with the attribute names and types specified - 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. - - - - -Joins Between Classes - - - Thus far, our queries have only accessed one class at a - time. Queries can access multiple classes at once, or - access the same class in such a way that multiple - instances of the class are being processed at the same - time. A query that accesses multiple instances of the - same or different classes at one time is called a join - query. - As an example, say we wish to find all the records that - are in the temperature range of other records. In - effect, we need to compare the temp_lo and temp_hi - attributes of each EMP instance to the temp_lo and - temp_hi attributes of all other EMP instances. - - -This is only a conceptual model. The actual join may - be performed in a more efficient manner, but this is invisible to the user. - - - - We can do this with the following query: - - + + + + + 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 + then, of course, perform any operations on the resulting + class that we can perform on other classes. + + + + + Joins Between Classes + + + Thus far, our queries have only accessed one class at a + time. Queries can access multiple classes at once, or + access the same class in such a way that multiple + instances of the class are being processed at the same + time. A query that accesses multiple instances of the + same or different classes at one time is called a join + query. + As an example, say we wish to find all the records that + are in the temperature range of other records. In + effect, we need to compare the temp_lo and temp_hi + attributes of each EMP instance to the temp_lo and + temp_hi attributes of all other EMP instances. + + + This is only a conceptual model. The actual join may + be performed in a more efficient manner, but this is invisible to the user. + + + + We can do this with the following query: + + SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high, W2.city, W2.temp_lo AS low, W2.temp_hi AS high FROM weather W1, weather W2 @@ -264,113 +285,135 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high, +--------------+-----+------+---------------+-----+------+ |San Francisco | 37 | 54 | San Francisco | 46 | 50 | +--------------+-----+------+---------------+-----+------+ - - - - -The semantics of such a join are - that the qualification - is a truth expression defined for the Cartesian product of - the classes indicated in the query. For those instances in - the Cartesian product for which the qualification is true, - Postgres computes and returns the values specified in the - target list. Postgres SQL does not assign any meaning to - duplicate values in such expressions. This means that Postgres - 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. - - - - - - 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.) - A query can contain an arbitrary number of - class names and surrogates. - - - - -Updates - - - 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: - - + + + + + The semantics of such a join are + that the qualification + is a truth expression defined for the Cartesian product of + the classes indicated in the query. For those instances in + the Cartesian product for which the qualification is true, + Postgres computes and returns the + values specified in the target list. + Postgres SQL + does not assign any meaning to + duplicate values in such expressions. + This means that Postgres + 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. + + + + + + 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.) + A query can contain an arbitrary number of + class names and surrogates. + + + + + Updates + + + 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: + + UPDATE weather SET temp_hi = temp_hi - 2, temp_lo = temp_lo - 2 WHERE date > '11/28/1994'; - - - + + + - -Deletions + + Deletions - - Deletions are performed using the delete command: - + + Deletions are performed using the delete command: + DELETE FROM weather WHERE city = 'Hayward'; - + - All weather recording belongs to Hayward is removed. - One should be wary of queries of the form - + All weather recording belongs to Hayward is removed. + One should be wary of queries of the form + DELETE FROM classname; - - - 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. - - - - -Using Aggregate Functions - - - Like most other query languages, PostgreSQL supports - aggregate functions. -The current implementation of Postgres aggregate functions have some limitations. - Specifically, while there are aggregates to compute - such functions as the count, sum, - avg (average), max (maximum) and - min (minimum) over a set of instances, aggregates can only - appear in the target list of a query and not directly in the - qualification (the where clause). As an example, - - + + + 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. + + + + + Using Aggregate Functions + + + Like most other query languages, + PostgreSQL supports + aggregate functions. + The current implementation of + Postgres aggregate functions have some limitations. + Specifically, while there are aggregates to compute + such functions as the count, sum, + avg (average), max (maximum) and + min (minimum) over a set of instances, aggregates can only + appear in the target list of a query and not directly in the + qualification (the where clause). As an example, + + SELECT max(temp_lo) FROM weather; - + -is allowed, while + is allowed, while - + SELECT city FROM weather WHERE temp_lo = max(temp_lo); - + -is not. However, as is often the case the query can be restated to accomplish -the intended result; here by using a subselect: - + is not. 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); - - + + - - Aggregates may also have group by clauses: - + + Aggregates may also have group by clauses: + SELECT city, max(temp_lo) FROM weather GROUP BY city; - - - - + + + + + + diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index af6b300455..521dcb9d17 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,93 +1,632 @@ - -Runtime Environment - - -This chapter outlines the interaction between Postgres and -the operating system. - - -Using <Productname>Postgres</Productname> from Unix - - -All Postgres commands that are executed -directly from a Unix shell are -found in the directory .../bin. Including this directory in -your search path will make executing the commands easier. - - -A collection of system catalogs exist at each site. These include a -class (pg_user) that contains an instance for each valid -Postgres user. The instance specifies a set of - Postgres privileges, such as -the ability to act as Postgres super-user, - the ability to create/destroy -databases, and the ability to update the system catalogs. A Unix -user cannot do anything with Postgres -until an appropriate instance is -installed in this class. Further information on the system catalogs -is available by running queries on the appropriate classes. - - - - - -System Layout - - -
-<ProductName>Postgres</ProductName> file layout - -
- - -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/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 - -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 you have 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 must go back and make sure that your -environment is properly set up. - + + Runtime Environment + + + This chapter outlines the interaction between Postgres and + the operating system. + + + + Using <Productname>Postgres</Productname> from Unix + + + All Postgres commands that are executed + directly from a Unix shell are + found in the directory .../bin. Including this directory in + your search path will make executing the commands easier. + + + + A collection of system catalogs exist at each site. These include a + class (pg_user) that contains an instance for each valid + Postgres user. The instance specifies a set of + Postgres privileges, such as + the ability to act as Postgres super-user, + the ability to create/destroy + databases, and the ability to update the system catalogs. A Unix + user cannot do anything with Postgres + until an appropriate instance is + installed in this class. Further information on the system catalogs + is available by running queries on the appropriate classes. + + + + + Starting <Application>postmaster</Application> + + + Nothing can happen to a database unless the + postmaster + process is running. As the site administrator, there + are a number of things you should remember before + starting the postmaster. + These are discussed in the installation and configuration sections + of this manual. + 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 postmaster: + + +% postmaster + + + + + The postmaster occasionally prints out + messages which + are often helpful during troubleshooting. If you wish + to view debugging messages from the postmaster, + you can + start it with the -d option and redirect the output to + the log file: + + +% postmaster -d >& pm.log & + + + If you do not wish to see these messages, you can type + +% postmaster -S + + and the postmaster will be "S"ilent. + Notice that there + is no ampersand ("&") at the end of the last example so + postmaster will be running in the foreground. + + + + + Using pg_options + + + + + Contributed by Massimo Dal Zotto + + + + + The optional file data/pg_options contains runtime + options used by the backend to control trace messages and other backend + tunable parameters. + The file is re-read by a backend + when it receives a SIGHUP signal, making thus possible to change run-time + options on the fly without needing to restart + Postgres. + The options specified in this file may be debugging flags used by the trace + package (backend/utils/misc/trace.c) or numeric + parameters which can be used by the backend to control its behaviour. + + + + All pg_options are initialized to zero at backend startup. + New or modified options will be read by all new backends when they are started. + To make effective any changes for all running backends we need to send a + SIGHUP to the postmaster. The signal will be automatically sent to all the + backends. We can also activate the changes only for a specific backend by + sending the SIGHUP directly to it. + + + pg_options can also be specified with the switch of + Postgres: + + +postgres options -T "verbose=2,query,hostlookup-" + + + + + The functions used for printing errors and debug messages can now make use + of the syslog(2) facility. Message printed to stdout + or stderr are prefixed by a timestamp containing also the backend pid: + + +#timestamp #pid #message +980127.17:52:14.173 [29271] StartTransactionCommand +980127.17:52:14.174 [29271] ProcessUtility: drop table t; +980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full +980127.17:52:14.186 [29286] Async_NotifyHandler +980127.17:52:14.186 [29286] Waking up sleeping backend process +980127.19:52:14.292 [29286] Async_NotifyFrontEnd +980127.19:52:14.413 [29286] Async_NotifyFrontEnd done +980127.19:52:14.466 [29286] Async_NotifyHandler done + + + + This format improves readability of the logs and allows people to understand + exactly which backend is doing what and at which time. It also makes + easier to write simple awk or perl scripts which monitor the log to + detect database errors or problem, or to compute transaction time statistics. + + + Messages printed to syslog use the log facility LOG_LOCAL0. + The use of syslog can be controlled with the syslog pg_option. + Unfortunately many functions call directly printf() + to print their messages to stdout or stderr and this output can't be + redirected to syslog or have timestamps in it. + It would be advisable that all calls to printf would be replaced with the + PRINTF macro and output to stderr be changed to use EPRINTF instead so that + we can control all output in a uniform way. + + + + The format of the pg_options file is as follows: + + +# comment +option=integer_value # set value for option +option # set option = 1 +option+ # set option = 1 +option- # set option = 0 + + + Note that keyword can also be + an abbreviation of the option name defined in + backend/utils/misc/trace.c. + + + pg_options File + + + For example my pg_options file contains the following values: + + +verbose=2 +query +hostlookup +showportnumber + + + + + + + Recognized Options + + + The options currently defined are: + + + + + all + + + + Global trace flag. Allowed values are: + + + + + + 0 + + + + Trace messages enabled individually + + + + + + + 1 + + + + Enable all trace messages + + + + + + + -1 + + + + Disable all trace messages + + + + + + + + + + + verbose + + + + Verbosity flag. Allowed values are: + + + + + + 0 + + + + No messages. This is the default. + + + + + + + 1 + + + + Print information messages. + + + + + + + 2 + + + + Print more information messages. + + + + + + + + + + + query + + + + Query trace flag. Allowed values are: + + + + + + 0 + + + + Don't print query. + + + + + + + 1 + + + + Print a condensed query in one line. + + + + + + + 4 + + + + Print the full query. + + + + + + + + + + + plan + + + + Print query plan. + + + + + + + parse + + + + Print parser output. + + + + + + + rewritten + + + + Print rewritten query. + + + + + + + parserstats + + + + Print parser statistics. + + + + + + + plannerstats + + + + Print planner statistics. + + + + + + + executorstats + + + + Print executor statistics. + + + + + + + shortlocks + + + + Currently unused but needed to enable features in the future. + + + + + + + locks + + + + Trace locks. + + + + + + + userlocks + + + + Trace user locks. + + + + + + + spinlocks + + + + Trace spin locks. + + + + + + + notify + + + + Trace notify functions. + + + + + + + malloc + + + + Currently unused. + + + + + + + palloc + + + + Currently unused. + + + + + + + lock_debug_oidmin + + + + Minimum relation oid traced by locks. + + + + + + + lock_debug_relid + + + + oid, if not zero, of relation traced by locks. + + + + + + + lock_read_priority + + + + Currently unused. + + + + + + + deadlock_timeout + + + + Deadlock check timer. + + + + + + + syslog + + + + syslog flag. Allowed values are: + + + + + + 0 + + + + Messages to stdout/stderr. + + + + + + + 1 + + + + Messages to stdout/stderr and syslog. + + + + + + + 2 + + + + Messages only to syslog. + + + + + + + + + + + hostlookup + + + + Enable hostname lookup in ps_status. + + + + + + + showportnumber + + + + Show port number in ps_status. + + + + + + + notifyunlock + + + + Unlock of pg_listener after notify. + + + + + + + notifyhack + + + + Remove duplicate tuples from pg_listener. + + + + + + + + + + diff --git a/doc/src/sgml/security.sgml b/doc/src/sgml/security.sgml index 4980c12cf7..1539f98717 100644 --- a/doc/src/sgml/security.sgml +++ b/doc/src/sgml/security.sgml @@ -183,6 +183,9 @@ two exceptions: manual system catalog updates are not permitted if the user does not have pg_user.usecatupd set, and destruction of system catalogs (or modification of their schemas) is never allowed. + + + diff --git a/doc/src/sgml/sql.sgml b/doc/src/sgml/sql.sgml index 9d146409bf..47d7febad5 100644 --- a/doc/src/sgml/sql.sgml +++ b/doc/src/sgml/sql.sgml @@ -288,7 +288,7 @@ attributes are taken from. We often write a relation scheme as Di, for each attribute Ai, - 1 ≤ i ≤ k, + 1 <&equal; i <&equal; k, where the values of the attributes are taken from. We often write a relation scheme as R(A1, @@ -325,10 +325,12 @@ attributes are taken from. We often write a relation scheme as integers. We define this by assigning a data type to each attribute. The type of SNAME will be VARCHAR(20) (this is the SQL type - for character strings of length ≤ 20), the type of SNO will be + for character strings of length <&equal; 20), + the type of SNO will be INTEGER. With the assignment of a data type we also have selected a domain for an attribute. The domain of SNAME is the set of all - character strings of length ≤ 20, the domain of SNO is the set of + character strings of length <&equal; 20, + the domain of SNO is the set of all integer numbers. @@ -339,7 +341,7 @@ attributes are taken from. We often write a relation scheme as Model - In section + In we defined the mathematical notion of the relational model. Now we know how the data can be stored using a relational data model but we do not know what to do with all these @@ -481,19 +483,23 @@ attributes are taken from. We often write a relation scheme as projecting out the duplicate column. - - Let's have a look at the tables that are produced by evaluating the steps - necessary for a join. - Let the following two tables be given: + + An Inner Join - + + Let's have a look at the tables that are produced by evaluating the steps + necessary for a join. + Let the following two tables be given: + + R A | B | C S C | D | E ---+---+--- ---+---+--- 1 | 2 | 3 3 | a | b 4 | 5 | 6 6 | c | d 7 | 8 | 9 - - + + + First we calculate the Cartesian product diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml index f0fdeb28c6..2f35e49504 100644 --- a/doc/src/sgml/start-ag.sgml +++ b/doc/src/sgml/start-ag.sgml @@ -4,251 +4,194 @@ - - thomas 1998-02-24 --> - -Starting <Application>postmaster</Application> - - - Nothing can happen to a database unless the - postmaster - process is running. As the site administrator, there - are a number of things you should remember before - starting the postmaster. -These are discussed in the installation and configuration sections -of this manual. - 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 postmaster: - -% postmaster - - The postmaster occasionally prints out -messages which - are often helpful during troubleshooting. If you wish - to view debugging messages from the postmaster, -you can - start it with the -d option and redirect the output to - the log file: - -% postmaster -d >& pm.log & - - If you do not wish to see these messages, you can type - -% postmaster -S - - and the postmaster will be "S"ilent. -Notice that there - is no ampersand ("&") at the end of the last example. - - - - -Adding and Deleting Users - - - createuser enables specific users to access - Postgres. -destroyuser removes users and - prevents them from accessing Postgres. -Note that these - commands only affect users with respect to -Postgres; - they have no effect on users other privileges or status with regards -to the underlying - operating system. - - - - -Disk Management - - - - - -Alternate Locations - - -It is possible to create a database in a location other than the default -location for the installation. Remember that all database access actually -occurs through the database backend, so that any location specified must -be accessible by the backend. - - - Alternate database locations are created and referenced by an environment variable - which gives the absolute path to the intended storage location. -This environment variable must have been defined before the backend was started -and must be writable by the postgres administrator account. -Any valid environment variable name may be used to reference an alternate -location, although using variable name with a prefix of PGDATA is recommended -to avoid confusion and conflict with other variables. - - - - In previous versions of Postgres, -it was also permissable to use an absolute path name to specify an alternate storage location. -The environment variable style of specification -is to be preferred since it allows the site administrator more flexibility in -managing disk storage. -If you prefer using absolute paths, you may do so by defining -"ALLOW_ABSOLUTE_DBPATHS" and recompiling Postgres - To do this, either add this line - + + Adding and Deleting Users + + + createuser enables specific users to access + Postgres. + destroyuser removes users and + prevents them from accessing Postgres. + Note that these + commands only affect users with respect to + Postgres; + they have no effect on users other privileges or status with regards + to the underlying + operating system. + + + + + Disk Management + + + Alternate Locations + + + It is possible to create a database in a location other than the default + location for the installation. Remember that all database access actually + occurs through the database backend, so that any location specified must + be accessible by the backend. + + + + Alternate database locations are created and referenced by an environment variable + which gives the absolute path to the intended storage location. + This environment variable must have been defined before the backend was started + and must be writable by the postgres administrator account. + Any valid environment variable name may be used to reference an alternate + location, although using variable name with a prefix of PGDATA is recommended + to avoid confusion and conflict with other variables. + + + + + In previous versions of Postgres, + it was also permissable to use an absolute path name + to specify an alternate storage location. + The environment variable style of specification + is to be preferred since it allows the site administrator more flexibility in + managing disk storage. + If you prefer using absolute paths, you may do so by defining + "ALLOW_ABSOLUTE_DBPATHS" and recompiling Postgres + To do this, either add this line + + #define ALLOW_ABSOLUTE_DBPATHS 1 - -to the file src/include/config.h, or by specifying - + + + to the file src/include/config.h, or by specifying + + CFLAGS+= -DALLOW_ABSOLUTE_DBPATHS - -in your Makefile.custom. - - - - -Remember that database creation is actually performed by the database backend. -Therefore, any environment variable specifying an alternate location must have -been defined before the backend was started. To define an alternate location -PGDATA2 pointing to /home/postgres/data, first type - + + + in your Makefile.custom. + + + + + Remember that database creation is actually performed by the database backend. + Therefore, any environment variable specifying an alternate location must have + been defined before the backend was started. To define an alternate location + PGDATA2 pointing to /home/postgres/data, first type + + % setenv PGDATA2 /home/postgres/data - -to define the environment variable to be used with subsequent commands. -Usually, you will want to define this variable in the -Postgres superuser's -.profile -or -.cshrc -initialization file to ensure that it is defined upon system startup. -Any environment variable can be used to reference alternate location, -although it is preferred that the variables be prefixed with "PGDATA" -to eliminate confusion and the possibility of conflicting with or -overwriting other variables. - - -To create a data storage area in PGDATA2, ensure -that /home/postgres already exists and is writable -by the postgres administrator. -Then from the command line, type - + + + to define the environment variable to be used with subsequent commands. + Usually, you will want to define this variable in the + Postgres superuser's + .profile + or + .cshrc + initialization file to ensure that it is defined upon system startup. + Any environment variable can be used to reference alternate location, + although it is preferred that the variables be prefixed with "PGDATA" + to eliminate confusion and the possibility of conflicting with or + overwriting other variables. + + + + To create a data storage area in PGDATA2, ensure + that /home/postgres already exists and is writable + by the postgres administrator. + Then from the command line, type + + % setenv PGDATA2 /home/postgres/data % initlocation $PGDATA2 Creating Postgres database system directory /home/postgres/data Creating Postgres database system directory /home/postgres/data/base - - - -To test the new location, create a database test by typing - + + + + + To test the new location, create a database test by typing + + % createdb -D PGDATA2 test % destroydb test - - - - - - -Troubleshooting - - - 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): - -connectDB() failed: Is the postmaster running at 'localhost' on port '5432'? - - it is usually because either 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. - - - - -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. - - - -Creating a Database - - - Let's say you want to create a database named mydb. - You can do this with the following command: - + + + + + + + + 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. + + + + Creating a Database + + + Let's say you want to create a database named mydb. + You can do this with the following command: + + % createdb mydb - - - 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. - - - - -Accessing a Database - - - Once you have constructed a database, you can access it - by: - - - - -running the Postgres terminal monitor program -(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 - 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 - database by typing the command: - + + + 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. + + + + + Accessing a Database + + + Once you have constructed a database, you can access it + by: + + + + + running the Postgres terminal monitor program + (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 + 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 + database by typing the command: + + % psql mydb - + - You will be greeted with the following message: - + You will be greeted with the following message: + Welcome to the Postgres interactive sql monitor: type \? for help on slash commands @@ -257,70 +200,94 @@ Welcome to the Postgres interactive sql monitor: You are currently connected to the database: mydb mydb=> - - - - -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 - can get help on the syntax of various -Postgres SQL commands by typing: - + + + + + 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 + can get help on the syntax of various + 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: - + Once you have finished entering your queries into the + workspace, you can pass the contents of the workspace + 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 backslash-g is not - necessary. psql will automatically -process semicolon terminated queries. - To read queries from a file, say myFile, instead of - entering them interactively, type: - + + + This tells the server to process the query. If you + terminate your query with a semicolon, the backslash-g is not + necessary. 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 backslash-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 - line is ignored. Multiple-line comments, and comments within a line, - are denoted by /* ... */ - - + + + and psql will quit and return + you to your command + shell. (For more escape codes, type backslash-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 two dashes + (--). Everything after the dashes up to the end of the + line is ignored. Multiple-line comments, and comments within a line, + are denoted by /* ... */, a convention borrowed + from Ingres. + + - -Destroying a Database + + Destroying a Database - - If you are the database administrator for the database - mydb, you can destroy it using the following UNIX command: - + + If you are the database administrator for the database + mydb, you can destroy it using the following UNIX command: + + % destroydb 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. - - - - + + + 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. + + + + + + diff --git a/doc/src/sgml/trouble.sgml b/doc/src/sgml/trouble.sgml new file mode 100644 index 0000000000..a1b100180b --- /dev/null +++ b/doc/src/sgml/trouble.sgml @@ -0,0 +1,166 @@ + + Troubleshooting + + + Client Connections + + If you get the following error message from a + Postgres + command (such as psql or + createdb): + + +connectDB() failed: Is the postmaster running at 'localhost' on port '5432'? + + + it is usually because either 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. + + + + + Debugging Messages + + + The postmaster occasionally prints out + messages which + are often helpful during troubleshooting. If you wish + to view debugging messages from the postmaster, + you can + start it with the -d option and redirect the output to + the log file: + + +% postmaster -d >& pm.log & + + + If you do not wish to see these messages, you can type + +% postmaster -S + + and the postmaster will be "S"ilent. + Notice that there + is no ampersand ("&") at the end of the last example so + postmaster will be running in the foreground. + + + + pg_options + + + + + Contributed by Massimo Dal Zotto + + + + + The optional file data/pg_options contains runtime + options used by the backend to control trace messages and other backend + tunable parameters. + What makes this file interesting is the fact that it is re-read by a backend + when it receives a SIGHUP signal, making thus possible to change run-time + options on the fly without needing to restart + Postgres. + The options specified in this file may be debugging flags used by the trace + package (backend/utils/misc/trace.c) or numeric + parameters which can be used by the backend to control its behaviour. + New options and parameters must be defined in + backend/utils/misc/trace.c and + backend/include/utils/trace.h. + + + + pg_options can also be specified with the switch of + Postgres: + + +postgres options -T "verbose=2,query,hostlookup-" + + + + + The functions used for printing errors and debug messages can now make use + of the syslog(2) facility. Message printed to stdout + or stderr are prefixed by a timestamp containing also the backend pid: + + +#timestamp #pid #message +980127.17:52:14.173 [29271] StartTransactionCommand +980127.17:52:14.174 [29271] ProcessUtility: drop table t; +980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full +980127.17:52:14.186 [29286] Async_NotifyHandler +980127.17:52:14.186 [29286] Waking up sleeping backend process +980127.19:52:14.292 [29286] Async_NotifyFrontEnd +980127.19:52:14.413 [29286] Async_NotifyFrontEnd done +980127.19:52:14.466 [29286] Async_NotifyHandler done + + + + + This format improves readability of the logs and allows people to understand + exactly which backend is doing what and at which time. It also makes + easier to write simple awk or perl scripts which monitor the log to + detect database errors or problem, or to compute transaction time statistics. + + + + Messages printed to syslog use the log facility LOG_LOCAL0. + The use of syslog can be controlled with the syslog pg_option. + Unfortunately many functions call directly printf() + to print their messages to stdout or stderr and this output can't be + redirected to syslog or have timestamps in it. + It would be advisable that all calls to printf would be replaced with the + PRINTF macro and output to stderr be changed to use EPRINTF instead so that + we can control all output in a uniform way. + + + + The format of the pg_options file is as follows: + + +# comment +option=integer_value # set value for option +option # set option = 1 +option+ # set option = 1 +option- # set option = 0 + + + Note that keyword can also be + an abbreviation of the option name defined in + backend/utils/misc/trace.c. + + + + Refer to + for a complete list of option keywords and possible values. + + + + + + diff --git a/doc/src/sgml/tutorial.sgml b/doc/src/sgml/tutorial.sgml index 3cedf0aefa..f51b94192a 100644 --- a/doc/src/sgml/tutorial.sgml +++ b/doc/src/sgml/tutorial.sgml @@ -24,23 +24,23 @@ -PostgreSQL Tutorial - - Covering v6.3 for general release - - - The PostgreSQL Development Team - + PostgreSQL Tutorial + + Covering v6.5 for general release + + + The PostgreSQL Development Team + - - Thomas - Lockhart - - Caltech/JPL - - + + Thomas + Lockhart + + Caltech/JPL + + @@ -49,16 +49,17 @@ TGL --> - (last updated 1998-02-23) - + (last updated 1999-05-19) + - - -PostgreSQL is copyright (C) 1998 by the Postgres Global Development Group. - - + + + PostgreSQL is copyright (©) 1998-9 + by the Postgres Global Development Group. + + - + - -Summary - - -Postgres, - developed originally in the UC Berkeley Computer Science Department, - pioneered many of the object-relational concepts - now becoming available in some commercial databases. -It provides SQL92/SQL3 language support, - transaction integrity, and type extensibility. - PostgreSQL is a public-domain, open source descendant - of this original Berkeley code. - - - -&intro; -&arch; -&start; -&query; -&advanced; - -&biblio; + + Summary + + + Postgres, + developed originally in the UC Berkeley Computer Science Department, + pioneered many of the object-relational concepts + now becoming available in some commercial databases. + It provides SQL92/SQL3 language support, + transaction integrity, and type extensibility. + PostgreSQL is a public-domain, open source descendant + of this original Berkeley code. + + + + &intro; + &arch; + &start; + &query; + &advanced; + + &biblio; + + diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index 87278c7cd5..ae5dd13c1c 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,11 +1,19 @@ -PostgreSQL User's Guide - - Covering v6.4 for general release - - - The PostgreSQL Development Team - + PostgreSQL User's Guide + + Covering v6.5 for general release + + + The PostgreSQL Development Team + - - Thomas - Lockhart - - Caltech/JPL - - + + Thomas + Lockhart + + Caltech/JPL + + - (last updated 1998-02-23) - + (last updated 1999-05-19) + - - -PostgreSQL is copyright (C) 1998 -by the Postgres Global Development Group. - - + + + PostgreSQL is copyright (©) 1998-9 + by the Postgres Global Development Group. + + - + - -Summary - - -Postgres, - developed originally in the UC Berkeley Computer Science Department, - pioneered many of the object-relational concepts - now becoming available in some commercial databases. -It provides SQL92/SQL3 language support, - transaction integrity, and type extensibility. - PostgreSQL is a public-domain, open source descendant - of this original Berkeley code. - - - - &intro; + + Summary + + + Postgres, + developed originally in the UC Berkeley Computer Science Department, + pioneered many of the object-relational concepts + now becoming available in some commercial databases. + It provides SQL92/SQL3 language support, + transaction integrity, and type extensibility. + PostgreSQL is a public-domain, open source descendant + of this original Berkeley code. + + + + &intro; &sql; - &environ; - &manage; &syntax; - &datatype; - &oper; - &func; - &typeconv; + &datatype; + &oper; + &func; + &typeconv; &keys; - &array; - &inherit; - &query-ug; - &storage; - &psql; - &pgaccess; - &commands; - - + &array; + &inherit; + &environ; + &manage; + &storage; + &commands; + + &biblio;