From b5adf46cbd18f1825d743c8d905f46bb3a4f4fc5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 8 Jan 2005 22:13:38 +0000 Subject: [PATCH] Some more small improvements in response to 7.4 interactive docs comments. --- doc/src/sgml/ecpg.sgml | 5 +- doc/src/sgml/gist.sgml | 12 ++++- doc/src/sgml/indices.sgml | 41 +++++++++++----- doc/src/sgml/installation.sgml | 8 ++- doc/src/sgml/libpq.sgml | 3 +- doc/src/sgml/lobj.sgml | 89 ++++++++++++++++++++-------------- doc/src/sgml/manage-ag.sgml | 36 ++++++++++++-- doc/src/sgml/plpgsql.sgml | 10 +++- doc/src/sgml/runtime.sgml | 14 ++++-- doc/src/sgml/user-manag.sgml | 50 +++++++++++++++---- doc/src/sgml/xfunc.sgml | 12 ++++- doc/src/sgml/xtypes.sgml | 7 +-- 12 files changed, 209 insertions(+), 78 deletions(-) diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index e2e4c30899..173c4f9c73 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1,5 +1,5 @@ @@ -1106,7 +1106,8 @@ struct the error message that is stored in sqlca.sqlerrm.sqlerrmc (the result of strlen(), not really interesting for a C - programmer). + programmer). Note that some messages are too long to fit in the + fixed-size sqlerrmc array; they will be truncated. diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml index d19dcb8096..584b7be5d8 100644 --- a/doc/src/sgml/gist.sgml +++ b/doc/src/sgml/gist.sgml @@ -1,14 +1,22 @@ - + GiST Indexes Introduction + + index + GiST + + + GiST + index + GiST 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 diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index e37d2b85e8..85cabecf05 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -1,4 +1,4 @@ - + Indexes @@ -106,8 +106,13 @@ CREATE INDEX test1_id_index ON test1 (id); PostgreSQL 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 CREATE INDEX command will create a + B-tree index, which fits the most common situations. + + + index B-tree @@ -116,21 +121,24 @@ CREATE INDEX test1_id_index ON test1 (id); B-tree index - By default, the CREATE INDEX 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 PostgreSQL query planner + B-trees can handle equality and range queries on data that can be sorted + into some ordering. + In particular, the PostgreSQL query planner will consider using a B-tree index whenever an indexed column is involved in a comparison using one of these operators: - + < <= = >= > + + Constructs equivalent to combinations of these operators, such as + BETWEEN and IN, can also be implemented with + a B-tree index search. (But note that IS NULL is not + equivalent to = and is not indexable.) @@ -142,8 +150,8 @@ CREATE INDEX test1_id_index ON test1 (id); 'foo%' or col ~ '^foo', but not col LIKE '%bar'. However, if your server does not use the C locale you will need to create the index with a - special operator class. See - below. + special operator class to support indexing of pattern-matching queries. + See below. @@ -164,7 +172,7 @@ CREATE INDEX name ON table consider using an R-tree index whenever an indexed column is involved in a comparison using one of these operators: - + << &< &> @@ -173,7 +181,8 @@ CREATE INDEX name ON table ~= && - (Refer to about the meaning of + + (See for the meaning of these operators.) @@ -204,6 +213,14 @@ CREATE INDEX name ON table + + 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 operator + class). For more information see . + + The B-tree index method is an implementation of Lehman-Yao high-concurrency B-trees. The R-tree index method implements diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index b732dfa9f1..3c0978a8e2 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,4 +1,4 @@ - + <![%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"> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 61824b63e5..4dbeda993e 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ <!-- -$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> diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index d2b7b06f57..1c40835db4 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -1,5 +1,5 @@ <!-- -$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 - To open an existing large object, call + To open an existing large object for reading or writing, call int lo_open(PGconn *conn, Oid lobjId, int mode); @@ -186,11 +189,13 @@ int lo_open(PGconn *conn, Oid lobjId, int mode); object is opened for reading (INV_READ), writing (INV_WRITE), or both. A large object cannot be opened before it is created. - lo_open returns a large object descriptor - for later use in lo_read, lo_write, - lo_lseek, lo_tell, and - lo_close. The descriptor is only valid for + lo_open returns a (non-negative) large object + descriptor for later use in lo_read, + lo_write, lo_lseek, + lo_tell, and lo_close. + The descriptor is only valid for the duration of the current transaction. + On failure, -1 is returned. @@ -246,7 +251,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence); are SEEK_SET (seek from object start), SEEK_CUR (seek from current position), and SEEK_END (seek from object end). The return value is - the new location pointer. + the new location pointer, or -1 on error. @@ -294,46 +299,56 @@ int lo_unlink(PGconn *conn, Oid lobjId); lo_unlink The lobjId 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. - Server-Side Functions - - There are two built-in server-side functions, - lo_importlo_import - and - lo_export,lo_export - for large object access, which are available for use in - SQL commands. Here is an example of their - use: + + 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 + lo_creatlo_creat, + lo_unlinklo_unlink, + lo_importlo_import, and + lo_exportlo_export. + Here are examples of their use: + 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'; - - - -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.) - + + + + The server-side lo_import and + lo_export 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 + PostgreSQL user. + diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml index 0deb3cc8b1..49aa764192 100644 --- a/doc/src/sgml/manage-ag.sgml +++ b/doc/src/sgml/manage-ag.sgml @@ -1,5 +1,5 @@ @@ -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 . + + Databases are created with the CREATE DATABASE command + (see ) and destroyed with the + DROP DATABASE command + (see ). + To determine the set of existing databases, examine the + pg_database system catalog, for example + +SELECT datname FROM pg_database; + + The program's \l meta-command + and + The SQL standard calls databases catalogs, but there @@ -444,8 +459,23 @@ CREATE TABLE foo(i int); - To simplify the implementation of tablespaces, - PostgreSQL makes extensive use of symbolic links. This + To remove an empty tablespace, use the + command. + + + + To determine the set of existing tablespaces, examine the + pg_tablespace system catalog, for example + +SELECT spcname FROM pg_tablespace; + + The program's \db meta-command + is also useful for listing the existing tablespaces. + + + + PostgreSQL makes extensive use of symbolic links + to simplify the implementation of tablespaces. This means that tablespaces can be used only on systems that support symbolic links. diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 96d68d6d5b..c7f46d613b 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,5 +1,5 @@ @@ -2715,6 +2715,14 @@ AFTER INSERT OR UPDATE OR DELETE ON emp into groups. + + + + 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. + + diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index eaf050a7bf..49148f16c2 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ @@ -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 /usr/local/pgsql/data or /var/lib/pgsql/data are popular. To initialize a - database cluster, use the command initdb,initdb which is + database cluster, use the command ,initdb which is installed with PostgreSQL. The desired file system location of your database cluster is indicated by the option, for example @@ -149,6 +150,12 @@ postgres$ initdb -D /usr/local/pgsql/data other than C or POSIX. Therefore, it is important to make this choice correctly the first time. + + + initdb also sets the default character set encoding + for the database cluster. Normally this should be chosen to match the + locale setting. For details see . + @@ -3474,7 +3481,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' present. The default is true for compatibility with previous releases of PostgreSQL. However, this behavior is not SQL-standard, and many people dislike it because it - can mask mistakes. Set to false for the SQL-standard + can mask mistakes (such as referencing a table where you should have + referenced its alias). Set to false for the SQL-standard behavior of rejecting references to tables that are not listed in FROM. diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml index c09d2facda..19e4489170 100644 --- a/doc/src/sgml/user-manag.sgml +++ b/doc/src/sgml/user-manag.sgml @@ -1,5 +1,5 @@ @@ -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 CREATE - USER SQL command: + per individual database). To create a user use the SQL command: CREATE USER name; name follows the rules for SQL identifiers: either unadorned without special characters, or double-quoted. To remove an existing user, use the analogous - DROP USER command: + command: DROP USER name; @@ -62,8 +62,8 @@ DROP USER name; - For convenience, the programs createuser - and dropuser are provided as wrappers + For convenience, the programs + and are provided as wrappers around these SQL commands that can be called from the shell command line: @@ -72,6 +72,16 @@ dropuser name + + To determine the set of existing users, examine the pg_user + system catalog, for example + +SELECT usename FROM pg_user; + + The program's \du meta-command + is also useful for listing the existing users. + + 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 name is determined by the client authentication setup, as explained in . (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; 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 SQL command: CREATE GROUP name; - To add users to or remove users from a group, use + + To add users to or remove users from an existing group, use : ALTER GROUP name ADD USER uname1, ... ; ALTER GROUP name DROP USER uname1, ... ; + + To destroy a group, use : + +DROP GROUP name; + + This only drops the group, not its member users. + + + + To determine the set of existing groups, examine the pg_group + system catalog, for example + +SELECT groname FROM pg_group; + + The program's \dg meta-command + is also useful for listing the existing groups. diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index bd70eb016b..06eef22db5 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1,5 +1,5 @@ @@ -161,7 +161,15 @@ SELECT clean_emp(); refers to the first argument, $2 to the second, and so on. If an argument is of a composite type, then the dot notation, e.g., $1.name, 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: + +INSERT INTO mytable VALUES ($1); + +but this will not work: + +INSERT INTO $1 VALUES (42); + diff --git a/doc/src/sgml/xtypes.sgml b/doc/src/sgml/xtypes.sgml index 4c07b2e681..6061571c62 100644 --- a/doc/src/sgml/xtypes.sgml +++ b/doc/src/sgml/xtypes.sgml @@ -1,5 +1,5 @@ @@ -240,8 +240,9 @@ CREATE TYPE complex ( data: the first four bytes must be an int32 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 - GETARG macros). Then, + toasted values they are handed, by using PG_DETOAST_DATUM. + (This detail is customarily hidden by defining type-specific + GETARG macros.) Then, when running the CREATE TYPE command, specify the internal length as variable and select the appropriate storage option. -- 2.40.0