<!--
-$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">
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>
<!--
-$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
-<!-- $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>
<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>
<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><</literal></member>
<member><literal><=</literal></member>
<member><literal>=</literal></member>
<member><literal>>=</literal></member>
<member><literal>></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>
'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>
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><<</literal></member>
<member><literal>&<</literal></member>
<member><literal>&></literal></member>
<member><literal>~=</literal></member>
<member><literal>&&</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>
</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
standard R-trees using Guttman's quadratic split algorithm. The
-<!-- $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</>]]>
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">
<!--
-$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">
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>
<!--
-$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">
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>
<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.
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>
<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>
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>
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>
</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">
<!--
-$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">
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
</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>
<!--
-$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">
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>
<!--
-$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">
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
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">
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>
<!--
-$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">
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>
</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>
</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
fixed ID 1, and by default (unless altered when running
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.
<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>
<!--
-$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">
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>
<!--
-$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">
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.
OSDN Git Service
