the interactive docs.
<Title><ProductName>Postgres</ProductName> Architectural Concepts</Title>
<Para>
- Before we continue, you should understand the basic
+ Before we begin, you should understand the basic
<ProductName>Postgres</ProductName> system architecture. Understanding how the
parts of <ProductName>Postgres</ProductName> interact will make the next chapter
somewhat clearer.
<ItemizedList>
<ListItem>
<Para>
- A supervisory daemon process (<Application>postmaster</Application>),
+ A supervisory daemon process (
the <Application>postmaster</Application>),
</Para>
</ListItem>
<ListItem>
</ListItem>
<ListItem>
<Para>
-
the one or more backend database servers (the <Application>postgres</Application> process itself).
+ one or more backend database servers (the <Application>postgres</Application> process itself).
</Para>
</ListItem>
</ItemizedList>
<Para>
A single <Application>postmaster</Application> 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
<Application>postmaster</Application>
(<XRef LinkEnd="PGARCH-CONNECTIONS">(a)),
From that point on, the frontend process and the backend
server communicate without intervention by the
<Application>postmaster</Application>. Hence, the <Application>postmaster</Application> is always running, waiting
- for requests, whereas frontend and backend processes
+ for connection requests, whereas frontend and backend processes
come and go. The <FileName>libpq</FileName> 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 <FileName>libpq</FileName>.
+ 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.
+</Para>
+
+<Para>
One implication of this architecture is that the
- <Application>postmaster</Application> and the backend always run on the same
- machine (the database server), while the frontend
+ <Application>postmaster</Application> 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.
+</Para>
+
+<Para>
You should also be aware that the <Application>postmaster</Application> and
postgres servers run with the user-id of the <ProductName>Postgres</ProductName>
- "superuser."
+ <quote>superuser</>.
Note that the <ProductName>Postgres</ProductName> 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
<literal>postgres</literal>), although many systems are installed that way.
Furthermore, the <ProductName>Postgres</ProductName> superuser should
- definitely not be the Unix superuser, <literal>root</literal>! In any
- case, all files relating to a database should belong to
+definitely not be the Unix superuser, <literal>root</literal>!
+It is safest if the <ProductName>Postgres</ProductName> 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 <ProductName>Postgres</ProductName> superuser.
</Para>
</sect1>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.13 2001/11/03 21:42:47 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.14 2001/11/19 03:58:23 tgl Exp $ -->
<chapter id="arrays">
<title>Arrays</title>
schedule text[][]
);
</programlisting>
+ As shown, an array data type is named by appending square brackets
+ (<literal>[ ]</>) to the data type name of the array elements.
The above query will create a table named
<structname>sal_emp</structname> with a <type>text</type> string
(<structfield>name</structfield>), a one-dimensional array of type
<para>
Now we do some <command>INSERT</command>s. 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.
(1 row)
</programlisting>
+ The array subscript numbers are written within square brackets.
<productname>Postgres</productname> uses the
<quote>one-based</quote> numbering convention for arrays, that is,
an array of n elements starts with <literal>array[1]</literal> and
<para>
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.
</para>
</para>
</tip>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+
</chapter>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.16 2001/11/18 20:33:32 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.17 2001/11/19 03:58:24 tgl Exp $ -->
<chapter id="charset">
<title>Localization</>
for any particular database cluster, or indexes on text columns will
become corrupt. <productname>Postgres</productname> enforces this
by recording the values of <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
- that are seen by <command>initdb</>. The server automatically adopts
+ that are seen by <application>initdb</>. The server automatically adopts
those two values when it is started; only the other <envar>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 <command>initdb</> time.
+ and it is chosen at <application>initdb</> time.
</para>
</sect2>
man page of your system if you are not sure.
</para>
+ <para>
+ Check that <productname>PostgreSQL</> is actually using the locale that
+ you think it is. <envar>LC_COLLATE</> and <envar>LC_CTYPE</> settings are
+ determined at <application>initdb</> time and cannot be changed without
+ repeating <application>initdb</>. Other locale settings including
+ <envar>LC_MESSAGES</> and <envar>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 <envar>LC_COLLATE</> and
+ <envar>LC_CTYPE</> settings of
+ a database with the <filename>contrib/pg_controldata</> utility program.
+ </para>
+
<para>
The directory <filename>src/test/locale</> contains a test suite
for <productname>PostgreSQL</>'s locale support.
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.27 2001/11/18 23:24:16 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.28 2001/11/19 03:58:24 tgl Exp $ -->
<chapter id="client-authentication">
<title>Client Authentication</title>
In order to use <productname>Kerberos</>, support for it must be
enabled at build time. Both Kerberos 4 and 5 are supported
(<literal>./configure --with-krb4</> or <literal>./configure
- --with-krb5</> respectively).
+ --with-krb5</> respectively), although only one version can be
+ supported in any one build.
</para>
<para>
- <productname>Postgres</> should operate like a normal Kerberos
- service. The name of the service principal is normally
- <literal>postgres</literal>, unless it was changed during the
- build. Make sure that your server key file is readable (and
+ <productname>Postgres</> operates like a normal Kerberos service.
+ The name of the service principal is
+ <replaceable>servicename/hostname@realm</>, where
+ <replaceable>servicename</> is <literal>postgres</literal>
+ (unless a different service name was selected at configure time
+ with <literal>./configure --with-krb-srvnam=whatever</>).
+ <replaceable>hostname</> is the fully qualified domain name of the server
+ machine. The service principal's realm is the preferred realm of the
+ server machine.
+ </para>
+
+ <para>
+ Client principals must have their <productname>Postgres</> username as
+ their first component, for example
+ <replaceable>pgusername/otherstuff@realm</>.
+ At present the realm of the client is not checked by
+ <productname>Postgres</>; so
+ if you have cross-realm authentication enabled, then any principal
+ in any realm that can communicate with yours will be accepted.
+ </para>
+
+ <para>
+ Make sure that your server key file is readable (and
preferably only readable) by the Postgres server account (see
<xref linkend="postgres-user">). The location of the key file
is specified with the <varname>krb_server_keyfile</> run time
</para>
<para>
- In the <productname>Kerberos</> 5 hooks, the following assumptions
- are made about user and service naming:
-
- <itemizedlist>
- <listitem>
- <para>
- User principal names (anames) are assumed to contain the actual
- Unix/<productname>Postgres</> user name in the first component.
- </para>
- </listitem>
- <listitem>
- <para>
- The <productname>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).
- </para>
- </listitem>
- </itemizedlist>
-
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Parameter</>
- <entry>Example</>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>user</>
- <entry>frew@S2K.ORG</>
- </row>
- <row>
- <entry>user</>
- <entry>aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG</>
- </row>
- <row>
- <entry>host</>
- <entry>postgres_dbms/ucbvax@S2K.ORG</>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ When connecting to the database make sure you have a ticket for a
+ principal matching the requested database username.
+ An example: For database username <literal>fred</>, both principal
+ <literal>fred@EXAMPLE.COM</> and
+ <literal>fred/users.example.com@EXAMPLE.COM</> can be
+ used to authenticate to the database server.
</para>
<para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.69 2001/11/12 21:04:45 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.70 2001/11/19 03:58:22 tgl Exp $
-->
<chapter id="datatype">
<entry><type>bigint</></entry>
<entry>8 bytes</entry>
<entry>Very large range fixed-precision</entry>
- <entry>about 18 decimal digits</entry>
+ <entry>-9223372036854775807 to 9223372036854775807</entry>
</row>
<row>
</indexterm>
<para>
- <type>interval</type>s can be specified with the following syntax:
+ <type>interval</type> values can be written with the following syntax:
<programlisting>
Quantity Unit [Quantity Unit...] [Direction]
-@ Quantity Unit [Direction]
+@ Quantity Unit [Quantity Unit...] [Direction]
</programlisting>
- where: <literal>Quantity</literal> is ..., <literal>-1</literal>,
- <literal>0</literal>, <literal>1</literal>, <literal>2</literal>, ...;
+ where: <literal>Quantity</literal> is an integer (possibly signed);
<literal>Unit</literal> is <literal>second</literal>,
<literal>minute</literal>, <literal>hour</literal>, <literal>day</literal>,
<literal>week</literal>, <literal>month</literal>, <literal>year</literal>,
<literal>decade</literal>, <literal>century</literal>, <literal>millennium</literal>,
or abbreviations or plurals of these units;
<literal>Direction</literal> can be <literal>ago</literal> or
- empty.
+ empty. The at sign (<literal>@</>) is optional noise. The amounts
+ of different quantities are implicitly added up with appropriate
+ sign accounting.
+ </para>
+
+ <para>
+ Quantities of days, hours, minutes, and seconds can be specified without
+ explicit unit markings: for example, <literal>'1 12:59:10'</> is read
+ the same as <literal>'1 day 12 hours 59 min 10 sec'</>.
</para>
</sect3>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.80 2001/11/18 21:17:10 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.81 2001/11/19 03:58:23 tgl Exp $
Postgres documentation
-->
</row>
<row>
- <entry><function>char_length</function>(<parameter>string</parameter>) or
character_length(<parameter>string</parameter>)</entry>
+ <entry><function>char_length</function>(<parameter>string</parameter>) or
<function>character_length</function>(<parameter>string</parameter>)</entry>
<entry><type>integer</type></entry>
<entry>
length of string
<entry><literal>Hi Thomas</literal></entry>
</row>
+ <row>
+ <entry><function>length</function>(<parameter>string</parameter>)</entry>
+ <entry><type>integer</type></entry>
+ <entry>
+ length of string
+ <indexterm>
+ <primary>character strings</primary>
+ <secondary>length</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>length</primary>
+ <secondary>character strings</secondary>
+ <see>character strings, length</see>
+ </indexterm>
+ </entry>
+ <entry><literal>length('jose')</></entry>
+ <entry><literal>4</></entry>
+ </row>
+
<row>
<entry>
<function>lpad</function>(<parameter>string</parameter> <type>text</type>,
<literal>TRIGGER</>. (Case of the string is not significant, however.)
</para>
+ <table>
+ <title>System Information Functions</>
+ <tgroup cols="3">
+ <thead>
+ <row><entry>Name</> <entry>Return Type</> <entry>Description</></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>version</>
+ <entry>text</>
+ <entry>PostgreSQL version information</>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <indexterm zone="functions-misc">
+ <primary>version</primary>
+ </indexterm>
+
+ <para>
+ <function>version()</> returns a string describing the PostgreSQL
+ server's version.
+ </para>
+
</sect1>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.15 2001/09/13 15:55:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.16 2001/11/19 03:58:23 tgl Exp $
-->
<chapter id="inherit">
or add a line in your <filename>postgresql.conf</filename> file.
</para>
</note>
+
+ <para>
+ 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 <literal>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.
+ </para>
+
</chapter>
<!-- Keep this comment at the end of the file
<tip>
<para>
- If you are using Windows NT/2000 you can build and use all of
+ If you are using Windows 98 or newer you can build and use all of
<productname>PostgreSQL</productname> <quote>the Unix way</quote>
if you install the <productname>Cygwin</productname> toolkit first.
In that case see <xref linkend="installation">.
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.63 2001/10/31 20:35:02 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.64 2001/11/19 03:58:24 tgl Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
<title>Getting The Source</title>
<para>
- The <productname>PostgreSQL</> &version; sources can by obtained from <ulink
+ The <productname>PostgreSQL</> &version; sources can be obtained by
+ anonymous FTP from <ulink
url="ftp://ftp.postgresql.org/pub/postgresql-&version;.tar.gz"></ulink>.
Use a mirror if possible. Then unpack it:
<screen>
<screen>
<userinput>gmake check</userinput>
</screen>
+ (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.
<
projects / postgresql / commitdiff