-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.16 2001/11/21 05:53:40 thomas Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.17 2001/11/28 20:49:09 petere Exp $ -->
<chapter id="arrays">
<title>Arrays</title>
The array subscript numbers are written within square brackets.
<productname>PostgreSQL</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
- ends with <literal>array[n]</literal>.
+ an array of <replaceable>n</> elements starts with <literal>array[1]</literal> and
+ ends with <literal>array[<replaceable>n</>]</literal>.
</para>
<para>
<tip>
<para>
- Arrays are not lists; using arrays in the manner described in the
+ Arrays are not sets; using arrays in the manner described in the
previous paragraph is often a sign of database misdesign. The
array field should generally be split off into a separate table.
Tables can obviously be searched easily.
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.21 2001/11/21 05:53:40 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.22 2001/11/28 20:49:09 petere Exp $
-->
<chapter id="backup">
<title>Backup and Restore</title>
<title><acronym>SQL</> Dump</title>
<para>
- The idea behind this method is to generate a text file with SQL
+ The idea behind the SQL-dump method is to generate a text file with SQL
commands that, when fed back to the server, will recreate the
database in the same state as it was at the time of the dump.
<productname>PostgreSQL</> provides the utility program
for the pg_dump command. The database <replaceable
class="parameter">dbname</replaceable> will not be created by this
command, you must create it yourself from template0 before executing
- <application>psql</> (e.g., with <userinput>createdb -T template0
- <replaceable class="parameter">dbname</></userinput>).
+ <application>psql</> (e.g., with <literal>createdb -T template0
+ <replaceable class="parameter">dbname</></literal>).
<application>psql</> supports similar options to <application>pg_dump</>
for controlling the database server location and the user names. See
its reference page for more information.
change between releases of <productname>PostgreSQL</>. This does not
apply to different <quote>patch levels</quote>, these always have
compatible storage formats. For example, releases 7.0.1, 7.1.2, and
- 7.2 are not compatible, whereas &version;.1 and &version;.2 are. When you
+ 7.2 are not compatible, whereas 7.1.1 and 7.1.2 are. When you
update between compatible versions, then you can simply reuse the
data area in disk by the new executables. Otherwise you need to
<quote>back up</> your data and <quote>restore</> it on the new
server, using <application>pg_dump</>. (There are checks in place
that prevent you from doing the wrong thing, so no harm can be done
by confusing these things.) The precise installation procedure is
- not subject of this section, the <citetitle>Installation
- Instructions</citetitle> carry these details.
+ not subject of this section, these details are in <xref linkend="installation">.
</para>
<para>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.18 2001/11/21 05:53:40 thomas Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.19 2001/11/28 20:49:09 petere Exp $ -->
<chapter id="charset">
<title>Localization</>
<para>
Multibyte (<acronym>MB</acronym>) support is intended to allow
<productname>PostgreSQL</productname> to handle
- multiple-byte character sets such as <acronym>EUC</> (Extended Unix Code), Unicode and
+ multiple-byte character sets such as <acronym>EUC</> (Extended Unix Code), Unicode, and
Mule internal code. With <acronym>MB</acronym> enabled you can use multibyte
character sets in regular expressions (regexp), LIKE, and some
other functions. The default
<application>initdb</application>. Note that this can be
overridden when you create a database using
<application>createdb</application> or by using the SQL command
- CREATE DATABASE. So you can have multiple databases each with
+ <command>CREATE DATABASE</>. So you can have multiple databases each with
a different encoding system.
</para>
- <para>
- <acronym>MB</acronym> also fixes some problems concerning 8-bit single byte
- character sets including ISO8859. (I would not say all problems
- have been fixed. I just confirmed that the regression test ran fine
- and a few French characters could be used with the patch. Please let
- me know if you find any problem while using 8-bit characters.)
- </para>
-
<sect2>
- <title>Enabling MB</title>
+ <title>Enabling Multibyte Support</title>
<para>
Run configure with the multibyte option:
- <programlisting>
-% ./configure --enable-multibyte[=<replaceable>encoding_system</replaceable>]
- </programlisting>
+<synopsis>
+./configure --enable-multibyte<optional>=<replaceable>encoding_system</replaceable></optional>
+</synopsis>
where <replaceable>encoding_system</replaceable> can be one of the
values in the following table:
<tbody>
<row>
<entry><literal>SQL_ASCII</literal></entry>
- <entry><acronym>US ASCII</acronym></entry>
+ <entry><acronym>ASCII</acronym></entry>
</row>
<row>
<entry><literal>EUC_JP</literal></entry>
</table>
</para>
- <para>
- CAUTION1: Note that before 7.2 LATIN5 meant ISO 8859-5 mistakely. In 7.2
- LATIN5 measn ISO 8859-9. If you have LATIN5 database created on
- 7.1 or before and want to migrate to 7.2, you should be very
- carefull about this change.
- </para>
+ <important>
+ <para>
+ Before <productname>PostgreSQL</>7.2, <literal>LATIN5</> mistakenly
+ meant ISO 8859-5. From 7.2 on,
+ <literal>LATIN5</> means ISO 8859-9. If you have a <literal>LATIN5</>
+ database created on 7.1 or earlier and want to migrate to 7.2 (or
+ later), you should be very careful about this change.
+ </para>
+ </important>
- <para>
- CAUTION2: Not all API supports encodings listed above. For example,
- <productname>PostgreSQL</>
- JDBC driver does not support MULE_INTERNAL, LATIN6,
- LATIN8 and LATIN10.
- </para>
+ <important>
+ <para>
+ Not all APIs supports all the encodings listed above. For example, the
+ <productname>PostgreSQL</>
+ JDBC driver does not support <literal>MULE_INTERNAL</>, <literal>LATIN6</>,
+ <literal>LATIN8</>, and <literal>LATIN10</>.
+ </para>
+ </important>
<para>
Here is an example of configuring
<productname>PostgreSQL</productname> to use a Japanese encoding by
default:
- <programlisting>
-% ./configure --enable-multibyte=EUC_JP
- </programlisting>
+<screen>
+$ <userinput>./configure --enable-multibyte=EUC_JP</userinput>
+</screen>
</para>
<para>
- If the encoding system is omitted (./configure --enable-multibyte),
- SQL_ASCII is assumed.
+ If the encoding system is omitted (<literal>./configure --enable-multibyte</literal>),
+ <literal>SQL_ASCII</> is assumed.
</para>
</sect2>
<application>initdb</application> defines the default encoding
for a <productname>PostgreSQL</productname> installation. For example:
- <programlisting>
-% initdb -E EUC_JP
- </programlisting>
+<screen>
+$ <userinput>initdb -E EUC_JP</>
+</screen>
sets the default encoding to <literal>EUC_JP</literal> (Extended Unix Code for Japanese).
Note that you can use <option>--encoding</option> instead of <option>-E</option> if you prefer
to type longer option strings.
- If no -E or --encoding option is given, the encoding
+ If no <option>-E</> or <option>--encoding</option> option is given, the encoding
specified at configure time is used.
</para>
<para>
You can create a database with a different encoding:
- <programlisting>
-% createdb -E EUC_KR korean
- </programlisting>
+<screen>
+$ <userinput>createdb -E EUC_KR korean</>
+</screen>
will create a database named <database>korean</database> with <literal>EUC_KR</literal> encoding.
Another way to accomplish this is to use a SQL command:
+<programlisting>
CREATE DATABASE korean WITH ENCODING = 'EUC_KR';
- </programlisting>
+</programlisting>
The encoding for a database is represented as an
<firstterm>encoding column</firstterm> in the
<literal>pg_database</literal> system catalog.
- You can see that by using <option>-l</option> or <command>\l</command> of <command>psql</command>
- command.
+ You can see that by using the <option>-l</option> option or the
+ <command>\l</command> command of <command>psql</command>.
- <programlisting>
-$ psql -l
+<screen>
+$ <userinput>psql -l</userinput>
List of databases
Database | Owner | Encoding
---------------+---------+---------------
test | t-ishii | EUC_JP
unicode | t-ishii | UNICODE
(9 rows)
- </programlisting>
+</screen>
</para>
</sect2>
<sect2>
- <title>Automatic encoding translation between backend and
- frontend</title>
+ <title>Automatic encoding translation between server and
+ client</title>
<para>
<productname>PostgreSQL</productname> supports an automatic
- encoding translation between backend
- and frontend for some encodings.
+ encoding translation between server
+ and client for some encodings. The available combinations are
+ listed in <xref linkend="multibyte-translation-table">.
+ </para>
- <table tocentry="1">
+ <table tocentry="1" id="multibyte-translation-table">
<title>Client/Server Character Set Encodings</title>
<titleabbrev>Communication Encodings</titleabbrev>
<tgroup cols="2">
</tbody>
</tgroup>
</table>
- </para>
<para>
To enable the automatic encoding translation, you have to tell
<productname>PostgreSQL</productname> the encoding you would like
- to use in frontend. There are
+ to use in the client. There are
several ways to accomplish this.
<itemizedlist>
<para>
Using the <command>\encoding</command> command in
<application>psql</application>.
- <command>\encoding</command> allows you to change frontend
+ <command>\encoding</command> allows you to change client
encoding on the fly. For
example, to change the encoding to <literal>SJIS</literal>, type:
+<programlisting>
\encoding SJIS
- </programlisting>
+</programlisting>
</para>
</listitem>
<command>\encoding</command> actually calls
<function>PQsetClientEncoding()</function> for its purpose.
- <programlisting>
+<synopsis>
int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>)
- </programlisting>
+</synopsis>
- where <replaceable>conn</replaceable> is a connection to the backend,
+ where <replaceable>conn</replaceable> is a connection to the server,
and <replaceable>encoding</replaceable> is an encoding you
want to use. If it successfully sets the encoding, it returns 0,
otherwise -1. The current encoding for this connection can be shown by
using:
- <programlisting>
+<synopsis>
int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
- </programlisting>
+</synopsis>
- Note that it returns the encoding id, not the encoding symbol string
- such as <literal>EUC_JP</literal>. To convert an encoding id to an encoding symbol, you
+ Note that it returns the encoding ID, not a symbolic string
+ such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
can use:
- <programlisting>
+<synopsis>
char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>)
- </programlisting>
+</synopsis>
</para>
</listitem>
<para>
Using <command>SET CLIENT_ENCODING TO</command>.
- Setting the frontend side encoding can be done by this SQL command:
+ Setting the client encoding can be done with this SQL command:
+<programlisting>
SET CLIENT_ENCODING TO 'encoding';
- </programlisting>
+</programlisting>
- Also you can use SQL92 syntax <literal>SET NAMES</literal> for this purpose:
+ Also you can use the SQL92 syntax <literal>SET NAMES</literal> for this purpose:
+<programlisting>
SET NAMES 'encoding';
- </programlisting>
+</programlisting>
- To query the current frontend encoding:
+ To query the current client encoding:
+<programlisting>
SHOW CLIENT_ENCODING;
- </programlisting>
+</programlisting>
To return to the default encoding:
+<programlisting>
RESET CLIENT_ENCODING;
- </programlisting>
+</programlisting>
</para>
</listitem>
If environment variable <envar>PGCLIENTENCODING</envar> is defined
in the client's environment, that client encoding is automatically
- selected when a backend connection is made. (This can subsequently
+ selected when a connection to the server is made. (This can subsequently
be overridden using any of the other methods mentioned above.)
</para>
</listitem>
<title>What happens if the translation is not possible?</title>
<para>
- Suppose you choose <literal>EUC_JP</literal> for the backend, <literal>LATIN1</literal> for the frontend,
- then some Japanese characters could not be translated into <literal>LATIN1</literal>. In
+ Suppose you choose <literal>EUC_JP</literal> for the server
+ and <literal>LATIN1</literal> for the client,
+ then some Japanese characters cannot be translated into <literal>LATIN1</literal>. In
this case, a letter that cannot be represented in the <literal>LATIN1</literal> character set
would be transformed as:
- <programlisting>
+<synopsis>
(HEXA DECIMAL)
- </programlisting>
+</synopsis>
</para>
</sect2>
<para>
Success depends on proper system locales. This has been tested
with <systemitem class="osname">Red Hat 6.0</> and <systemitem
- class="osname">Slackware 3.6</>, with <literal>cs_CZ.iso8859-2</literal> locale.
+ class="osname">Slackware 3.6</>, with the
+ <literal>cs_CZ.iso8859-2</literal> locale.
</para>
</listitem>
<listitem>
<para>
- Never try to set the server multibyte database encoding to WIN1250.
- Always use LATIN2 instead since there is not a WIN1250 locale
+ Never try to set the server's database encoding to WIN1250.
+ Always use LATIN2 instead since there is no WIN1250 locale
in Unix.
</para>
</listitem>
<listitem>
<para>
- WIN1250 encoding is usable only for Windows ODBC clients. The
+ The WIN1250 encoding is usable only for Windows ODBC clients. The
characters are recoded on the fly, to be displayed and stored
back properly.
</para>
</itemizedlist>
</para>
- <para>
- When running, it is important to remember the following:
-
- <itemizedlist>
- <listitem>
- <para>
- This configuration reorders your sort order depending on your
- <envar>LC_<replaceable>x</replaceable></envar> settings. Don't be
- confused with the regression test results since they don't use
- locale.
- </para>
- </listitem>
-
- <listitem>
- <para>
- A locale such as <literal>ch</literal> is correctly sorted
- only if your system
- supports that locale; older systems may not do so but new ones
- (e.g. RH6.0) do.
- </para>
- </listitem>
-
- <listitem>
- <para>
- You have to insert money as '<literal>162,50</literal>' (note
- comma within the single-quotes).
- </para>
- </listitem>
-
- <listitem>
- <para>
- At the time of writing (early 1999), this configuration has
- not received extensive testing. Please let us know of any
- changes you had to make!
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
<procedure>
<title>WIN1250 on Windows/ODBC</title>
<step>
<para>
Compile <productname>PostgreSQL</productname> with locale enabled
- and the multibyte encoding set to <literal>LATIN2</literal>.
+ and the server-side encoding set to <literal>LATIN2</literal>.
</para>
</step>
<step>
<para>
Set up your installation. Do not forget to create locale
- variables in your profile (environment). For example (this may
+ variables in your environment. For example (this may
not be correct for <emphasis>your</emphasis> environment):
+<programlisting>
LC_ALL=cs_CZ.ISO8859-2
-LC_COLLATE=cs_CZ.ISO8859-2
-LC_CTYPE=cs_CZ.ISO8859-2
-LC_MONETARY=cs_CZ.ISO8859-2
-LC_NUMERIC=cs_CZ.ISO8859-2
-LC_TIME=cs_CZ.ISO8859-2
- </programlisting>
+</programlisting>
</para>
</step>
<step>
<para>
- You have to start the postmaster with locales set!
+ You have to start the server with locales set!
</para>
</step>
<step>
<para>
- Try it with Czech language, and have it sort on a query.
+ Try it with the Czech language, and have it sort on a query.
</para>
</step>
<step>
<para>
- Setup properly your data source. Include this line in your ODBC
- configuration dialog in the field <literal>Connect Settings</literal>:
+ Set up your data source properly. Include this line in your ODBC
+ configuration dialog in the field <guilabel>Connect Settings</guilabel>:
+<programlisting>
SET CLIENT_ENCODING = 'WIN1250';
- </programlisting>
+</programlisting>
</para>
</step>
cannot use different encodings on the same host at the same
time. It is also inconvenient when you boot your client hosts into
multiple operating systems. Nevertheless, when these restrictions are
- not limiting and you do not need multibyte characters than it is a
+ not limiting and you do not need multibyte characters then it is a
simple and effective solution.
</para>
</sect1>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.29 2001/11/21 05:53:40 thomas Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.30 2001/11/28 20:49:09 petere Exp $ -->
<chapter id="client-authentication">
<title>Client Authentication</title>
separate from user names of the operating system in which the server
runs. If all the users of a particular server also have accounts on
the server's machine, it makes sense to assign database user names
- that match their Unix user ids. However, a server that accepts remote
+ that match their operating system user names. However, a server that accepts remote
connections may have many users who have no local account, and in such
- cases there need be no connection between database user names and Unix
+ cases there need be no connection between database user names and OS
user names.
</para>
<filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (<acronym>HBA</> stands
for host-based authentication.) A default <filename>pg_hba.conf</filename>
file is installed when the
- data area is initialized by <application>initdb</application>.
+ data area is initialized by <command>initdb</command>.
</para>
<para>
(if relevant for the connection type), a database name or names,
and the authentication method to be used for connections matching
these parameters.
- The first record that matches the type, client address and requested
+ The first record that matches the type, client address, and requested
database name of a connection attempt is used to do the
authentication step. There is no <quote>fall-through</> or
<quote>backup</>: if one record is chosen and the authentication
<para>
Since the <filename>pg_hba.conf</filename> records are examined
- sequentially for each connection attempt, order of the records is
+ sequentially for each connection attempt, the order of the records is
very significant. Typically, earlier records will have tight
connection match parameters and weaker authentication methods,
while later records will have looser match parameters and stronger
and when the <application>postmaster</> receives a
<systemitem>SIGHUP</systemitem> signal. If you edit the file on an
active system, you will need to signal the <application>postmaster</>
- (using <application>pg_ctl reload</> or <application>kill -HUP</>)
+ (using <literal>pg_ctl reload</> or <literal>kill -HUP</>)
to make it re-read the file.
</para>
<synopsis>
<replaceable>username</replaceable>:<replaceable>password</replaceable>
</synopsis>
- Any extra colon separated fields following the password are
+ Any extra colon-separated fields following the password are
ignored. The password is expected to be encrypted using the
system's <function>crypt()</function> function. The utility
program <application>pg_passwd</application> that is installed
</para>
<para>
- Client principals must have their <productname>PostgreSQL</> username as
+ Client principals must have their <productname>PostgreSQL</> user name as
their first component, for example
<replaceable>pgusername/otherstuff@realm</>.
At present the realm of the client is not checked by
<para>
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
+ principal matching the requested database user name.
+ An example: For database user name <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.
and when the <application>postmaster</> receives a
<systemitem>SIGHUP</systemitem> signal. If you edit the file on an
active system, you will need to signal the <application>postmaster</>
- (using <application>pg_ctl reload</> or <application>kill -HUP</>)
+ (using <literal>pg_ctl reload</> or <literal>kill -HUP</>)
to make it re-read the file.
</para>
No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb
</ProgramListing>
This is what you are most likely to get if you succeed in
- contacting the server, but it doesn't want to talk to you. As the
+ contacting the server, but it does not want to talk to you. As the
message suggests, the server refused the connection request
because it found no authorizing entry in its <filename>pg_hba.conf</filename>
configuration file.
Password authentication failed for user 'joeblow'
</ProgramListing>
Messages like this indicate that you contacted the server, and
- it's willing to talk to you, but not until you pass the
+ it is willing to talk to you, but not until you pass the
authorization method specified in the
- <filename>pg_hba.conf</filename> file. Check the password you're
- providing, or check your Kerberos or IDENT software if the
+ <filename>pg_hba.conf</filename> file. Check the password you are
+ providing, or check your Kerberos or ident software if the
complaint mentions one of those authentication types.
</para>
<ProgramListing>
FATAL 1: user "joeblow" does not exist
</ProgramListing>
- The indicated user name was not found in pg_shadow.
+ The indicated user name was not found.
</para>
<para>
<ProgramListing>
FATAL 1: Database "testdb" does not exist in the system catalog.
</ProgramListing>
- The database you're trying to connect to doesn't exist. Note that
- if you don't specify a database name, it defaults to the database
+ The database you are trying to connect to does not exist. Note that
+ if you do not specify a database name, it defaults to the database
user name, which may or may not be the right thing.
</para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.76 2001/11/24 19:57:06 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.77 2001/11/28 20:49:09 petere Exp $
-->
<chapter id="datatype">
<row>
<entry><type>time with time zone</type></entry>
- <entry>timetz</entry>
+ <entry><type>timetz</type></entry>
<entry>time of day, including time zone</entry>
</row>
<row>
<entry><type>timestamp without time zone</type></entry>
- <entry>timestamp</entry>
+ <entry><type>timestamp</type></entry>
<entry>date and time</entry>
</row>
<row>
<entry><type>timestamp [ with time zone ]</type></entry>
- <entry>timestamptz</entry>
+ <entry><type>timestamptz</type></entry>
<entry>date and time, including time zone</entry>
</row>
</tbody>
limit on precision. A column of this kind will not coerce input
values to any particular scale, whereas <type>numeric</type> columns
with a declared scale will coerce input values to that scale.
- (The SQL standard requires a default scale of 0, ie, coercion to
+ (The SQL standard requires a default scale of 0, i.e., coercion to
integer accuracy. We find this a bit useless. If you're concerned about
portability, always specify the precision and scale explicitly.)
</para>
names <type>bigserial</type> and <type>serial8</type> work just
the same way, except that they create a <type>bigint</type>
column. <type>bigserial</type> should be used if you anticipate
- use of more than 2^31 identifiers over the lifetime of the table.
+ use of more than 2<superscript>31</> identifiers over the lifetime of the table.
</para>
<para>
The storage requirement for data of these types is 4 bytes plus
the actual string, and in case of <type>character</type> plus the
padding. Long strings will be compressed by the system
- automatically, so the physical requirement on-disk may be less.
+ automatically, so the physical requirement on disk may be less.
In any case, the longest possible character string
that can be stored is about 1 GB. (The maximum value that will be
allowed for <replaceable>n</> in the data type declaration is
Octets of certain values <emphasis>must</emphasis> be escaped (but all
octet values <emphasis>may</emphasis> be escaped) when used as part of
a string literal in an <acronym>SQL</acronym> statement. In general,
- to escape an octet, it is converted into the three digit octal number
+ to escape an octet, it is converted into the three-digit octal number
equivalent of its decimal octet value, and preceded by two
backslashes. Some octet values have alternate escape sequences, as
shown in <xref linkend="datatype-binary-sqlesc">.
<acronym>SQL</acronym> string literals (input strings) must be
preceded with two backslashes due to the fact that they must pass
through two parsers in the PostgreSQL backend. The first backslash
- is interpreted as an escape character by the string literal parser,
+ is interpreted as an escape character by the string-literal parser,
and therefore is consumed, leaving the octets that follow.
The remaining backslash is recognized by the <type>bytea</type> input
function as the prefix of a three digit octal value. For example, a string
literal passed to the backend as <literal>'\\001'</literal> becomes
- <literal>'\001'</literal> after passing through the string literal
+ <literal>'\001'</literal> after passing through the string-literal
parser. The <literal>'\001'</literal> is then sent to the
<type>bytea</type> input function, where it is converted to a single
octet with a decimal value of 1.
For a similar reason, a backslash must be input as
<literal>'\\\\'</literal> (or <literal>'\\134'</literal>). The first
and third backslashes are interpreted as escape characters by the
- string literal parser, and therefore are consumed, leaving two
+ string-literal parser, and therefore are consumed, leaving two
backslashes in the string passed to the <type>bytea</type> input function,
which interprets them as representing a single backslash.
For example, a string literal passed to the
backend as <literal>'\\\\'</literal> becomes <literal>'\\'</literal>
- after passing through the string literal parser. The
+ after passing through the string-literal parser. The
<literal>'\\'</literal> is then sent to the <type>bytea</type> input
function, where it is converted to a single octet with a decimal
value of 92.
<type>bytea</type> input function does <emphasis>not</emphasis>
recognize a single quote as a special octet. Therefore a string
literal passed to the backend as <literal>'\''</literal> becomes
- <literal>'''</literal> after passing through the string literal
+ <literal>'''</literal> after passing through the string-literal
parser. The <literal>'''</literal> is then sent to the
<type>bytea</type> input function, where it is retains its single
octet decimal value of 39.
<entry> Operators operating on and returning binary strings
include concatenation, substring, overlay, and trim</entry>
<entry> Operators operating on and returning binary strings
- include concatenation, substring, and trim. The <literal>
- 'leading'</literal> and <literal>'trailing'</literal>
+ include concatenation, substring, and trim. The
+ <literal>leading</literal> and <literal>trailing</literal>
arguments for trim are not yet implemented.
</entry>
</row>
<note>
<para>
- Time zones, and time zone conventions, are influenced by
+ Time zones, and time-zone conventions, are influenced by
political conventions, not just physical effects. Time zones have
become somewhat standardized during the 1900's, but continue to
be prone to arbitrary changes with time.
<productname>PostgreSQL</productname> uses your operating
- system's underlying features to provide time zone
+ system's underlying features to provide time-zone
support, and these systems usually contain information for only
the time period 1902 through 2038 (corresponding to the full
range of conventional Unix system time).
<para>
Date and time input is accepted in almost any reasonable format, including
- <acronym>ISO
-8601</acronym>, <acronym>SQL</acronym>-compatible,
+ <acronym>ISO
8601</acronym>, <acronym>SQL</acronym>-compatible,
traditional <productname>PostgreSQL</productname>, and others.
The ordering of month and day in date input can be ambiguous, therefore a setting
exists to specify how it should be interpreted in ambiguous cases. The command
</row>
<row>
<entry>1/8/1999</entry>
- <entry>US; read as August 1 in European mode</entry>
+ <entry>U.S.; read as August 1 in European mode</entry>
</row>
<row>
<entry>8/1/1999</entry>
- <entry>European; read as August 1 in US mode</entry>
+ <entry>European; read as August 1 in U.S. mode</entry>
</row>
<row>
<entry>1/18/1999</entry>
- <entry>US; read as January 18 in any mode</entry>
+ <entry>U.S.; read as January 18 in any mode</entry>
</row>
<row>
<entry>19990108</entry>
<tbody>
<row>
<entry>04:05:06.789</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
<row>
<entry>04:05:06</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
<row>
<entry>04:05</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
<row>
<entry>040506</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
<row>
<entry>04:05 AM</entry>
<tbody>
<row>
<entry>04:05:06.789-8</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
<row>
<entry>04:05:06-08:00</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
<row>
<entry>04:05-08:00</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
<row>
<entry>040506-08</entry>
- <entry>ISO-8601</entry>
+ <entry>ISO 8601</entry>
</row>
</tbody>
</tgroup>
<literal>'now'</literal> is
evaluated when the value is first interpreted.
+ </para>
- <caution>
+ <note>
<para>
As of <productname>PostgreSQL</> version 7.2,
<literal>'current'</literal> is no longer supported as a
Previously,
<literal>'current'</literal> was stored as a special value,
and evaluated to <literal>'now'</literal> only when
- used in a math operation or type
+ used in an expression or type
conversion.
</para>
- </caution>
- </para>
+ </note>
</sect3>
</sect2>
<para>
Output formats can be set to one of the four styles
- ISO
-8601, <acronym>SQL</acronym> (Ingres), traditional
+ ISO
8601, <acronym>SQL</acronym> (Ingres), traditional
PostgreSQL, and German, using the <command>SET DateStyle</command>.
The default is the <acronym>ISO</acronym> format.
<para>
The <acronym>SQL</acronym> style has European and non-European
- (US) variants,
+ (U.S.) variants,
which determines whether month follows day or vice versa. (See
also <xref linkend="datatype-datetime-input">
for how this setting affects interpretation of
input values.)
<table tocentry="1">
- <title>Date Order Conventions</title>
+ <title>Date-Order Conventions</title>
<tgroup cols="3">
<thead>
<row>
<type>time</type> type can.
Time zones in the real world can have no meaning unless
associated with a date as well as a time
- since the offset may vary through the year with daylight savings
+ since the offset may vary through the year with daylight-saving
time boundaries.
</para>
</listitem>
<listitem>
<para>
The default time zone is specified as a constant integer offset
- from GMT/UTC. It is not possible to adapt to daylight savings
+ from GMT/UTC. It is not possible to adapt to daylight-saving
time when doing date/time arithmetic across
<acronym>DST</acronym> boundaries.
</para>
<para>
To address these difficulties, we recommend using date/time
types that contain both date and time when using time zones. We
- recommend <emphasis>not</emphasis> using the SQL92 type TIME
- WITH TIME ZONE (though it is supported by
+ recommend <emphasis>not</emphasis> using the SQL92 type <type>time
+ with time zone</type> (though it is supported by
<productname>PostgreSQL</productname> for legacy applications and
for compatibility with other RDBMS implementations).
<productname>PostgreSQL</productname>
assumes local time for any type containing only
date or time. Further, time zone support is derived from
the underlying operating system
- time zone capabilities, and hence can handle daylight savings time
+ time-zone capabilities, and hence can handle daylight-saving time
and other expected behavior.
</para>
<para>
- <productname>PostgreSQL</productname> obtains time zone support
+ <productname>PostgreSQL</productname> obtains time-zone support
from the underlying operating system for dates between 1902 and
2038 (near the typical date limits for Unix-style
systems). Outside of this range, all dates are assumed to be
</para>
<para>
- There are several ways to affect the time zone behavior:
+ There are several ways to affect the time-zone behavior:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<term><replaceable>x</replaceable></term>
<listitem>
<para>
- The x-axis coordinate as a floating point number.
+ The x-axis coordinate as a floating-point number
</para>
</listitem>
</varlistentry>
<term><replaceable>y</replaceable></term>
<listitem>
<para>
- The y-axis coordinate as a floating point number.
+ The y-axis coordinate as a floating-point number
</para>
</listitem>
</varlistentry>
<term>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</term>
<listitem>
<para>
- The end points of the line segment.
+ The end points of the line segment
</para>
</listitem>
</varlistentry>
<term>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</term>
<listitem>
<para>
- Opposite corners of the box.
+ Opposite corners of the box
</para>
</listitem>
</varlistentry>
<listitem>
<para>
End points of the line segments comprising the boundary of the
- polygon.
+ polygon
</para>
</listitem>
</varlistentry>
<term>(<replaceable>x</replaceable>,<replaceable>y</replaceable>)</term>
<listitem>
<para>
- Center of the circle.
+ Center of the circle
</para>
</listitem>
</varlistentry>
<term><replaceable>r</replaceable></term>
<listitem>
<para>
- Radius of the circle.
+ Radius of the circle
</para>
</listitem>
</varlistentry>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.85 2001/11/21 22:33:14 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.86 2001/11/28 20:49:09 petere Exp $
PostgreSQL documentation
-->
VARYING</type>, and <type>TEXT</type>. Unless otherwise noted, all
of the functions listed below work on all of these types, but be
wary of potential effects of the automatic padding when using the
- <type>CHARACTER</type> type. Generally the functions described
+ <type>CHARACTER</type> type. Generally, the functions described
here also work on data of non-string types by converting that data
to a string representation first. Some functions also exist
- natively for bit string types.
+ natively for bit-string types.
</para>
<para>
you must write two backslashes in the query. Thus, writing a pattern
that actually matches a literal backslash means writing four backslashes
in the query. You can avoid this by selecting a different escape
- character with <literal>ESCAPE</literal>; then backslash isn't special
- to <function>LIKE</> anymore. (But it's still special to the string
+ character with <literal>ESCAPE</literal>; then backslash is not special
+ to <function>LIKE</> anymore. (But it is still special to the string
literal parser, so you still need two of them.)
</para>
In an output template string, there are certain patterns that are
recognized and replaced with appropriately-formatted data from the value
to be formatted. Any text that is not a template pattern is simply
- copied verbatim. Similarly, in an input template string template patterns
+ copied verbatim. Similarly, in an input template string, template patterns
identify the parts of the input data string to be looked at and the
values to be found there.
</para>
<listitem>
<para>
Millisecond <literal>MS</literal> and microsecond <literal>US</literal>
- values are in conversion from string to time stamp used as part of
- second after decimal point. For example
+ values in a conversion from string to time stamp are used as part of the
+ seconds after the decimal point. For example
<literal>to_timestamp('12:3', 'SS:MS')</literal> is not 3 milliseconds,
- but 300, because the conversion count it as <literal>12 + 0.3</literal>.
- It means for format 'SS:MS' is '12:3' or '12:30' or '12:300' same
- number of milliseconds. For the three milliseconds must be used
- '12:003' that the conversion count as
- <literal> 12 + 0.003 = 12.003 seconds </literal>. Here is a more
+ but 300, because the conversion counts it as 12 + 0.3.
+ This means for the format <literal>SS:MS</>, the input values
+ <literal>12:3</>, <literal>12:30</>, and <literal>12:300</> specify the
+ same number of milliseconds. To get three milliseconds, one must use
+ <literal>12:003</>, which the conversion counts as
+ 12 + 0.003 = 12.003 seconds.
+ </para>
+
+ <para>
+ Here is a more
complex example:
<literal>to_timestamp('15:12:02.020.001230','HH:MI:SS.MS.US')</literal>
- is 15 hours, 12 minutes, 2.021230 seconds.
+ is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds +
+ 1230 microseconds = 2.021230 seconds.
</para>
</listitem>
</itemizedlist>
</row>
<row>
<entry><literal>EEEE</literal></entry>
- <entry>scientific numbers (not supported yet)</entry>
+ <entry>scientific notation (not implemented yet)</entry>
</row>
</tbody>
</tgroup>
<itemizedlist>
<listitem>
<para>
- A sign formatted using 'SG', 'PL' or 'MI' is not an anchor in
+ A sign formatted using <literal>SG</>, <literal>PL</>, or
+ <literal>MI</> is not an anchor in
the number; for example,
- to_char(-12, 'S9999') produces <literal>' -12'</literal>,
- but to_char(-12, 'MI9999') produces <literal>'- 12'</literal>.
+ <literal>to_char(-12, 'S9999')</> produces <literal>' -12'</literal>,
+ but <literal>to_char(-12, 'MI9999')</> produces <literal>'- 12'</literal>.
The Oracle implementation does not allow the use of
<literal>MI</literal> ahead of <literal>9</literal>, but rather
requires that <literal>9</literal> precede
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.17 2001/11/23 22:06:20 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 petere Exp $
-->
<sect1 id="history">
- <title>A Short History of <productname>Postgres</productname></title>
+ <title>A Short History of <productname>PostgreSQL</productname></title>
<para>
The object-relational database management system now known as
<para>
In addition to the monitor program, a new program
(<application>psql</application>) was provided for interactive SQL queries
- using <acronym>GNU</acronym> <filename>readline</filename>.
+ using <acronym>GNU</acronym> <application>Readline</application>.
</para>
</listitem>
A new front-end library, <filename>libpgtcl</filename>,
supported <acronym>Tcl</acronym>-based clients. A sample shell,
<command>pgtclsh</command>, provided new Tcl commands to interface
- <application>tcl</application>
+ <application>Tcl</application>
programs with the <productname>Postgres95</productname> backend.
</para>
</listitem>
<para>
A short tutorial introducing regular <acronym>SQL</acronym> features as
well as those of <productname>Postgres95</productname> was
- distributed with the source code.
+ distributed with the source code
</para>
</listitem>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/indices.sgml,v 1.28 2001/11/21 05:53:41 thomas Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/indices.sgml,v 1.29 2001/11/28 20:49:10 petere Exp $ -->
<chapter id="indexes">
<title id="indexes-title">Indexes</title>
</para>
<para>
- When an index is created, it has to be kept synchronized with the
+ When an index is created, the system has to keep it synchronized with the
table. This adds overhead to data manipulation operations.
Therefore indexes that are non-essential or do not get used at all
should be removed. Note that a
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.14 2001/11/21 05:53:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/info.sgml,v 1.15 2001/11/28 20:49:10 petere Exp $
-->
<sect1 id="resources">
<term>Yourself!</term>
<listitem>
<para>
- <productname>PostgreSQL</productname> is an open source effort.
+ <productname>PostgreSQL</productname> is an open-source effort.
As such, it depends on the user community for ongoing support.
As you begin to use <productname>PostgreSQL</productname>, you
will rely on others for help, either through the documentation
or through the mailing lists. Consider contributing your
knowledge back. If you learn something which is not in the
documentation, write it up and contribute it. If you add
- features to the code, contribute it.
+ features to the code, contribute them.
</para>
<para>
<para>
To use the libraries, you must add the
<filename>libpqdll.lib</filename> file to your project. (In Visual
- C++, just right-click on the project and chose to add it.)
+ C++, just right-click on the project and choose to add it.)
</para>
</chapter>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.66 2001/11/27 20:35:08 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.67 2001/11/28 20:49:10 petere Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
<application>make</> programs will <emphasis>not</> work.
<acronym>GNU</> <application>make</> is often installed under
the name <filename>gmake</filename>; this document will always
- refer to it by that name. (On <systemitem class="osname">GNU/Linux</> systems GNU make is the
+ refer to it by that name. (On some systems GNU make is the
default tool with the name <filename>make</>.) To test for
<acronym>GNU</acronym> <application>make</application> enter
<screen>
<para>
Also check that you have sufficient disk space. You will need about
- 30 MB for the source tree during compilation and about 5 MB for the
- installation directory. An empty database takes about 1 MB, later
- it takes about five times the amount of space that a flat text file
+ 30 MB for the source tree during compilation and about 10 MB for the
+ installation directory. An empty database cluster takes about 20 MB, databases
+ take about five times the amount of space that a flat text file
with the same data would take. If you are going to run the
regression tests you will temporarily need an extra 20 MB. Use the
<command>df</command> command to check for disk space.
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:
+ Use a mirror if possible. After you have obtained the file, unpack it:
<screen>
<userinput>gunzip postgresql-&version;.tar.gz</userinput>
<userinput>tar xf postgresql-&version;.tar</userinput>
</screen>
This will create a directory
- <filename>postgresql-&version;</filename> with the
- <productname>PostgreSQL</> sources
- in the current directory. Change into that directory for the rest
+ <filename>postgresql-&version;</filename> under the current directory
+ with the <productname>PostgreSQL</> sources.
+ Change into that directory for the rest
of the installation procedure.
</para>
</sect1>
<replaceable>PREFIX</> was set to. This can be useful to
share architecture-independent files between hosts. If you
omit this, then <replaceable>EXEC-PREFIX</> is set equal to
- <replaceable>PREFIX</> and both architecture dependent and
+ <replaceable>PREFIX</> and both architecture-dependent and
independent files will be installed under the same tree,
which is probably what you want.
</para>
<term><option>--enable-multibyte</option></term>
<listitem>
<para>
- Allows the use of multibyte character encodings. This is
- primarily for languages like Japanese, Korean, and Chinese.
- Read
+ Allows the use of multibyte character encodings (including Unicode)
+ and character set encoding conversion. Read
<![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]>
<![%standalone-ignore[<xref linkend="multibyte">]]>
for details.
</para>
+
+ <para>
+ Note that some interfaces (such as Tcl or Java) expect all character
+ strings to be in Unicode, so this option will be required to correctly
+ support these interfaces.
+ </para>
</listitem>
</varlistentry>
<term><option>--enable-odbc</option></term>
<listitem>
<para>
- Build the ODBC driver.
+ Build the ODBC driver. By default, the driver will be independent
+ of a driver manager. To work better with a driver manager already
+ installed on your system, use one of the following options. More
+ information can be found in the <citetitle>Programmer's Guide</citetitle>.
</para>
</listitem>
</varlistentry>
Also, having the tests turned on won't necessarily enhance the
stability of your server! The assertion checks are not categorized
for severity, and so what might be a relatively harmless bug will
- still lead to postmaster restarts if it triggers an assertion
+ still lead to server restarts if it triggers an assertion
failure. Currently, this option is not recommended for
production use, but you should have it on for development work
or when running a beta version.
<userinput>gmake -C src/interfaces/perl5 install</userinput>
<userinput>gmake -C src/interfaces/python install</userinput>
</screen>
- Due to a quirk in the Perl build environment the first command
- will actually rebuild the complete interface and then install it.
- This is not harmful, just unusual. If you do not have superuser
+ If you do not have superuser
access you are on your own: you can still take the required files
and place them in other directories where Perl or Python can find
them, but how to do that is left as an exercise.
<screen>
<userinput>gmake install-all-headers</userinput>
</screen>
- This adds a megabyte or two to the install footprint, and is only
+ This adds a megabyte or two to the installation footprint, and is only
useful if you don't plan to keep the whole source tree around for
reference. (If you do, you can just use the source's include
directory when building server-side software.)
<para>
To undo the installation use the command <command>gmake
- uninstall</>. However, this will not remove the Perl and Python
- interfaces and it will not remove any directories.
+ uninstall</>. However, this will not remove any directories.
</para>
</step>
</procedure>
<entry>7.1</entry>
<entry>2001-03-26, Magnus Hagander (<email>mha@sollentuna.net</email>)</entry>
<entry>
- client-side libraries (<application>libpq</> and <application>psql</>) or ODBC/JDBC, no server-side;
+ client-side libraries (<application>libpq</> and <application>psql</>) or ODBC or JDBC, no server-side;
<![%standalone-include[see Administrator's Guide]]>
<![%standalone-ignore[see <xref linkend="install-win32">]]>
for instructions
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.9 2001/11/21 05:53:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.10 2001/11/28 20:49:10 petere Exp $
-->
<chapter id="maintenance">
</indexterm>
<para>
- In normal <productname>PostgreSQL</productname> operation, an UPDATE or
- DELETE of a row does not immediately remove the old <firstterm>tuple</>
+ In normal <productname>PostgreSQL</productname> operation, an <command>UPDATE</> or
+ <command>DELETE</> of a row does not immediately remove the old <firstterm>tuple</>
(version of the row). This approach is necessary to gain the benefits
of multiversion concurrency control (see the <citetitle>User's Guide</>):
the tuple must not be deleted while
The new approach to XID comparison distinguishes two special XIDs, numbers
1 and 2 (<literal>BootstrapXID</> and <literal>FrozenXID</>). These two
XIDs are always considered older than every normal XID. Normal XIDs (those
- greater than 2) are compared using modulo-2^31 arithmetic. This means
+ greater than 2) are compared using modulo-2<superscript>31</> arithmetic. This means
that for every normal XID, there are two billion XIDs that are
<quote>older</> and two billion that are <quote>newer</>; another way to
say it is that the normal XID space is circular with no endpoint.
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.19 2001/11/21 05:53:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.20 2001/11/28 20:49:10 petere Exp $
-->
<chapter id="managing-databases">
CREATE DATABASE <replaceable>name</>
</synopsis>
where <replaceable>name</> follows the usual rules for SQL identifiers.
- (Depending on the
- current implementation, certain characters that are special to the
- underlying operating system might be prohibited. There will be
- run-time checks for that.) The current user automatically becomes
+ The current user automatically becomes
the owner of the new database. It is the privilege of the owner of
a database to remove it later on (which also removes all the
objects in it, even if they have a different owner).
one might copy any database in an installation by specifying its name
as the template for <command>CREATE DATABASE</>. It is important to
understand, however, that this is not (yet) intended as
- a general-purpose COPY DATABASE facility. In particular, it is
+ a general-purpose <quote>COPY DATABASE</quote> facility. In particular, it is
essential that the source database be idle (no data-altering transactions
in progress)
for the duration of the copying operation. <command>CREATE DATABASE</>
may be set to indicate that a database is intended as a template for
<command>CREATE DATABASE</>. If this flag is set, the database may be
cloned by
- any user with CREATEDB privileges; if it is not set, only superusers
+ any user with <literal>CREATEDB</> privileges; if it is not set, only superusers
and the owner of the database may clone it.
If <literal>datallowconn</literal> is false, then no new connections
to that database will be allowed (but existing sessions are not killed
initlocation PGDATA2
</programlisting>
</informalexample>
- The you can restart the server.
+ Then you can restart the server.
</para>
<para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.20 2001/11/21 05:53:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.21 2001/11/28 20:49:10 petere Exp $
-->
<chapter id="mvcc">
adequate for many applications, and this level is fast and simple to use.
However, for applications that do complex queries and updates, it may
be necessary to guarantee a more rigorously consistent view of the
- database than Read Committed level provides.
+ database than the Read Committed level provides.
</para>
</sect1>
transaction commit, a serializable transaction will be rolled back
with the message
- <programlisting>
+<screen>
ERROR: Can't serialize access due to concurrent update
- </programlisting>
+</screen>
because a serializable transaction cannot modify rows changed by
other transactions after the serializable transaction began.
</para>
<para>
- Serializable transaction level provides a rigorous guarantee that each
+ The Serializable transaction level provides a rigorous guarantee that each
transaction sees a wholly consistent view of the database. However,
the application has to be prepared to retry transactions when concurrent
updates make it impossible to sustain the illusion of serial execution,
and the cost of redoing complex transactions may be significant. So
this level is recommended only when update queries contain logic
- sufficiently complex that they may give wrong answers in Read Committed
+ sufficiently complex that they may give wrong answers in the Read Committed
level.
</para>
</sect1>
transaction isolation level, data read by one transaction can be
overwritten by another concurrent transaction. In other words,
if a row is returned by <command>SELECT</command> it doesn't mean that
- the row still exists at the time it is returned (i.e. sometime after the
+ the row still exists at the time it is returned (i.e., sometime after the
current transaction began); the row might have been modified or deleted
by an already-committed transaction that committed after this one started.
Even if the row is still valid <quote>now</quote>, it could be changed or deleted
<title>Row-level locks</title>
<para>
- These locks are acquired when rows are being updated (or deleted or
+ Row-level locks are acquired when rows are being updated (or deleted or
marked for update).
Row-level locks don't affect data querying. They block
writers to <emphasis>the same row</emphasis> only.
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.14 2001/11/21 05:53:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.15 2001/11/28 20:49:10 petere Exp $
-->
<chapter id="performance-tips">
</para>
<sect2 id="disable-autocommit">
- <title>Disable Auto-commit</title>
+ <title>Disable Autocommit</title>
<para>
- Turn off auto-commit and just do one commit at
+ Turn off autocommit and just do one commit at
the end. (In plain SQL, this means issuing <command>BEGIN</command>
at the start and <command>COMMIT</command> at the end. Some client
libraries may do this behind your back, in which case you need to
Use <command>COPY FROM STDIN</command> to load all the records in one
command, instead of using
a series of <command>INSERT</command> commands. This reduces parsing,
- planning, etc
- overhead a great deal. If you do this then it's not necessary to fool
- around with auto-commit, since it's only one command anyway.
+ planning, etc.
+ overhead a great deal. If you do this then it is not necessary to turn
+ off autocommit, since it is only one command anyway.
</para>
</sect2>
INDEX</command>, load the table, then recreate the index. Of
course, the database performance for other users may be adversely
affected during the time that the index is missing. One should also
- think twice before dropping UNIQUE indexes, since the error checking
- afforded by the UNIQUE constraint will be lost while the index is missing.
+ think twice before dropping unique indexes, since the error checking
+ afforded by the unique constraint will be lost while the index is missing.
</para>
</sect2>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.13 2001/11/21 05:53:41 thomas Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.14 2001/11/28 20:49:10 petere Exp $ -->
<chapter id="queries">
<title>Queries</title>
+ <sect1 id="queries-overview">
+ <title>Overview</title>
+
<para>
A <firstterm>query</firstterm> is the process of retrieving or the command
to retrieve data from a database. In SQL the <command>SELECT</command>
SELECT random();
</programlisting>
</para>
+ </sect1>
<sect1 id="queries-table-expressions">
<title>Table Expressions</title>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.22 2001/11/23 21:08:51 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.23 2001/11/28 20:49:10 petere Exp $
-->
<chapter id="tutorial-sql">
</indexterm>
You could also have used <command>COPY</command> to load large
- amounts of data from flat text files. This is usually faster
- because the <command>COPY</command> is optimized for this
+ amounts of data from flat-text files. This is usually faster
+ because the <command>COPY</command> command is optimized for this
application while allowing less flexibility than
<command>INSERT</command>. An example would be:
COPY weather FROM '/home/user/weather.txt';
</programlisting>
- where the path name for the source file must be available to the
+ where the file name for the source file must be available to the
backend server machine, not the client, since the backend server
reads the file directly. You can read more about the
<command>COPY</command> command in the <citetitle>Reference
<indexterm><primary>query</primary></indexterm>
<indexterm><primary>SELECT</primary></indexterm>
- To retrieve data from a table it is
+ To retrieve data from a table, the table is
<firstterm>queried</firstterm>. An <acronym>SQL</acronym>
<command>SELECT</command> statement is used to do this. The
statement is divided into a select list (the part that lists the
columns to be returned), a table list (the part that lists the
tables from which to retrieve the data), and an optional
qualification (the part that specifies any restrictions). For
- example, to retrieve all the rows of
+ example, to retrieve all the rows of table
<classname>weather</classname>, type:
<programlisting>
SELECT * FROM weather;
There are two columns containing the city name. This is
correct because the lists of columns of the
<classname>weather</classname> and the
- <classname>cities</classname> tables are concatenated. In
+ <classname>cities</classname> table are concatenated. In
practice this is undesirable, though, so you will probably want
to list the output columns explicitly rather than using
<literal>*</literal>:
</screen>
which gives us the same results for only the cities that have all
- <literal>temp_lo</> values below forty. Finally, if we only care about
+ <literal>temp_lo</> values below 40. Finally, if we only care about
cities whose
names begin with <quote><literal>S</literal></quote>, we might do
will be inputs to the aggregates. On the other hand,
<literal>HAVING</literal> clauses always contain aggregate functions.
(Strictly speaking, you are allowed to write a <literal>HAVING</literal>
- clause that doesn't use aggregates, but it's wasteful; the same condition
+ clause that doesn't use aggregates, but it's wasteful: The same condition
could be used more efficiently at the <literal>WHERE</literal> stage.)
</para>
<para>
A filled data disk may result in subsequent corruption of database
- indices, but not of the fundamental data tables. If the WAL files
+ indexes, but not of the fundamental data tables. If the WAL files
are on the same disk (as is the case for a default configuration)
then a filled disk during database initialization may result in
corrupted or incomplete WAL files. This failure condition is
</chapter>
-<chapter Id="recovery">
- <title>Database Recovery</title>
-
- <para>
- Database recovery is necessary in the event of hardware or software
- failure. There are several categories of failures; some of these
- require relatively minor adjustments to the database, while others
- may depend on the existance of previously prepared database dumps
- and other recovery data sets. It should be emphasized that if your
- data is important and/or difficult to regenerate, then you should
- have considered and prepared for various failure scenarios.
- </para>
-
-</chapter>
-
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.21 2001/11/18 20:35:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.22 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<term>-h, --host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the
- <application>postmaster</application>
- is running. If host begins with a slash, it is used
+ Specifies the host name of the machine on which the
+ server is running. If host begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
<listitem>
<para>
Specifies the Internet TCP/IP port or the local Unix domain socket file
- extension on which the <command>postmaster</command>
- is listening for connections.
+ extension on which the server is listening for connections.
</para>
</listitem>
</varlistentry>
<term>-U, --username <replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
- Username to connect as.
+ User name to connect as
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Echo the queries that <application>createdb</application> generates
- and sends to the backend.
+ and sends to the server.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the name of the database to be created. The name must be
- unique among all <productname>Postgres</productname> databases in this installation.
+ unique among all <productname>PostgreSQL</productname> databases in this installation.
The default is to create a database with the same name as the
current system user.
</para>
Description
</title>
<para>
- <application>createdb</application> creates a new <productname>Postgres</productname>
+ <application>createdb</application> creates a new <productname>PostgreSQL</productname>
database. The user who executes this command becomes the database owner.
</para>
<application>createdb</application> is a shell script wrapper around the
<acronym>SQL</acronym> command
<xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
- the <productname>Postgres</productname> interactive terminal
+ the <productname>PostgreSQL</productname> interactive terminal
<xref linkend="APP-PSQL">. Thus, there is nothing
special about creating databases via this or other methods. This means
that the <application>psql</application> program must be found by the script and that
<informalexample>
<para>
To create the database <literal>demo</literal> using the
- postmaster on host eden, port 5000, using the
+ server on host eden, port 5000, using the
<literal>LATIN1</literal> encoding scheme with a look at the
underlying query:
<screen>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.19 2001/10/26 21:17:03 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.20 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<listitem>
<para>
Specifies the directory in which the language interpreter is
- to be found. Use of this option is deprecated; the directory
- is normally found automatically.
+ to be found. The directory is normally found automatically; this
+ option is primarily for debugging purposes.
</para>
</listitem>
</varlistentry>
<term>-h, --host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the
- <application>postmaster</application>
+ Specifies the host name of the machine on which the
+ server
is running. If host begins with a slash, it is used
- as the directory for the unix domain socket.
+ as the directory for the Unix domain socket.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the server
is listening for connections.
</para>
</listitem>
<term>-U, --username <replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
- Username to connect as.
+ User name to connect as
</para>
</listitem>
</varlistentry>
<para>
<application>createlang</application> is a utility for adding a new
- programming language to a <productname>Postgres</productname> database.
- <application>createlang</application> currently accepts several
- languages, <literal>plpgsql, pltcl, pltclu,</literal> and <literal>
- plperl</literal>.
+ programming language to a <productname>PostgreSQL</productname> database.
+ <application>createlang</application> can handle all the languages
+ supplied in the default <productname>PostgreSQL</> distribution, but
+ not languages provided by other parties.
</para>
<para>
Although backend programming languages can be added directly using
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.20 2001/09/03 12:57:49 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.21 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<term>-h, --host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the
- <application>postmaster</application>
+ Specifies the host name of the machine on which the
+ server
is running. If host begins with a slash, it is used
- as the directory for the unix domain socket.
+ as the directory for the Unix domain socket.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the server
is listening for connections.
</para>
</listitem>
<listitem>
<para>
Echo the queries that <application>createuser</application> generates
- and sends to the backend.
+ and sends to the server.
</para>
</listitem>
</varlistentry>
<term><replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
- Specifies the name of the <productname>Postgres</productname> user to be created.
- This name must be unique among all <productname>Postgres</productname> users.
+ Specifies the name of the <productname>PostgreSQL</productname> user to be created.
+ This name must be unique among all <productname>PostgreSQL</productname> users.
</para>
</listitem>
</varlistentry>
</title>
<para>
<application>createuser</application> creates a
- new <productname>Postgres</productname> user.
+ new <productname>PostgreSQL</productname> user.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> table can create
- new <productname>Postgres</productname> users.
+ new <productname>PostgreSQL</productname> users.
</para>
<para>
<application>createuser</application> is a shell script wrapper around the
<acronym>SQL</acronym> command
<xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title"> via
- the <productname>Postgres</productname> interactive terminal
+ the <productname>PostgreSQL</productname> interactive terminal
<xref linkend="APP-PSQL">. Thus, there is nothing
special about creating users via this or other methods. This means
that the <application>psql</application> must be found by the script and that
<informalexample>
<para>
To create the same user <literal>joe</literal> using the
- postmaster on host eden, port 5000, avoiding the prompts and
+ server on host eden, port 5000, avoiding the prompts and
taking a look at the underlying query:
<screen>
<prompt>$ </prompt><userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.11 2001/09/03 12:57:50 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.12 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<term>-h, --host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the
- <application>postmaster</application>
+ Specifies the host name of the machine on which the
+ server
is running. If host begins with a slash, it is used
as the directory for the unix domain socket.
</para>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the server
is listening for connections.
</para>
</listitem>
<term>-U, --username <replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
- Username to connect as.
+ User name to connect as
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Echo the queries that <application>dropdb</application> generates
- and sends to the backend.
+ and sends to the server.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the name of the database to be removed. The database
- must be one of the existing <productname>Postgres</productname> databases
+ must be one of the existing <productname>PostgreSQL</productname> databases
in this installation.
</para>
</listitem>
</title>
<para>
<application>dropdb</application> destroys an existing
- <productname>Postgres</productname> database.
+ <productname>PostgreSQL</productname> database.
The user who executes this command must be a database
superuser or the owner of the database.
</para>
<application>dropdb</application> is a shell script wrapper around the
<acronym>SQL</acronym> command
<xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> via
- the <productname>Postgres</productname> interactive terminal
+ the <productname>PostgreSQL</productname> interactive terminal
<xref linkend="APP-PSQL">. Thus, there is nothing
special about dropping databases via this or other methods. This means
that the <application>psql</application> must be found by the script and that
<informalexample>
<para>
To destroy the database <literal>demo</literal> using the
- postmaster on host eden, port 5000, with verification and a peek
+ server on host eden, port 5000, with verification and a peek
at the underlying query:
<screen>
<prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.13 2001/09/14 09:49:00 ishii Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.14 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<term>-h, --host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the
- <application>postmaster</application>
+ Specifies the host name of the machine on which the
+ server
is running. If host begins with a slash, it is used
- as the directory for the unix domain socket.
+ as the directory for the Unix domain socket.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the server
is listening for connections.
</para>
</listitem>
<term>-U, --username <replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
- Username to connect as.
+ User name to connect as
</para>
</listitem>
</varlistentry>
<para>
<application>droplang</application> is a utility for removing an
existing programming language from a
- <productname>Postgres</productname> database.
- <application>droplang</application> currently accepts two
- languages, <literal>plsql</literal> and <literal>pltcl</literal>.
+ <productname>PostgreSQL</productname> database.
+ <application>droplang</application> can drop any procedural language,
+ even those not supplied by the <productname>PostgreSQL</> distribution.
</para>
<para>
Although backend programming languages can be removed directly using
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.13 2001/09/03 12:57:50 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.14 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<term>-h, --host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the
- <application>postmaster</application>
+ Specifies the host name of the machine on which the
+ server
is running. If host begins with a slash, it is used
- as the directory for the unix domain socket.
+ as the directory for the Unix domain socket.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the server
is listening for connections.
</para>
</listitem>
<listitem>
<para>
Echo the queries that <application>createdb</application> generates
- and sends to the backend.
+ and sends to the server.
</para>
</listitem>
</varlistentry>
<term><replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
- Specifies the name of the <productname>Postgres</productname> user to be removed.
- This name must exist in the <productname>Postgres</productname> installation.
+ Specifies the name of the <productname>PostgreSQL</productname> user to be removed.
+ This name must exist in the <productname>PostgreSQL</productname> installation.
You will be prompted for a name if none is specified on the command line.
</para>
</listitem>
</title>
<para>
<application>dropuser</application> removes an existing
- <productname>Postgres</productname> user
+ <productname>PostgreSQL</productname> user
<emphasis>and</emphasis> the databases which that user owned.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> table can destroy
- <productname>Postgres</productname> users.
+ <productname>PostgreSQL</productname> users.
</para>
<para>
<application>dropuser</application> is a shell script wrapper around the
<acronym>SQL</acronym> command
<xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title"> via
- the <productname>Postgres</productname> interactive terminal
+ the <productname>PostgreSQL</productname> interactive terminal
<xref linkend="APP-PSQL">. Thus, there is nothing
special about removing users via this or other methods. This means
that the <application>psql</application> must be found by the script and that
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.12 2001/11/18 20:35:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.13 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<listitem>
<para>
Specify an additional include path.
- Defaults are <filename>.</filename>,
+ Defaults are <filename>.</filename> (current directory),
<filename>/usr/local/include</filename>, the
- <productname>Postgres</productname> include path which is
+ <productname>PostgreSQL</productname> include path which is
defined at compile time (default:
- <filename>/usr/local/pgsql/lib</filename>), and
+ <filename>/usr/local/pgsql/include</filename>), and
<filename>/usr/include</filename>.
</para>
</listitem>
<variablelist>
<varlistentry>
- <term><replaceable>return value</replaceable></term>
+ <term>Return value</term>
<listitem>
<para>
<application>ecpg</application> returns 0 to the shell on successful completion, non-zero
<para>
<application>ecpg</application>
is an embedded SQL preprocessor for the C language and the
- <productname>Postgres</productname>. It
+ <productname>PostgreSQL</productname>. It
enables development of C programs with embedded SQL code.
</para>
<para>
An embedded SQL source file must be preprocessed before
compilation:
- <programlisting>
+<synopsis>
ecpg [ -d ] [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.pgc
- </programlisting>
+</synopsis>
where the optional <option>-d</option> flag turns on debugging.
The <literal>.pgc</literal> extension is an
<title>Compiling and Linking</title>
<para>
- Assuming the <productname>Postgres</productname> binaries are in
+ Assuming the <productname>PostgreSQL</productname> binaries are in
<filename>/usr/local/pgsql</filename>, you will need to compile
and link your preprocessed source file:
- <programlisting>
+<synopsis>
gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.c -L /usr/local/pgsql/lib -lecpg -lpq
- </programlisting>
+</synopsis>
</para>
</refsect2>
</refsect1>
<para>
The preprocessor will prepend two directives to the source:
+<programlisting>
#include <ecpgtype.h>
#include <ecpglib.h>
- </programlisting>
+</programlisting>
</para>
</refsect2>
<para>
Variables declared within <application>ecpg</application> source code must be prepended with:
+<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
- </programlisting>
+</programlisting>
</para>
<para>
Similarly, variable declaration sections must terminate with:
+<programlisting>
EXEC SQL END DECLARE SECTION;
- </programlisting>
+</programlisting>
<note>
<para>
Prior to version 2.1.0, each variable had to be declared
on a separate line. As of version 2.1.0 multiple variables may
be declared on a single line:
+<programlisting>
char foo[16], bar[16];
- </programlisting>
+</programlisting>
</para>
</note>
</para>
<para>
The SQL communication area is defined with:
+<programlisting>
EXEC SQL INCLUDE sqlca;
- </programlisting>
+</programlisting>
+ </para>
<note>
<para>
The <literal>sqlca</literal> is in lowercase.
While SQL convention may be
followed, i.e., using uppercase to separate embedded SQL
- from C statements, sqlca (which includes the sqlca.h
- header file) MUST be lowercase. This is because the EXEC SQL
- prefix indicates that this INCLUDE will be parsed by <application>ecpg</application>.
- <application>ecpg</application> observes case sensitivity (SQLCA.h will not be found).
+ from C statements, sqlca (which includes the <filename>sqlca.h</>
+ header file) <emphasis>must</> be lowercase. This is because the
+ EXEC SQL prefix indicates that this inclusion will be parsed by
+ <application>ecpg</application>.
+ <application>ecpg</application> observes case sensitivity
+ (<filename>SQLCA.h</> will not be found).
<command>EXEC SQL INCLUDE</command>
can be used to include other header files
as long as case sensitivity is observed.
</para>
</note>
- </para>
<para>
The sqlprint command is used with the EXEC SQL WHENEVER
statement to turn on error handling throughout the
program:
+<programlisting>
EXEC SQL WHENEVER sqlerror sqlprint;
- </programlisting>
+</programlisting>
and
+<programlisting>
EXEC SQL WHENEVER not found sqlprint;
- </programlisting>
+</programlisting>
+ </para>
<note>
<para>
This is <emphasis>not</emphasis> an exhaustive example of usage for
the <command>EXEC SQL WHENEVER</command> statement.
Further examples of usage may
- be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by
+ be found in SQL manuals (e.g., <citetitle>The LAN TIMES Guide to SQL</> by
Groff and Weinberg).
</para>
</note>
- </para>
</refsect2>
<refsect2 id="R2-APP-ECPG-connecting">
<para>
One connects to a database using the following:
+<programlisting>
EXEC SQL CONNECT TO <replaceable>dbname</replaceable>;
- </programlisting>
+</programlisting>
where the database name is not quoted. Prior to version 2.1.0, the
database name was required to be inside single quotes.
Specifying a server and port name in the connect statement is also
possible. The syntax is:
- <programlisting>
+<synopsis>
<replaceable>dbname</replaceable>[@<replaceable>server</replaceable>][:<replaceable>port</replaceable>]
- </programlisting>
+</synopsis>
or
- <programlisting>
+<synopsis>
<tcp|unix>:postgresql://<replaceable>server</replaceable>[:<replaceable>port</replaceable>][/<replaceable>dbname</replaceable>][?<replaceable>options</replaceable>]
- </programlisting>
+</synopsis>
</para>
</refsect2>
<para>
Create Table:
+<programlisting>
EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
EXEC SQL CREATE UNIQUE index num1 on foo(number);
EXEC SQL COMMIT;
- </programlisting>
+</programlisting>
</para>
<para>
Insert:
+<programlisting>
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;
- </programlisting>
+</programlisting>
</para>
<para>
<programlisting>
EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT;
- </programlisting>
+</programlisting>
</para>
<para>
Singleton Select:
+<programlisting>
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
- </programlisting>
+</programlisting>
</para>
<para>
Select using Cursors:
+<programlisting>
EXEC SQL DECLARE foo_bar CURSOR FOR
SELECT number, ascii FROM foo
ORDER BY ascii;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;
- </programlisting>
+</programlisting>
</para>
<para>
Updates:
+<programlisting>
EXEC SQL UPDATE foo
SET ascii = 'foobar'
WHERE number = 9999;
EXEC SQL COMMIT;
- </programlisting>
+</programlisting>
</para>
</refsect2>
</refsect1>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.17 2001/09/08 15:24:00 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.18 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<term>-E <replaceable class="parameter">encoding</replaceable></term>
<listitem>
<para>
- Selects the multibyte encoding of the template database. This will also
+ Selects the encoding of the template database. This will also
be the default encoding of any database you create later, unless you
- override it there. To use the multibyte encoding feature, you must
- specify so at build time, at which time you also select the default
+ override it there. To use the encoding feature, you must
+ have enabled it at build time, at which time you also select the default
for this option.
</para>
</listitem>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.10 2001/11/19 03:58:25 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.11 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
started manually, <application>pg_ctl</application> encapulates
tasks such as redirecting log output, properly detaching from the
terminal and process group, and it provides convenient options for
- controlled shut down.
+ controlled shutdown.
</para>
<para>
</para>
<para>
- <option>reload</option> mode simply sends the postmaster a SIGHUP signal,
+ <option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
causing it to reread its configuration files
(<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
- etc). This allows changing of configuration-file options that do not
+ etc.). This allows changing of configuration-file options that do not
require a complete restart to take effect.
</para>
</varlistentry>
<varlistentry>
- <term>-w</term>
+ <term>-s</term>
<listitem>
<para>
- Wait for the start or shutdown to complete. Times out after
- 60 seconds. This is the default for shutdowns.
+ Only print errors, no informational messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-W</term>
+ <term>-w</term>
<listitem>
<para>
- Do not wait for start or shutdown to complete. This is the
- default for starts and restarts.
+ Wait for the start or shutdown to complete. Times out after
+ 60 seconds. This is the default for shutdowns.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-s</term>
+ <term>-W</term>
<listitem>
<para>
- Only print errors, no informational messages.
+ Do not wait for start or shutdown to complete. This is the
+ default for starts and restarts.
</para>
</listitem>
</varlistentry>
<title>Starting the postmaster</title>
<para>
- To start up <application>postmaster</application>:
+ To start up
a <application>postmaster</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
<para>
An example of starting the <application>postmaster</application>,
- blocking until postmaster comes up is:
+ blocking until the postmaster comes up is:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
- stops postmaster. Using the <option>-m</option> switch allows one
+ stops the postmaster. Using the <option>-m</option> switch allows one
to control <emphasis>how</emphasis> the backend shuts down.
</para>
</refsect2>
<para>
This is almost equivalent to stopping the
- <application>postmaster</application> then starting it again
+ <application>postmaster</application> and starting it again
except that pg_ctl saves and reuses the command line options that
were passed to the previously running instance. To restart
- <application>postmaster</application> in the simplest form:
+
the <application>postmaster</application> in the simplest form:
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.39 2001/11/18 20:35:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.40 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<para>
<command>pg_dump</command> is a utility for saving a
<productname>PostgreSQL</productname> database into a script or an
- archive file. The script files are in plain text format and
+ archive file. The script files are in plain-text format and
contain the SQL commands required to reconstruct the database to
the state it was in at the time it was saved. They can be used to
reconstruct the database even on other machines and other
architectures, with some modifications even on other RDBMS
- products. The alternative archive file formats are meant to be
+ products. Furthermore, there are alternative archive file formats that
+ are meant to be
used with <xref linkend="app-pgrestore"> to rebuild the database,
and they also allow <command>pg_restore</command> to be selective
about what is restored, or even to reorder the items prior to being
<para>
<command>pg_dump</command>
is useful for dumping out the contents of a database to move from one
- <productname>Postgres</productname> installation to another.
+ <productname>PostgreSQL</productname> installation to another.
</para>
<para>
</para>
<para>
- This option is only meaningful for the plain text format. For
+ This option is only meaningful for the plain-text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</para>
<para>
- This option is only meaningful for the plain text format. For
+ This option is only meaningful for the plain-text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</para>
<para>
- This option is only meaningful for the plain text format. For
+ This option is only meaningful for the plain-text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
<term>p</term>
<listitem>
<para>
-
output a plain text <acronym>SQL</acronym> script file (default)
+
Output a plain-text <acronym>SQL</acronym> script file (default)
</para>
</listitem>
</varlistentry>
<term>t</term>
<listitem>
<para>
- output a <filename>tar</filename> archive suitable for input into
+ Output a <filename>tar</filename> archive suitable for input into
<command>pg_restore</command>. Using this archive format
allows reordering and/or exclusion of schema elements
at the time the database is restored. It is also possible to limit
<term>c</term>
<listitem>
<para>
- output a custom archive suitable for input into
+ Output a custom archive suitable for input into
<command>pg_restore</command>. This is the most flexible
format in that it allows reordering of data load as well
as schema elements. This format is also compressed by default.
</para>
<para>
- This option is only meaningful for the plain text format. For
+ This option is only meaningful for the plain-text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
</para>
<para>
- This option is only meaningful for the plain text format. For
+ This option is only meaningful for the plain-text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
<term>--use-set-session-authorization</term>
<listitem>
<para>
- Normally, if a (plain text mode) script generated by
+ Normally, if a (plain-text mode) script generated by
<command>pg_dump</command> must alter the current database
user (e.g., to set correct object ownerships), it uses the
<xref linkend="app-psql"> <command>\connect</command> command.
</para>
<para>
- This option is only meaningful for the plain text format. For
+ This option is only meaningful for the plain-text format. For
the other formats, you may specify the option when you
call <command>pg_restore</command>.
</para>
<listitem>
<para>
Specifies the host name of the machine on which the
- <command>postmaster</command>
+ server
is running. If host begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <command>postmaster</command>
+ extension on which the server
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.25 2001/10/23 22:11:22 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.26 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<para>
<application>pg_dumpall</application> is a utility for writing out
- (<quote>dumping</quote>) all Postgres databases of a cluster into
+ (<quote>dumping</quote>) all PostgreSQL databases of a cluster into
one script file. The script file contains SQL commands that can be
used as input to <xref linkend="app-psql">
to restore the databases. It does this by calling <xref
<term>-h <replaceable>host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the database
+ Specifies the host name of the machine on which the database
server is running. If host begins with a slash, it is used as
the directory for the Unix domain socket. The default is
taken from the <envar>PGHOST</envar> environment variable, if
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.8 2001/09/03 12:57:50 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.9 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<refnamediv>
<refname>pg_passwd</refname>
- <refpurpose>change a secondary password file</refpurpose>
+ <refpurpose>change a secondary <productname>PostgreSQL</> password file</refpurpose>
</refnamediv>
<refsynopsisdiv>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.20 2001/11/26 23:09:21 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.21 2001/11/28 20:49:10 petere Exp $ -->
<refentry id="APP-PGRESTORE">
<docinfo>
<para>
<command>pg_restore</command> is a utility for restoring a
- <productname>Postgres</productname> database from an archive
+ <productname>PostgreSQL</productname> database from an archive
created by <xref linkend="app-pgdump"> in one of the non-plain-text
formats. It
will issue the commands necessary to re-generate all user-defined
current database user (e.g., to set correct object
ownerships), a new connection to the database must be opened,
which might require manual interaction (e.g., passwords). If
- you use the <option>-X use-set-session-authorization</option>,
+ you use the <option>-X use-set-session-authorization</option> option,
then <command>pg_restore</command> will instead use the <xref
linkend="sql-set-session-authorization"> command. This has
the same effect, but it requires that the user restoring the
<listitem>
<para>
Specifies the host name of the machine on which the
- <command>postmaster</command>
+ server
is running. If host begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <command>postmaster</command>
+ extension on which the server
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<command>pg_restore</command> could not attach to the
<command>postmaster</command>
process on the specified host and port. If you see this message,
- ensure that the <command>postmaster</command>
+ ensure that the server
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgaccess-ref.sgml,v 1.11 2001/09/03 12:57:50 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgaccess-ref.sgml,v 1.12 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
Description
</title>
<para>
- <application>pgaccess</application> provides a graphical interface
- for <productname>Postgres</productname>
+ <application>PgAccess</application> provides a graphical interface
+ for <productname>PostgreSQL</productname>
wherein you
can manage your tables, edit them, define queries, sequences and
functions.
</para>
<para>
- <application>pgaccess</application> can:
+ <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
Open any database on a specified host at the specified port,
- username, and password.
+ user name, and password.
</para>
</listitem>
</para>
<para>
- For tables, <application>pgaccess</application> can:
+ For tables, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<listitem>
<para>
- Delete records; point to the record, press <keycap>Delete</keycap> key.
+ Delete records; point to the record, press the <keycap>Delete</keycap> key.
</para>
</listitem>
</para>
<para>
- For queries, <application>pgaccess</application> can:
+ For queries, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
</para>
<para>
- For sequences, <application>pgaccess</application> can:
+ For sequences, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
</para>
<para>
- For views, <application>pgaccess</application> can:
+ For views, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
</para>
<para>
- For functions, <application>pgaccess</application> can:
+ For functions, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
</para>
<para>
- For reports, <application>pgaccess</application> can:
+ For reports, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
</para>
<para>
- For forms, <application>pgaccess</application> can:
+ For forms, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
</para>
<para>
- For scripts, <application>pgaccess</application> can:
+ For scripts, <application>PgAccess</application> can:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<title>Notes</title>
<para>
- <application>pgaccess</application> is written in Tcl/Tk. Your
+ <application>PgAccess</application> is written in Tcl/Tk. Your
<productname>PostgreSQL</productname> installation needs to be
- built with Tcl support for <application>pgaccess</application> to
+ built with Tcl support for <application>PgAccess</application> to
be available.
</para>
</refsect1>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.21 2001/11/25 01:11:36 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.22 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
queries and the results will be printed to the screen, but in a
form that is more useful for developers than end users. But note
that running a single-user backend is not truly suitable for
- debugging the server since no realistic inter-process communication
+ debugging the server since no realistic interprocess communication
and locking will happen.
</para>
<title>Usage</title>
<para>
- Start a standalone backend with a command like
+ Start a stand-alone backend with a command like
<screen>
<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
</screen>
</para>
<para>
- Normally, the standalone backend treats newline as the command
+ Normally, the stand-alone backend treats newline as the command
entry terminator; there is no intelligence about semicolons,
as there is in <application>psql</>. To continue a command
across multiple lines, you must type backslash just before each
<para>
But if you use the <option>-N</> command line switch, then newline does
- not terminate command entry. The backend will read stdin until EOF, then
+ not terminate command entry. The backend will read the standard input
+ until the end-of-file (EOF) marker, then
process the input as a single query string. Backslash-newline is not
treated specially in this case.
</para>
<para>
- The standalone backend does not have readline input processing
- (no command history, for example).
+ To quit the session, type EOF
+ (<keycombo action="simul"><keycap>Control</><keycap>D</></>, usually).
+ If you've
+ used <option>-N</>, two consecutive EOFs are needed to exit.
</para>
<para>
- To quit the backend, type EOF (control-D, usually). If you've
- used <option>-N</>, two consecutive EOFs are needed to exit.
+ Note that the stand-alone backend does not provide sophisticated
+ line-editing features (no command history, for example).
</para>
</refsect1>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.24 2001/11/26 19:41:55 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.25 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<term>-h <replaceable class="parameter">hostname</replaceable></term>
<listitem>
<para>
- Specifies the TCP/IP hostname or address on which the
+ Specifies the TCP/IP host name or address on which the
<application>postmaster</application> is to listen for
connections from client applications. Defaults to
- listening on all configured addresses (including localhost).
+ listening on all configured addresses (including
+ <systemitem class="systemname">localhost</systemitem>).
</para>
</listitem>
</varlistentry>
Sets a named run-time parameter; a shorter form of
<option>-c</>.
</para>
- <para>
- The <option>--</> option will not work on FreeBSD or OpenBSD.
- Use <option>-c</> instead. This should be fixed in
- <productname>PostgreSQL</productname> 7.3.
- </para>
</listitem>
</varlistentry>
<tip>
<para>
You may be able to postpone
- reconfiguring your kernel by decreasing -B to reduce
- <productname>Postgres</productname>' shared memory
- consumption, and/or by reducing -N to reduce Postgres' semaphore
+ reconfiguring your kernel by decreasing <option>-B</option> to reduce
+ the shared memory consumption of <productname>PostgreSQL</>,
+ and/or by reducing <option>-N</option> to reduce the semaphore
consumption.
</para>
</tip>
start and shut down the <application>postmaster</application>
safely and comfortably.
</para>
+
+ <para>
+ The <option>--</> options will not work on FreeBSD or OpenBSD.
+ Use <option>-c</> instead. This is a bug in the affected operating
+ systems; a future release of <productname>PostgreSQL</productname> will
+ provide a workaround if this is not fixed.
+ </para>
+
</refsect1>
<refsect1 id="app-postmaster-usage">
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.18 2001/09/03 12:57:50 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.19 2001/11/28 20:49:10 petere Exp $
Postgres documentation
-->
<varlistentry>
<term>-a</term>
- <term>--alldb</term>
+ <term>--all</term>
<listitem>
<para>
Vacuum all databases.
<term>--host <replaceable class="parameter">host</replaceable></term>
<listitem>
<para>
- Specifies the hostname of the machine on which the
- <application>postmaster</application>
+ Specifies the host name of the machine on which the
+ server
is running. If host begins with a slash, it is used
- as the directory for the unix domain socket.
+ as the directory for the Unix domain socket.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the server
is listening for connections.
</para>
</listitem>
<term>--username <replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
- Username to connect as.
+ User name to connect as
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Echo the commands that <application>vacuumdb</application> generates
- and sends to the backend.
+ and sends to the server.
</para>
</listitem>
</varlistentry>
<para>
<application>vacuumdb</application> is a utility for cleaning a
- <productname>Postgres</productname> database.
+ <productname>PostgreSQL</productname> database.
<application>vacuumdb</application> will also generate internal statistics
- used by the <productname>Postgres</productname> query optimizer.
+ used by the <productname>PostgreSQL</productname> query optimizer.
</para>
<para>
<application>vacuumdb</application> is a shell script wrapper around the
backend command
<xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via
- the <productname>Postgres</productname> interactive terminal
+ the <productname>PostgreSQL</productname> interactive terminal
<xref linkend="APP-PSQL">. There is no effective
difference between vacuuming databases via this or other methods.
<application>psql</application> must be found by the script and
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/regress.sgml,v 1.21 2001/09/21 18:37:05 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/regress.sgml,v 1.22 2001/11/28 20:49:10 petere Exp $ -->
<chapter id="regress">
<title id="regress-title">Regression Tests</title>
<prompt>root# </prompt><userinput>chmod -R a+w src/test/regress</userinput>
<prompt>root# </prompt><userinput>chmod -R a+w contrib/spi</userinput>
<prompt>root# </prompt><userinput>su - joeuser</userinput>
-<prompt>joeuser$ </prompt><userinput>cd <build top-level directory></userinput>
+<prompt>joeuser$ </prompt><userinput>cd <replaceable>top-level build directory</></userinput>
<prompt>joeuser$ </prompt><userinput>gmake check</userinput>
</screen>
(The only possible <quote>security risk</quote> here is that other
<para>
Some of the queries in the <filename>timestamp</filename> test will
- fail if you run the test on the day of a daylight-savings time
+ fail if you run the test on the day of a daylight-saving time
changeover, or the day before or after one. These queries assume
that the intervals between midnight yesterday, midnight today and
midnight tomorrow are exactly twenty-four hours -- which is wrong
- if daylight-savings time went into or out of effect meanwhile.
+ if daylight-saving time went into or out of effect meanwhile.
</para>
<para>
<para>
Some systems using older time zone libraries fail to apply
- daylight-savings corrections to dates before 1970, causing
+ daylight-saving corrections to dates before 1970, causing
pre-1970 <acronym>PDT</acronym> times to be displayed in <acronym>PST</acronym> instead. This will
result in localized differences in the test results.
</para>
<para>
For example: some systems using older time zone libraries fail to apply
- daylight-savings corrections to dates before 1970, causing
+ daylight-saving corrections to dates before 1970, causing
pre-1970 <acronym>PDT</acronym> times to be displayed in <acronym>PST</acronym> instead. This causes a
few differences in the <filename>horology</> regression test.
Therefore, we provide a variant comparison file,
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.98 2001/11/28 00:13:30 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.99 2001/11/28 20:49:10 petere Exp $
-->
<Chapter Id="runtime">
file system location of your database system is indicated by the
<option>-D</option> option, for example
<screen>
-> <userinput>initdb -D /usr/local/pgsql/data</userinput>
+<prompt>$</> <userinput>initdb -D /usr/local/pgsql/data</userinput>
</screen>
Note that you must execute this command while being logged in to
the <productname>PostgreSQL</productname> user account, which is described in the previous
root# <userinput>mkdir /usr/local/pgsql/data</userinput>
root# <userinput>chown postgres /usr/local/pgsql/data</userinput>
root# <userinput>su postgres</userinput>
-postgres> <userinput>initdb -D /usr/local/pgsql/data</userinput>
+postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
</screen>
</para>
<literal>LC_ALL</literal> or <literal>LANG</literal>. The sort order used
within a particular database cluster is set by <command>initdb</command>
and cannot be changed later, short of dumping all data, rerunning <command>initdb</command>,
- reload data. So it's important to make this choice correctly now.
+ and reloading the data. So it's important to make this choice correctly now.
</para>
</sect1>
to work on. This is done with the <option>-D</option> option. Thus,
the simplest way to start the server is, for example,
<screen>
-> <userinput>postmaster -D /usr/local/pgsql/data</userinput>
+$ <userinput>postmaster -D /usr/local/pgsql/data</userinput>
</screen>
which will leave the server running in the foreground. This must
again be done while logged in to the <productname>PostgreSQL</productname> user account. Without
To start the <application>postmaster</application> in the
background, use the usual shell syntax:
<screen>
-> <userinput>postmaster -D /usr/local/pgsql/data > logfile 2>&1 &</userinput>
+$ <userinput>postmaster -D /usr/local/pgsql/data > logfile 2>&1 &</userinput>
</screen>
It is an extremely good idea to keep the server's stdout and stderr
output around somewhere, as suggested here. It will help both for auditing
purposes and to diagnose problems.
(See <xref linkend="logfile-maintenance"> for a more thorough discussion
- of logfile handling.)
+ of log file handling.)
</para>
<para>
<primary>TCP/IP</primary>
</indexterm>
The postmaster also takes a number of other command line options.
- For more information see the reference page and below under runtime
- configuration. In particular, in order for the postmaster to accept
+ For more information see the reference page and <xref linkend="runtime-config"> below.
+ In particular, in order for the server to accept
TCP/IP connections (rather than just Unix domain socket ones), you
must also specify the <option>-i</option> option.
</para>
example, trying to start a postmaster on a reserved port number
may draw something like
<screen>
-> <userinput>postmaster -i -p 666</userinput>
+$ <userinput>postmaster -i -p 666</userinput>
FATAL: StreamServerPort: bind() failed: Permission denied
Is another postmaster already running on that port?
</screen>
<para>
Although the possible error conditions on the client side are
- both virtually infinite and application dependent, a few of them
+ both virtually infinite and application-dependent, a few of them
might be directly related to how the server was started up.
Conditions other than those shown below should be documented with
the respective client application.
This is the generic <quote>I couldn't find a server to talk
to</quote> failure. It looks like the above when TCP/IP
communication is attempted. A common mistake is to forget the
- <option>-i</option> to the postmaster to allow TCP/IP
+ <option>-i</option> option to allow the postmaster to accept TCP/IP
connections.
</para>
<term><varname>ENABLE_INDEXSCAN</varname> (<type>boolean</type>)</term>
<listitem>
<para>
- Enables or disables the query planner's use of index scan plan
+ Enables or disables the query planner's use of index-scan plan
types. The default is on. This is mostly useful to debug the
query planner.
</para>
<listitem>
<para>
Use genetic query optimization to plan queries with at least
- this many FROM items involved. (Note that a JOIN construct
- counts as only one FROM item.) The default is 11. For simpler
+ this many <literal>FROM</> items involved. (Note that a <literal>JOIN</> construct
+ counts as only one <literal>FROM</> item.) The default is 11. For simpler
queries it is usually best to use the
deterministic, exhaustive planner. This parameter also controls
how hard the optimizer will try to merge subquery
<para>
The <firstterm>Key Set Query Optimizer</firstterm>
(<acronym>KSQO</acronym>) causes the query planner to convert
- queries whose WHERE clause contains many OR'ed AND clauses
+ queries whose <literal>WHERE</> clause contains many OR'ed AND clauses
(such as <literal>WHERE (a=1 AND b=2) OR (a=2 AND b=3)
- ...</literal>) into a UNION query. This method can be faster
+ ...</literal>) into a union query. This method can be faster
than the default implementation, but it doesn't necessarily
- give exactly the same results, since UNION implicitly adds a
- SELECT DISTINCT clause to eliminate identical output rows.
+ give exactly the same results, since <literal>UNION</> implicitly adds a
+ <literal>SELECT DISTINCT</> clause to eliminate identical output rows.
<acronym>KSQO</acronym> is commonly used when working with products like
<productname>Microsoft Access</productname>, which tend to
generate queries of this form.
with many OR'ed AND clauses, but in
<productname>PostgreSQL</productname> 7.0 and later the standard
planner handles these queries fairly successfully. Hence the
- default is OFF.
+ default is off.
</para>
</listitem>
</varlistentry>
To use this option, the macro <literal>USE_ASSERT_CHECKING</literal>
must be defined when <productname>PostgreSQL</productname> is built (see the configure option
<literal>--enable-cassert</literal>). Note that
- <literal>DEBUG_ASSERTIONS</literal> defaults to
ON if <productname>PostgreSQL</productname>
+ <literal>DEBUG_ASSERTIONS</literal> defaults to
on if <productname>PostgreSQL</productname>
has been built this way.
</para>
</listitem>
<listitem>
<para>
Minimum number of concurrent open transactions to require before
- performing the COMMIT_DELAY delay. A larger value makes it more
+ performing the <varname>COMMIT_DELAY</> delay. A larger value makes it more
probable that at least one other transaction will become ready to
commit during the delay interval.
</para>
passed to the individual backend process via the
<option>-o</option> postmaster option, for example,
<screen>
-> <userinput>postmaster -o '-S 1024 -s'</userinput>
+$ <userinput>postmaster -o '-S 1024 -s'</userinput>
</screen>
or via <envar>PGOPTIONS</envar> from the client side, as explained
above.
<filename>postmaster.pid</filename> in the data directory. So for
example, to do a fast shutdown:
<screen>
-> <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput>
+$ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput>
</screen>
</para>
<para>
<acronym>SSL</> to encrypt
client/server communications for increased security. This requires
<productname>OpenSSL</productname> to be installed on both client
- and server systems and support enabled at build-time (see <xref
+ and server systems and support enabled at build time (see <xref
linkend="installation">).
</para>
<para>
With SSL support compiled in, the <productname>PostgreSQL</> server
can be started with the argument <option>-l</> (ell) to enable
- SSL connections. When starting in SSL mode, the postmaster will look
+ SSL connections. When starting in SSL mode, the server will look
for the files <filename>server.key</> and <filename>server.crt</> in
the data directory. These files should contain the server private key
and certificate respectively. These files must be set up correctly
before an SSL-enabled server can start. If the private key is protected
- with a passphrase, the postmaster will prompt for the passphrase and will
+ with a passphrase, the server will prompt for the passphrase and will
not start until it has been entered.
</para>
<para>
- The postmaster will listen for both standard and SSL connections
+ The server will listen for both standard and SSL connections
on the same TCP/IP port, and will negotiate with any connecting
client whether or not to use SSL.
See <xref linkend="client-authentication">
refer to the <productname>OpenSSL</> documentation. A simple self-signed
certificate can be used to get started for testing, but a certificate signed
by a <acronym>CA</> (either one of the global <acronym>CAs</> or a local one) should be used in
- production so the client can verify the servers identity. To create
+ production so the client can verify the server's identity. To create
a quick self-signed certificate, use the following <productname>OpenSSL</productname> command:
<programlisting>
openssl req -new -text -out cert.req
left blank. The script will generate a key that is passphrase protected;
it will not accept a pass phrase that is less than four characters long.
To remove the passphrase (as you must if you want automatic start-up of
- the postmaster), run the commands
+ the server), run the commands
<programlisting>
openssl rsa -in privkey.pem -out cert.pem
</programlisting>
cp cert.cert <replaceable>$PGDATA</replaceable>/server.crt
</programlisting>
to turn the certificate into a self-signed certificate and to copy the
- key and certificate to where the postmaster will look for them.
+ key and certificate to where the server will look for them.
</para>
</sect1>
<command>ssh</command> as some user. Then you can establish a secure tunnel with a
command like this from the client machine:
<programlisting>
-> <userinput>ssh -L 3333:foo.com:5432 joe@foo.com</userinput>
+$ <userinput>ssh -L 3333:foo.com:5432 joe@foo.com</userinput>
</programlisting>
The first number in the <option>-L</option> argument, 3333, is the
port number of your end of the tunnel; it can be chosen freely. The
second number, 5432, is the remote end of the tunnel -- the port
- number your backend is using. The name or the address in between
+ number your server is using. The name or the address in between
the port numbers is the host with the database server you are going
to connect to. In order to connect to the database server using
this tunnel, you connect to port 3333 on the local machine:
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.20 2001/11/23 21:08:51 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.21 2001/11/28 20:49:10 petere Exp $
-->
<chapter id="tutorial-start">
Before we proceed, you should understand the basic
<productname>PostgreSQL</productname> system architecture.
Understanding how the parts of
- <productname>PostgreSQL</productname> interact will make the next
+ <productname>PostgreSQL</productname> interact will make this
chapter somewhat clearer.
</para>
over a TCP/IP network connection. You should keep this in mind,
because the files that can be accessed on a client machine might
not be accessible (or might only be accessible using a different
- file path) on the database server machine.
+ file name) on the database server machine.
</para>
<para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.52 2001/11/21 06:09:45 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.53 2001/11/28 20:49:10 petere Exp $
-->
<chapter id="sql-syntax">
for the type, as recorded in its <literal>pg_type</literal>
entry. (For all built-in types, this is the comma character
<quote><literal>,</literal></>.) Each <replaceable>val</replaceable> is either a constant
- of the array element type, or a sub-array. An example of an
+ of the array element type, or a subarray. An example of an
array constant is
<programlisting>
'{{1,2,3},{4,5,6},{7,8,9}}'
</programlisting>
- This constant is a two-dimensional, 3 by 3 array consisting of three
- sub-arrays of integers.
+ This constant is a two-dimensional, 3-by-3 array consisting of three
+ subarrays of integers.
</para>
<para>
<para>
Command identifiers are also 32-bit quantities. This creates a hard
- limit of 2^32 (4 billion) SQL commands within a single transaction.
+ limit of 2<superscript>32</> (4 billion) SQL commands within a single transaction.
In practice this limit is not a problem --- note that the limit is on
number of SQL queries, not number of tuples processed.
</para>
<replaceable>correlation</replaceable> is either the name of a
table, an alias for a table defined by means of a FROM clause, or
- the keyword <literal>NEW</literal> or <literal>OLD</literal>.
+ the key words <literal>NEW</literal> or <literal>OLD</literal>.
(NEW and OLD can only appear in the action portion of a rule,
while other correlation names can be used in any SQL statement.)
The correlation name can be omitted if the column name is unique
<para>
The <productname>PostgreSQL</productname> scanner/parser decodes lexical
-elements into only five fundamental categories: integers, floats, strings,
-names, and keywords. Most extended types are first tokenized into
+elements into only five fundamental categories: integers, floating-point numbers, strings,
+names, and key words. Most extended types are first tokenized into
strings. The <acronym>SQL</acronym> language definition allows specifying type
names with strings, and this mechanism can be used in
<productname>PostgreSQL</productname> to start the parser down the correct
<listitem>
<para>
<productname>PostgreSQL</productname> allows expressions with
-prefix and postfix unary (one argument) operators,
-as well as binary (two argument) operators.
+prefix and postfix unary (one-argument) operators,
+as well as binary (two-argument) operators.
</para>
</listitem>
</varlistentry>
<note>
<para>
Actually, the parser is aware that <type>text</type> and <type>varchar</type>
-are <firstterm>binary compatible</>, meaning that one can be passed to a function that
+are <firstterm>binary-compatible</>, meaning that one can be passed to a function that
accepts the other without doing any physical conversion. Therefore, no
explicit type conversion call is really inserted in this case.
</para>
</synopsis>
<replaceable>name</replaceable> follows the rules for SQL
identifiers: either unadorned without special characters, or
- double-quoted. To remove an existing user, use the analog
+ double-quoted. To remove an existing user, use the analogous
<command>DROP USER</command> command.
</para>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.13 2001/11/21 06:09:45 thomas Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.14 2001/11/28 20:49:10 petere Exp $ -->
<chapter id="wal">
<title>Write-Ahead Logging (<acronym>WAL</acronym>)</title>
<orderedlist>
<listitem>
- <simpara>index tuples pointing to non-existent table rows</simpara>
+ <simpara>index tuples pointing to nonexistent table rows</simpara>
</listitem>
<listitem>
<para>
<acronym>WAL</acronym> logs are stored in the directory
<Filename><replaceable>$PGDATA</replaceable>/pg_xlog</Filename>, as
- a set of segment files, each 16MB in size. Each segment is
- divided into 8KB pages. The log record headers are described in
+ a set of segment files, each 16 MB in size. Each segment is
+ divided into 8 kB pages. The log record headers are described in
<filename>access/xlog.h</filename>; record content is dependent on
the type of event that is being logged. Segment files are given
ever-increasing numbers as names, starting at
shared memory, and are handled by the backends; they are protected
by lightweight locks. The demand on shared memory is dependent on the
number of buffers. The default size of the <acronym>WAL</acronym>
- buffers is 8 8KB buffers, or 64KB.
+ buffers is 8 buffers of 8 kB each, or 64 kB total.
</para>
<para>
corruption of <filename>pg_control</filename>, we should actually
implement the reading of existing log segments in reverse order --
newest to oldest -- in order to find the last checkpoint. This has
- not yet been done in release 7.1.
+ not been implemented, yet.
</para>
</sect2>
</sect1>
</para>
<para>
- Setting the <varname>WAL_DEBUG</varname> parameter to any non-zero
+ Setting the <varname>WAL_DEBUG</varname> parameter to any nonzero
value will result in each <function>LogInsert</function> and
<function>LogFlush</function> <acronym>WAL</acronym> call being
logged to standard error. At present, it makes no difference what
- the non-zero value is. This option may be replaced by a more
+ the nonzero value is. This option may be replaced by a more
general mechanism in the future.
</para>
</sect1>
projects / postgresql / commitdiff