Postgres Architectural Concepts
- Before we continue, you should understand the basic
+ Before we begin, you should understand the basic
Postgres system architecture. Understanding how the
parts of Postgres interact will make the next chapter
somewhat clearer.
@@ -16,7 +16,7 @@
- A supervisory daemon process (postmaster),
+ A supervisory daemon process (the postmaster),
@@ -26,7 +26,7 @@
- the one or more backend database servers (the postgres process itself).
+ one or more backend database servers (the postgres process itself).
@@ -34,9 +34,10 @@
A single postmaster manages a given collection of
databases on a single host. Such a collection of
- databases is called a cluster (of databases). Frontend
- applications that wish to access a given database
- within a cluster make calls to the library.
+ databases is called a cluster (of databases). A frontend
+ application that wishes to access a given database
+ within a cluster makes calls to an interface library (eg, libpq)
+ that is linked into the application.
The library sends user requests over the network to the
postmaster
((a)),
@@ -58,30 +59,39 @@ which in turn starts a new backend server process
From that point on, the frontend process and the backend
server communicate without intervention by the
postmaster. Hence, the postmaster is always running, waiting
- for requests, whereas frontend and backend processes
+ for connection requests, whereas frontend and backend processes
come and go. The libpq library allows a single
frontend to make multiple connections to backend processes.
- However, the frontend application is still a
- single-threaded process. Multithreaded frontend/backend
- connections are not currently supported in libpq.
+ However, each backend process is a single-threaded process that can
+ only execute one query at a time; so the communication over any one
+ frontend-to-backend connection is single-threaded.
+
+
+
One implication of this architecture is that the
- postmaster and the backend always run on the same
- machine (the database server), while the frontend
+ postmaster and the backend always run on the
+ same machine (the database server), while the frontend
application may run anywhere. You should keep this
in mind,
because the files that can be accessed on a client
machine may not be accessible (or may only be accessed
- using a different file name) on the database server
+ using a different path name) on the database server
machine.
+
+
+
You should also be aware that the postmaster and
postgres servers run with the user-id of the Postgres
- "superuser."
+ superuser>.
Note that the Postgres superuser does not
-have to be a special user (e.g., a user named
+have to be any particular user (e.g., a user named
postgres), although many systems are installed that way.
Furthermore, the Postgres superuser should
- definitely not be the Unix superuser, root! In any
- case, all files relating to a database should belong to
+definitely not be the Unix superuser, root!
+It is safest if the Postgres superuser is an
+ordinary, unprivileged user so far as the surrounding Unix system is
+concerned.
+ In any case, all files relating to a database should belong to
this Postgres superuser.
diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index a6ea373d2a..4bda19f3e2 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -1,4 +1,4 @@
-
+
Arrays
@@ -19,6 +19,8 @@ CREATE TABLE sal_emp (
schedule text[][]
);
+ As shown, an array data type is named by appending square brackets
+ ([ ]>) to the data type name of the array elements.
The above query will create a table named
sal_emp with a text string
(name), a one-dimensional array of type
@@ -31,7 +33,7 @@ CREATE TABLE sal_emp (
Now we do some INSERTs. Observe that to write an array
- value, we enclose the element values within braces and separate them
+ value, we enclose the element values within curly braces and separate them
by commas. If you know C, this is not unlike the syntax for
initializing structures.
@@ -63,6 +65,7 @@ SELECT name FROM sal_emp WHERE pay_by_quarter[1] <> pay_by_quarter[2];
(1 row)
+ The array subscript numbers are written within square brackets.
Postgres uses the
one-based numbering convention for arrays, that is,
an array of n elements starts with array[1] and
@@ -163,7 +166,7 @@ CREATE TABLE tictactoe (
Actually, the current implementation does not enforce the declared
- number of dimensions either. Arrays of a particular base type are
+ number of dimensions either. Arrays of a particular element type are
all considered to be of the same type, regardless of size or number
of dimensions.
@@ -236,4 +239,13 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000;
+
+
+ A limitation of the present array implementation is that individual
+ elements of an array cannot be SQL NULLs. The entire array can be set
+ to NULL, but you can't have an array with some elements NULL and some
+ not. Fixing this is on the TODO list.
+
+
+
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 26abb0bd3f..37ee4ff8cf 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -1,4 +1,4 @@
-
+
Localization>
@@ -176,11 +176,11 @@ export LANG=sv_SE
for any particular database cluster, or indexes on text columns will
become corrupt. Postgres enforces this
by recording the values of LC_COLLATE> and LC_CTYPE>
- that are seen by initdb>. The server automatically adopts
+ that are seen by initdb>. The server automatically adopts
those two values when it is started; only the other LC_>
categories can be set from the environment at server startup.
In short, only one collation order can be used in a database cluster,
- and it is chosen at initdb> time.
+ and it is chosen at initdb> time.
@@ -256,6 +256,18 @@ perl: warning: Falling back to the standard locale ("C").
man page of your system if you are not sure.
+
+ Check that PostgreSQL> is actually using the locale that
+ you think it is. LC_COLLATE> and LC_CTYPE> settings are
+ determined at initdb> time and cannot be changed without
+ repeating initdb>. Other locale settings including
+ LC_MESSAGES> and LC_MONETARY> are determined by the
+ environment the postmaster is started in, and can be changed with a simple
+ postmaster restart. You can check the LC_COLLATE> and
+ LC_CTYPE> settings of
+ a database with the contrib/pg_controldata> utility program.
+
+
The directory src/test/locale> contains a test suite
for PostgreSQL>'s locale support.
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index e7dbc60134..90bb9911fd 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,4 +1,4 @@
-
+
Client Authentication
@@ -541,14 +541,34 @@ local all md5 admins
In order to use Kerberos>, support for it must be
enabled at build time. Both Kerberos 4 and 5 are supported
(./configure --with-krb4> or ./configure
- --with-krb5> respectively).
+ --with-krb5> respectively), although only one version can be
+ supported in any one build.
- Postgres> should operate like a normal Kerberos
- service. The name of the service principal is normally
- postgres, unless it was changed during the
- build. Make sure that your server key file is readable (and
+ Postgres> operates like a normal Kerberos service.
+ The name of the service principal is
+ servicename/hostname@realm>, where
+ servicename> is postgres
+ (unless a different service name was selected at configure time
+ with ./configure --with-krb-srvnam=whatever>).
+ hostname> is the fully qualified domain name of the server
+ machine. The service principal's realm is the preferred realm of the
+ server machine.
+
+
+
+ Client principals must have their Postgres> username as
+ their first component, for example
+ pgusername/otherstuff@realm>.
+ At present the realm of the client is not checked by
+ Postgres>; so
+ if you have cross-realm authentication enabled, then any principal
+ in any realm that can communicate with yours will be accepted.
+
+
+
+ Make sure that your server key file is readable (and
preferably only readable) by the Postgres server account (see
). The location of the key file
is specified with the krb_server_keyfile> run time
@@ -569,49 +589,12 @@ local all md5 admins
- In the Kerberos> 5 hooks, the following assumptions
- are made about user and service naming:
-
-
-
-
- User principal names (anames) are assumed to contain the actual
- Unix/Postgres> user name in the first component.
-
-
-
-
- The Postgres> service is assumed to be have two
- components, the service name and a host name, canonicalized as
- in Version 4 (i.e., with all domain suffixes removed).
-
-
-
-
-
-
-
-
- Parameter>
- Example>
-
-
-
-
- user>
- frew@S2K.ORG>
-
-
- user>
- aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG>
-
-
- host>
- postgres_dbms/ucbvax@S2K.ORG>
-
-
-
-
+ When connecting to the database make sure you have a ticket for a
+ principal matching the requested database username.
+ An example: For database username fred>, both principal
+ fred@EXAMPLE.COM> and
+ fred/users.example.com@EXAMPLE.COM> can be
+ used to authenticate to the database server.
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 5a9e927745..a8f5d7e20f 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
@@ -382,7 +382,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.69 2001/11/12 21:04:45 tg
bigint>8 bytesVery large range fixed-precision
- about 18 decimal digits
+ -9223372036854775807 to 9223372036854775807
@@ -1538,22 +1538,29 @@ January 8 04:05:06 1999 PST
- intervals can be specified with the following syntax:
+ interval values can be written with the following syntax:
Quantity Unit [Quantity Unit...] [Direction]
-@ Quantity Unit [Direction]
+@ Quantity Unit [Quantity Unit...] [Direction]
- where: Quantity is ..., -1,
- 0, 1, 2, ...;
+ where: Quantity is an integer (possibly signed);
Unit is second,
minute, hour, day,
week, month, year,
decade, century, millennium,
or abbreviations or plurals of these units;
Direction can be ago or
- empty.
+ empty. The at sign (@>) is optional noise. The amounts
+ of different quantities are implicitly added up with appropriate
+ sign accounting.
+
+
+
+ Quantities of days, hours, minutes, and seconds can be specified without
+ explicit unit markings: for example, '1 12:59:10'> is read
+ the same as '1 day 12 hours 59 min 10 sec'>.
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index b1c9503705..7407841d6c 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
@@ -825,7 +825,7 @@ Postgres documentation
- char_length(string) or character_length(string)
+ char_length(string) or character_length(string)integer
length of string
@@ -981,6 +981,25 @@ Postgres documentation
Hi Thomas
+
+ length(string)
+ integer
+
+ length of string
+
+ character strings
+ length
+
+
+ length
+ character strings
+ character strings, length
+
+
+ length('jose')>
+ 4>
+
+
lpad(stringtext,
@@ -4084,6 +4103,32 @@ SELECT NULLIF(value, '(none)') ...
TRIGGER>. (Case of the string is not significant, however.)
+
+ System Information Functions>
+
+
+ Name> Return Type> Description>
+
+
+
+
+ version>
+ text>
+ PostgreSQL version information>
+
+
+
+
+
+
+ version
+
+
+
+ version()> returns a string describing the PostgreSQL
+ server's version.
+
+
diff --git a/doc/src/sgml/inherit.sgml b/doc/src/sgml/inherit.sgml
index 403710cffb..66d6be0c19 100644
--- a/doc/src/sgml/inherit.sgml
+++ b/doc/src/sgml/inherit.sgml
@@ -1,5 +1,5 @@
@@ -171,6 +171,16 @@ SET SQL_Inheritance TO OFF;
or add a line in your postgresql.conf file.
+
+
+ A limitation of the inheritance feature is that indexes (including
+ unique constraints) and foreign key constraints only apply to single
+ tables, not to their inheritance children. Thus, in the above example,
+ specifying that another table's column REFERENCES cities(name)>
+ would allow the other table to contain city names but not capital names.
+ This deficiency will probably be fixed in some future release.
+
+
+
PostgreSQL>]]>
@@ -162,7 +162,8 @@ su - postgres
Getting The Source
- The PostgreSQL> &version; sources can by obtained from PostgreSQL> &version; sources can be obtained by
+ anonymous FTP from .
Use a mirror if possible. Then unpack it:
@@ -904,6 +905,7 @@ All of PostgreSQL is successfully made. Ready to install.
gmake check
+ (This won't work as root; do it as an unprivileged user.)
It is possible that some tests fail, due to differences in error
message wording or floating point results.
~/.bash_profile> (or
/etc/profile>, if you want it to affect every user):
-PATH=$PATH:/usr/local/pgsql/bin
+PATH=/usr/local/pgsql/bin:$PATH
If you are using csh> or tcsh>, then use this command:
@@ -1137,7 +1139,7 @@ set path = ( /usr/local/pgsql/bin $path )
documentation, you need to add a line like the following to a
shell start-up file:
-MANPATH=$MANPATH:/usr/local/pgsql/man
+MANPATH=/usr/local/pgsql/man:$MANPATH
diff --git a/doc/src/sgml/libpq++.sgml b/doc/src/sgml/libpq++.sgml
index 8a5f153e2a..aabdcd4fc7 100644
--- a/doc/src/sgml/libpq++.sgml
+++ b/doc/src/sgml/libpq++.sgml
@@ -1,5 +1,5 @@
@@ -217,6 +217,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.33 2001/10/12 23:32:
PgConnection::PgConnection(const char *conninfo)
+ The conninfo> string is the same as for the underlying
+ libpq PQconnectdb> function.
+
Although typically called from one of the access classes, a connection to
a backend server is possible by creating a PgConnection> object.
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 4a191e99b4..603ad714ff 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
@@ -78,11 +78,12 @@ PGconn *PQconnectdb(const char *conninfo)
Each parameter setting is in the form keyword = value.
- (To write a null value or a value containing
+ (To write an empty value or a value containing
spaces, surround it with single quotes, e.g.,
keyword = 'a value'.
- Single quotes within the value must be written as \'.
- Spaces around the equal sign are optional.) The currently recognized
+ Single quotes and backslashes within the value must be escaped with a
+ backslash, e.g., \' or \\.)
+ Spaces around the equal sign are optional. The currently recognized
parameter keywords are:
diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml
index 9304992176..dabfbefac9 100644
--- a/doc/src/sgml/manage.sgml
+++ b/doc/src/sgml/manage.sgml
@@ -1,5 +1,5 @@
@@ -90,32 +90,37 @@ ERROR: CREATE DATABASE: Permission denied.
Once you have constructed a database, you can access it
by:
-
-
-
-running the PostgreSQL interactive terminal
-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.
-
-
-
-
-writing a program in other languages for which there are available interface
-libraries.
-
-
-
+
+
+
+ Running the PostgreSQL interactive
+ terminal program, called psql, which allows you
+ to interactively enter, edit, and execute
+ SQL commands.
+
+
-You might want to start up psql,
+
+
+ Using an existing graphical frontend tool like
+ PgAccess or
+ ApplixWare (via
+ ODBC) to create and manipulate a database.
+ These possibilities are not covered in this tutorial.
+
+
+
+
+
+ Writing a custom application, using one of the several
+ available language bindings. These possibilities are discussed
+ further in The PostgreSQL Programmer's
+ Guide.
+
+
+
+
+You probably 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:
@@ -164,7 +169,7 @@ mydb=> \g
To read queries from a file, say myFile, instead of
entering them interactively, type:
-mydb=> \i fileName
+mydb=> \i myFile
To get out of psql and return to Unix, type
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 4f3f42a027..e3c7caddc2 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -1,5 +1,5 @@
@@ -463,7 +463,7 @@ spi_exec -array C "SELECT * FROM pg_class" {
- spi_exec> ?-count n? ?-arrayname? ?-nullsstring? queryid ?value-list? ?loop-body?
+ spi_execp> ?-count n? ?-arrayname? ?-nullsstring? queryid ?value-list? ?loop-body?
Execute a prepared plan from spi_prepare> with variable substitution.
diff --git a/doc/src/sgml/pygresql.sgml b/doc/src/sgml/pygresql.sgml
index 4d8a28813d..b5dbf71c8a 100644
--- a/doc/src/sgml/pygresql.sgml
+++ b/doc/src/sgml/pygresql.sgml
@@ -1,4 +1,4 @@
-
+
PyGreSQL - Python Interface
@@ -2671,11 +2671,13 @@ get_attnames(table)
- list
+ dictionary
- List of attribute names.
+ The dictionary's keys are
+ the attribute names, the values are the type names of
+ the attributes.
@@ -2687,7 +2689,8 @@ get_attnames(table)
Description
- Given the name of a table, digs out the list of attribute names.
+ Given the name of a table, digs out the set of attribute names
+ and types.
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 0cbbfc12d1..d894a0f7db 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -1,4 +1,4 @@
-
+
Queries
@@ -910,15 +910,21 @@ SELECT a AS b FROM table1 ORDER BY a;
SELECT select_list
FROM table_expression
- ORDER BY sort_specLIMIT { number | ALL }OFFSET number
LIMIT allows you to retrieve just a portion of the rows that are
generated by the rest of the query. If a limit count is given, no
- more than that many rows will be returned. If an offset is given,
- that many rows will be skipped before starting to return rows.
+ more than that many rows will be returned.
+ LIMIT ALL is the same as omitting a LIMIT clause.
+
+
+
+ OFFSET says to skip that many rows before beginning to return rows
+ to the client. OFFSET 0 is the same as omitting an OFFSET clause.
+ If both OFFSET and LIMIT appear, then OFFSET rows are skipped before
+ starting to count the LIMIT rows that are returned.
diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml
index 35701b0aec..d6e2905a49 100644
--- a/doc/src/sgml/ref/create_trigger.sgml
+++ b/doc/src/sgml/ref/create_trigger.sgml
@@ -1,5 +1,5 @@
@@ -44,7 +44,7 @@ CREATE TRIGGER name { BEFORE | AFTE
name
- The name of an existing trigger.
+ The name to give the new trigger.
@@ -52,7 +52,7 @@ CREATE TRIGGER name { BEFORE | AFTE
table
- The name of a table.
+ The name of an existing table.
diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml
index ec95044426..6e92205eef 100644
--- a/doc/src/sgml/ref/drop_function.sgml
+++ b/doc/src/sgml/ref/drop_function.sgml
@@ -1,5 +1,5 @@
@@ -36,7 +36,7 @@ DROP FUNCTION name ( [
- name
+ name
The name of an existing function.
@@ -47,7 +47,7 @@ DROP FUNCTION name ( [ type
- The type of function parameters.
+ The type of the function's parameters.
@@ -99,11 +99,11 @@ NOTICE RemoveFunction: Function "name
- DROP FUNCTION will remove references to an existing C
+ DROP FUNCTION will remove the definition of an existing
function. To execute this command the user must be the
owner of the function. The input argument types to the
- function must be specified, as only the function with the
- given name and argument types will be removed.
+ function must be specified, since several different functions
+ may exist with the same name and different argument lists.
@@ -117,8 +117,8 @@ NOTICE RemoveFunction: Function "name
- No checks are made to ensure that types, operators or access
- methods that rely on the function have been removed first.
+ No checks are made to ensure that types, operators, access
+ methods, or triggers that rely on the function have been removed first.
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index 668dd861ca..10f9a2a5f4 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -1,5 +1,5 @@
@@ -103,9 +103,11 @@ Postgres documentation
shutdown methods can be selected with the
option: Smart mode waits for all the clients to
disconnect. This is the default. Fast mode does
- not wait for clients to disconnect. All active transactions will
- be rolled back. Immediate mode will abort without
- complete shutdown. This will lead to a recovery run on restart.
+ not wait for clients to disconnect. All active transactions are
+ rolled back and clients are forcibly disconnected, then the
+ database is shut down. Immediate mode will abort
+ all server processes without clean shutdown. This will lead to a recovery
+ run on restart.
@@ -337,7 +339,7 @@ Command line was:
Waiting for complete start is not a well-defined operation and may
- fail if access control is set up in way that a local client cannot
+ fail if access control is set up so that a local client cannot
connect without manual interaction. It should be avoided.
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index d52736ac5a..5121d69a7d 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,4 +1,4 @@
-
+
@@ -584,7 +584,7 @@ connectDBStart() -- connect() failed: No such file or directory
To reorder database items, it is first necessary to dump the table of
contents of the archive:
-$pg_restore archive.file -l > archive.list
+$pg_restore -l archive.file > archive.list
The listing file consists of a header and one line for each item, e.g.,
@@ -628,7 +628,7 @@ connectDBStart() -- connect() failed: No such file or directory
could be used as input to pg_restore and would only restore
items 10 and 6, in that order.
-$pg_restore archive.file -L archive.list
+$pg_restore -L archive.list archive.file
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 6a192d9d67..51be109ab2 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
@@ -324,8 +324,8 @@ su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgs
FATAL: StreamServerPort: bind() failed: Address already in use
Is another postmaster already running on that port?
- This usually means just what it suggests: you accidentally
- started a second postmaster on the same port where one is already
+ This usually means just what it suggests: you tried to
+ start a second postmaster on the same port where one is already
running. However, if the kernel error message is not
Address already in use or some
variant of that wording, there may be a different problem. For
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 56963e255a..2bca167378 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -20,7 +20,7 @@
- The trigger function must be created before the trigger is created as a
+ The trigger function must be defined before the trigger is created as a
function taking no arguments and returning opaque. If the function is
written in C, it must use the version 1> function manager interface.
diff --git a/src/interfaces/python/README b/src/interfaces/python/README
index 24e100efac..7d9c73ae3d 100644
--- a/src/interfaces/python/README
+++ b/src/interfaces/python/README
@@ -976,9 +976,10 @@ The following describes the methods and variables of this class.
Parameters:
table - name of table
Returns:
- List of attribute names
+ Dictionary of attribute names (the names are the keys, the values
+ are the names of the attributes' types)
Description:
- Given the name of a table, digs out the list of attribute names.
+ Given the name of a table, digs out the set of attribute names.
3.6. get - get a tuple from a database table
--------------------------------------------