Skip to content

P
Postgres FD Implementation
Commit b5adf46c authored by Tom Lane's avatar Tom Lane
Browse files
Options

Some more small improvements in response to 7.4 interactive docs comments.

parent b19011e1
Hide whitespace changes
Inline Side-by-side
Showing with 209 additions and 78 deletions
doc/src/sgml/ecpg.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.61 2005/01/07 05:43:28 momjian Exp $
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62 2005/01/08 22:13:25 tgl Exp $
-->
<chapter id="ecpg">
......@@ -1106,7 +1106,8 @@ struct
the error message that is stored in
<literal>sqlca.sqlerrm.sqlerrmc</literal> (the result of
<function>strlen()</function>, not really interesting for a C
programmer).
programmer). Note that some messages are too long to fit in the
fixed-size <literal>sqlerrmc</literal> array; they will be truncated.
</para>
<para>
......
doc/src/sgml/gist.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.14 2003/11/29 19:51:37 pgsql Exp $
$PostgreSQL: pgsql/doc/src/sgml/gist.sgml,v 1.15 2005/01/08 22:13:25 tgl Exp $
-->
<chapter Id="GiST">
<chapter id="GiST">
<title>GiST Indexes</title>
<sect1 id="intro">
<title>Introduction</title>
<para>
<indexterm>
<primary>index</primary>
<secondary>GiST</secondary>
</indexterm>
<indexterm>
<primary>GiST</primary>
<see>index</see>
</indexterm>
<acronym>GiST</acronym> stands for Generalized Search Tree. It is a
balanced, tree-structured access method, that acts as a base template in
which to implement arbitrary indexing schemes. B+-trees, R-trees and many
......
doc/src/sgml/indices.sgml
View file @ b5adf46c
<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.48 2004/12/23 23:07:38 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.49 2005/01/08 22:13:25 tgl Exp $ -->
<chapter id="indexes">
<title id="indexes-title">Indexes</title>
......@@ -106,8 +106,13 @@ CREATE INDEX test1_id_index ON test1 (id);
<para>
<productname>PostgreSQL</productname> provides several index types:
B-tree, R-tree, GiST, and Hash. Each index type uses a different
B-tree, R-tree, Hash, and GiST. Each index type uses a different
algorithm that is best suited to different types of queries.
By default, the <command>CREATE INDEX</command> command will create a
B-tree index, which fits the most common situations.
</para>
<para>
<indexterm>
<primary>index</primary>
<secondary>B-tree</secondary>
......@@ -116,21 +121,24 @@ CREATE INDEX test1_id_index ON test1 (id);
<primary>B-tree</primary>
<see>index</see>
</indexterm>
By default, the <command>CREATE INDEX</command> command will create a
B-tree index, which fits the most common situations. B-trees can
handle equality and range queries on data that can be sorted into
some ordering. In
particular, the <productname>PostgreSQL</productname> query planner
B-trees can handle equality and range queries on data that can be sorted
into some ordering.
In particular, the <productname>PostgreSQL</productname> query planner
will consider using a B-tree index whenever an indexed column is
involved in a comparison using one of these operators:
<simplelist type="inline">
<simplelist>
<member><literal>&lt;</literal></member>
<member><literal>&lt;=</literal></member>
<member><literal>=</literal></member>
<member><literal>&gt;=</literal></member>
<member><literal>&gt;</literal></member>
</simplelist>
Constructs equivalent to combinations of these operators, such as
<literal>BETWEEN</> and <literal>IN</>, can also be implemented with
a B-tree index search. (But note that <literal>IS NULL</> is not
equivalent to <literal>=</> and is not indexable.)
</para>
<para>
......@@ -142,8 +150,8 @@ CREATE INDEX test1_id_index ON test1 (id);
'foo%'</literal> or <literal>col ~ '^foo'</literal>, but not
<literal>col LIKE '%bar'</literal>. However, if your server does
not use the C locale you will need to create the index with a
special operator class. See <xref linkend="indexes-opclass">
below.
special operator class to support indexing of pattern-matching queries.
See <xref linkend="indexes-opclass"> below.
</para>
<para>
......@@ -164,7 +172,7 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
consider using an R-tree index whenever an indexed column is
involved in a comparison using one of these operators:
<simplelist type="inline">
<simplelist>
<member><literal>&lt;&lt;</literal></member>
<member><literal>&amp;&lt;</literal></member>
<member><literal>&amp;&gt;</literal></member>
......@@ -173,7 +181,8 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
<member><literal>~=</literal></member>
<member><literal>&amp;&amp;</literal></member>
</simplelist>
(Refer to <xref linkend="functions-geometry"> about the meaning of
(See <xref linkend="functions-geometry"> for the meaning of
these operators.)
</para>
......@@ -204,6 +213,14 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
</note>
</para>
<para>
GiST indexes are not a single kind of index, but rather an infrastructure
within which many different indexing strategies can be implemented.
Accordingly, the particular operators with which a GiST index can be
used vary depending on the indexing strategy (the <firstterm>operator
class</>). For more information see <xref linkend="GiST">.
</para>
<para>
The B-tree index method is an implementation of Lehman-Yao
high-concurrency B-trees. The R-tree index method implements
......
doc/src/sgml/installation.sgml
View file @ b5adf46c
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.224 2005/01/08 09:54:47 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.225 2005/01/08 22:13:26 tgl Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
......@@ -12,7 +12,11 @@
This <![%standalone-include;[document]]>
<![%standalone-ignore;[chapter]]> describes the installation of
<productname>PostgreSQL</productname> from the source code
distribution.
distribution. (If you are installing a pre-packaged distribution,
such as an RPM or Debian package, ignore this
<![%standalone-include;[document]]>
<![%standalone-ignore;[chapter]]>
and read the packager's instructions instead.)
</para>
<sect1 id="install-short">
......
doc/src/sgml/libpq.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.176 2005/01/06 21:20:43 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.177 2005/01/08 22:13:28 tgl Exp $
-->
<chapter id="libpq">
......@@ -1264,6 +1264,7 @@ statement, instead of giving a query string.
This feature allows commands
that will be used repeatedly to be parsed and planned just once, rather
than each time they are executed.
The statement must have been prepared previously in the current session.
<function>PQexecPrepared</> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.
</para>
......
doc/src/sgml/lobj.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.34 2004/12/28 22:47:15 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.35 2005/01/08 22:13:33 tgl Exp $
-->
<chapter id="largeObjects">
......@@ -122,15 +122,17 @@ Oid lo_creat(PGconn *conn, int mode);
or'ing together the bits <symbol>INV_READ</symbol> and
<symbol>INV_WRITE</symbol>. The low-order sixteen bits of the mask have
historically been used at Berkeley to designate the storage manager number on which the large object
should reside. These
bits should always be zero now.
The return value is the OID that was assigned to the new large object.
should reside. These bits should always be zero now. (The access type
does not actually do anything anymore either, but one or both flag bits
must be set to avoid an error.)
The return value is the OID that was assigned to the new large object,
or InvalidOid (zero) on failure.
</para>
<para>
An example:
<programlisting>
inv_oid = lo_creat(INV_READ|INV_WRITE);
inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
</programlisting>
</para>
</sect2>
......@@ -147,7 +149,8 @@ Oid lo_import(PGconn *conn, const char *filename);
<replaceable class="parameter">filename</replaceable>
specifies the operating system name of
the file to be imported as a large object.
The return value is the OID that was assigned to the new large object.
The return value is the OID that was assigned to the new large object,
or InvalidOid (zero) on failure.
Note that the file is read by the client interface library, not by
the server; so it must exist in the client filesystem and be readable
by the client application.
......@@ -164,11 +167,11 @@ Oid lo_import(PGconn *conn, const char *filename);
int lo_export(PGconn *conn, Oid lobjId, const char *filename);
</synopsis>
<indexterm><primary>lo_export</></>
The <parameter>lobjId</parameter> argument specifies the OID of the large
object to export and the <parameter>filename</parameter> argument specifies
the operating system name of the file.
Note that the file is written by the client interface library, not by
the server.
The <parameter>lobjId</parameter> argument specifies the OID of the large
object to export and the <parameter>filename</parameter> argument
specifies the operating system name of the file. Note that the file is
written by the client interface library, not by the server. Returns 1
on success, -1 on failure.
</para>
</sect2>
......@@ -176,7 +179,7 @@ int lo_export(PGconn *conn, Oid lobjId, const char *filename);
<title>Opening an Existing Large Object</title>
<para>
To open an existing large object, call
To open an existing large object for reading or writing, call
<synopsis>
int lo_open(PGconn *conn, Oid lobjId, int mode);
</synopsis>
......@@ -186,11 +189,13 @@ int lo_open(PGconn *conn, Oid lobjId, int mode);
object is opened for reading (<symbol>INV_READ</>), writing (<symbol>INV_WRITE</symbol>), or
both.
A large object cannot be opened before it is created.
<function>lo_open</function> returns a large object descriptor
for later use in <function>lo_read</function>, <function>lo_write</function>,
<function>lo_lseek</function>, <function>lo_tell</function>, and
<function>lo_close</function>. The descriptor is only valid for
<function>lo_open</function> returns a (non-negative) large object
descriptor for later use in <function>lo_read</function>,
<function>lo_write</function>, <function>lo_lseek</function>,
<function>lo_tell</function>, and <function>lo_close</function>.
The descriptor is only valid for
the duration of the current transaction.
On failure, -1 is returned.
</para>
</sect2>
......@@ -246,7 +251,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence);
are <symbol>SEEK_SET</> (seek from object start),
<symbol>SEEK_CUR</> (seek from current position), and
<symbol>SEEK_END</> (seek from object end). The return value is
the new location pointer.
the new location pointer, or -1 on error.
</para>
</sect2>
......@@ -294,46 +299,56 @@ int lo_unlink(PGconn *conn, Oid lobjId);
</synopsis>
<indexterm><primary>lo_unlink</></> The
<parameter>lobjId</parameter> argument specifies the OID of the
large object to remove. In the event of an error, the return
value is negative.
large object to remove. Returns 1 if successful, -1 on failure.
</para>
</sect2>
</sect1>
<sect1 id="lo-funcs">
<title>Server-Side Functions</title>
<para>
There are two built-in server-side functions,
<function>lo_import</function><indexterm><primary>lo_import</></>
and
<function>lo_export</function>,<indexterm><primary>lo_export</></>
for large object access, which are available for use in
<acronym>SQL</acronym> commands. Here is an example of their
use:
<para>
There are server-side functions callable from SQL that correspond to
each of the client-side functions described above; indeed, for the
most part the client-side functions are simply interfaces to the
equivalent server-side functions. The ones that are actually useful
to call via SQL commands are
<function>lo_creat</function><indexterm><primary>lo_creat</></>,
<function>lo_unlink</function><indexterm><primary>lo_unlink</></>,
<function>lo_import</function><indexterm><primary>lo_import</></>, and
<function>lo_export</function><indexterm><primary>lo_export</></>.
Here are examples of their use:
<programlisting>
CREATE TABLE image (
name text,
raster oid
);
SELECT lo_creat(-1); -- returns OID of new, empty large object
SELECT lo_unlink(173454); -- deletes large object with OID 173454
INSERT INTO image (name, raster)
VALUES ('beautiful image', lo_import('/etc/motd'));
SELECT lo_export(image.raster, '/tmp/motd') FROM image
WHERE name = 'beautiful image';
</programlisting>
</para>
<para>
These functions read and write files in the server's file system, using the
permissions of the database's owning user. Therefore, their use is restricted
to superusers. (In contrast, the client-side import and export functions
read and write files in the client's file system, using the permissions of
the client program. Their use is not restricted.)
</para>
</para>
<para>
The server-side <function>lo_import</function> and
<function>lo_export</function> functions behave considerably differently
from their client-side analogs. These two functions read and write files
in the server's file system, using the permissions of the database's
owning user. Therefore, their use is restricted to superusers. In
contrast, the client-side import and export functions read and write files
in the client's file system, using the permissions of the client program.
The client-side functions can be used by any
<productname>PostgreSQL</productname> user.
</para>
</sect1>
<sect1 id="lo-examplesect">
......
doc/src/sgml/manage-ag.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.39 2004/12/27 22:30:10 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.40 2005/01/08 22:13:34 tgl Exp $
-->
<chapter id="managing-databases">
......@@ -54,6 +54,21 @@ $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.39 2004/12/27 22:30:10 tgl Ex
managing schemas is in <xref linkend="ddl-schemas">.
</para>
<para>
Databases are created with the <command>CREATE DATABASE</> command
(see <xref linkend="manage-ag-createdb">) and destroyed with the
<command>DROP DATABASE</> command
(see <xref linkend="manage-ag-dropdb">).
To determine the set of existing databases, examine the
<structname>pg_database</> system catalog, for example
<synopsis>
SELECT datname FROM pg_database;
</synopsis>
The <xref linkend="app-psql"> program's <literal>\l</> meta-command
and <option>-l</> command-line option are also useful for listing the
existing databases.
</para>
<note>
<para>
The <acronym>SQL</> standard calls databases <quote>catalogs</>, but there
......@@ -444,8 +459,23 @@ CREATE TABLE foo(i int);
</para>
<para>
To simplify the implementation of tablespaces,
<productname>PostgreSQL</> makes extensive use of symbolic links. This
To remove an empty tablespace, use the <xref linkend="sql-droptablespace">
command.
</para>
<para>
To determine the set of existing tablespaces, examine the
<structname>pg_tablespace</> system catalog, for example
<synopsis>
SELECT spcname FROM pg_tablespace;
</synopsis>
The <xref linkend="app-psql"> program's <literal>\db</> meta-command
is also useful for listing the existing tablespaces.
</para>
<para>
<productname>PostgreSQL</> makes extensive use of symbolic links
to simplify the implementation of tablespaces. This
means that tablespaces can be used <emphasis>only</> on systems
that support symbolic links.
</para>
......
doc/src/sgml/plpgsql.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.54 2004/12/30 21:45:36 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.55 2005/01/08 22:13:34 tgl Exp $
-->
<chapter id="plpgsql">
......@@ -2715,6 +2715,14 @@ AFTER INSERT OR UPDATE OR DELETE ON emp
into groups.
</para>
</listitem>
<listitem>
<para>
Since there are no packages, there are no package-level variables
either. This is somewhat annoying. You may be able to keep per-session
state in temporary tables, instead.
</para>
</listitem>
</itemizedlist>
</para>
......
doc/src/sgml/runtime.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.300 2005/01/04 00:05:44 momjian Exp $
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.301 2005/01/08 22:13:35 tgl Exp $
-->
<Chapter Id="runtime">
......@@ -69,7 +69,8 @@ $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.300 2005/01/04 00:05:44 momjian
default, although locations such as
<filename>/usr/local/pgsql/data</filename> or
<filename>/var/lib/pgsql/data</filename> are popular. To initialize a
database cluster, use the command <command>initdb</command>,<indexterm><primary>initdb</></> which is
database cluster, use the command <xref
linkend="app-initdb">,<indexterm><primary>initdb</></> which is
installed with <productname>PostgreSQL</productname>. The desired
file system location of your database cluster is indicated by the
<option>-D</option> option, for example
......@@ -149,6 +150,12 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
other than <literal>C</> or <literal>POSIX</>. Therefore, it is
important to make this choice correctly the first time.
</para>
<para>
<command>initdb</command> also sets the default character set encoding
for the database cluster. Normally this should be chosen to match the
locale setting. For details see <xref linkend="multibyte">.
</para>
</sect1>
<sect1 id="postmaster-start">
......@@ -3474,7 +3481,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
present. The default is <literal>true</> for compatibility with
previous releases of <productname>PostgreSQL</>. However, this
behavior is not SQL-standard, and many people dislike it because it
can mask mistakes. Set to <literal>false</> for the SQL-standard
can mask mistakes (such as referencing a table where you should have
referenced its alias). Set to <literal>false</> for the SQL-standard
behavior of rejecting references to tables that are not listed in
<literal>FROM</>.
</para>
......
doc/src/sgml/user-manag.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.26 2004/12/27 22:30:10 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.27 2005/01/08 22:13:36 tgl Exp $
-->
<chapter id="user-manag">
......@@ -39,15 +39,15 @@ $PostgreSQL: pgsql/doc/src/sgml/user-manag.sgml,v 1.26 2004/12/27 22:30:10 tgl E
operating system users. In practice it might be convenient to
maintain a correspondence, but this is not required. Database user
names are global across a database cluster installation (and not
per individual database). To create a user use the <command>CREATE
USER</command> SQL command:
per individual database). To create a user use the <xref
linkend="sql-createuser" endterm="sql-createuser-title"> SQL command:
<synopsis>
CREATE USER <replaceable>name</replaceable>;
</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 analogous
<command>DROP USER</command> command:
<xref linkend="sql-dropuser" endterm="sql-dropuser-title"> command:
<synopsis>
DROP USER <replaceable>name</replaceable>;
</synopsis>
......@@ -62,8 +62,8 @@ DROP USER <replaceable>name</replaceable>;
</indexterm>
<para>
For convenience, the programs <command>createuser</command>
and <command>dropuser</command> are provided as wrappers
For convenience, the programs <xref linkend="app-createuser">
and <xref linkend="app-dropuser"> are provided as wrappers
around these SQL commands that can be called from the shell command
line:
<synopsis>
......@@ -72,6 +72,16 @@ dropuser <replaceable>name</replaceable>
</synopsis>
</para>
<para>
To determine the set of existing users, examine the <structname>pg_user</>
system catalog, for example
<synopsis>
SELECT usename FROM pg_user;
</synopsis>
The <xref linkend="app-psql"> program's <literal>\du</> meta-command
is also useful for listing the existing users.
</para>
<para>
In order to bootstrap the database system, a freshly initialized
system always contains one predefined user. This user will have the
......@@ -102,8 +112,8 @@ dropuser <replaceable>name</replaceable>
is determined by the client authentication setup, as explained in
<xref linkend="client-authentication">. (Thus, a client is not
necessarily limited to connect as the user with the same name as
its operating system user, in the same way a person is not
constrained in its login name by her real name.) Since the user
its operating system user, just as a person's login name
need not match her real name.) Since the user
identity determines the set of privileges available to a connected
client, it is important to carefully configure this when setting up
a multiuser environment.
......@@ -195,15 +205,35 @@ ALTER USER myname SET enable_indexscan TO off;
<para>
As in Unix, groups are a way of logically grouping users to ease
management of privileges: privileges can be granted to, or revoked
from, a group as a whole. To create a group, use
from, a group as a whole. To create a group, use the <xref
linkend="sql-creategroup" endterm="sql-creategroup-title"> SQL command:
<synopsis>
CREATE GROUP <replaceable>name</replaceable>;
</synopsis>
To add users to or remove users from a group, use
To add users to or remove users from an existing group, use <xref
linkend="sql-altergroup" endterm="sql-altergroup-title">:
<synopsis>
ALTER GROUP <replaceable>name</replaceable> ADD USER <replaceable>uname1</replaceable>, ... ;
ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</replaceable>, ... ;
</synopsis>
To destroy a group, use <xref
linkend="sql-dropgroup" endterm="sql-dropgroup-title">:
<synopsis>
DROP GROUP <replaceable>name</replaceable>;
</synopsis>
This only drops the group, not its member users.
</para>
<para>
To determine the set of existing groups, examine the <structname>pg_group</>
system catalog, for example
<synopsis>
SELECT groname FROM pg_group;
</synopsis>
The <xref linkend="app-psql"> program's <literal>\dg</> meta-command
is also useful for listing the existing groups.
</para>
</sect1>
......
doc/src/sgml/xfunc.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.94 2005/01/07 23:08:44 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.95 2005/01/08 22:13:36 tgl Exp $
-->
<sect1 id="xfunc">
......@@ -161,7 +161,15 @@ SELECT clean_emp();
refers to the first argument, <literal>$2</> to the second, and so on.
If an argument is of a composite type, then the dot notation,
e.g., <literal>$1.name</literal>, may be used to access attributes
of the argument.
of the argument. The arguments can only be used as data values,
not as identifiers. Thus for example this is reasonable:
<programlisting>
INSERT INTO mytable VALUES ($1);
</programlisting>
but this will not work:
<programlisting>
INSERT INTO $1 VALUES (42);
</programlisting>
</para>
<sect2>
......
doc/src/sgml/xtypes.sgml
View file @ b5adf46c
<!--
$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.23 2003/11/29 19:51:38 pgsql Exp $
$PostgreSQL: pgsql/doc/src/sgml/xtypes.sgml,v 1.24 2005/01/08 22:13:38 tgl Exp $
-->
<sect1 id="xtypes">
......@@ -240,8 +240,9 @@ CREATE TYPE complex (
data: the first four bytes must be an <type>int32</type> containing
the total length in bytes of the datum (including itself). The C
functions operating on the data type must be careful to unpack any
toasted values they are handed (this detail can normally be hidden in the
<function>GETARG</function> macros). Then,
toasted values they are handed, by using <function>PG_DETOAST_DATUM</>.
(This detail is customarily hidden by defining type-specific
<function>GETARG</function> macros.) Then,
when running the <command>CREATE TYPE</command> command, specify the
internal length as <literal>variable</> and select the appropriate
storage option.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment