--- /dev/null
+<!-- allfiles.sgml
+-
+- Complete list of usable sgml source files in this directory.
+-
+- -->
+
+<!entity intro-ref system "intro-ref.sgml">
+<!entity commands system "commands.sgml">
+
+<!-- these will go into the "operators" reference chapter -->
+<!entity all system "all.sgml">
+<!entity any system "any.sgml">
+<!entity between system "between.sgml">
+<!entity in system "in.sgml">
+<!entity like system "like.sgml">
+
+<!-- these will go into the "functions" reference chapter -->
+<!entity avg system "avg.sgml">
+<!entity cast system "cast.sgml">
+<!entity charLength system "char_length.sgml">
+<!entity count system "count.sgml">
+<!entity currentDate system "current_date.sgml">
+<!entity currentTime system "current_time.sgml">
+<!entity currentTimestamp system "current_timestamp.sgml">
+<!entity currentUser system "current_user.sgml">
+<!entity exists system "exists.sgml">
+<!entity extract system "extract.sgml">
+<!entity initcap system "initcap.sgml">
+<!entity lower system "lower.sgml">
+<!entity lpad system "lpad.sgml">
+<!entity max system "max.sgml">
+<!entity min system "min.sgml">
+<!entity position system "position.sgml">
+<!entity rpad system "rpad.sgml">
+<!entity substring system "substring.sgml">
+<!entity sum system "sum.sgml">
+<!entity translate system "translate.sgml">
+<!entity trim system "trim.sgml">
+<!entity upper system "upper.sgml">
+
+<!-- these are folded into create_table.sgml
+<!entity check system "check.sgml">
+<!entity constraints system "constraint.sgml">
+<!entity default system "default.sgml">
+<!entity notNull system "not_null.sgml">
+<!entity primaryKey system "primary_key.sgml">
+<!entity unique system "unique.sgml">
+-->
+
+<!-- these are folded into select.sgml
+<!entity groupBy system "group_by.sgml">
+<!entity having system "having.sgml">
+<!entity orderBy system "order_by.sgml">
+<!entity union system "union.sgml">
+-->
+
+<!-- these are in the "commands" reference chapter -->
+<!entity alterTable system "alter_table.sgml">
+<!entity alterUser system "alter_user.sgml">
+<!entity begin system "begin.sgml">
+<!entity close system "close.sgml">
+<!entity cluster system "cluster.sgml">
+<!entity commit system "commit.sgml">
+<!entity copy system "copy.sgml">
+<!entity createAggregate system "create_aggregate.sgml">
+<!entity createDatabase system "create_database.sgml">
+<!entity createFunction system "create_function.sgml">
+<!entity createIndex system "create_index.sgml">
+<!entity createLanguage system "create_language.sgml">
+<!entity createOperator system "create_operator.sgml">
+<!entity createRule system "create_rule.sgml">
+<!entity createSequence system "create_sequence.sgml">
+<!entity createTable system "create_table.sgml">
+<!entity createTrigger system "create_trigger.sgml">
+<!entity createType system "create_type.sgml">
+<!entity createUser system "create_user.sgml">
+<!entity createView system "create_view.sgml">
+<!entity declare system "declare.sgml">
+<!entity delete system "delete.sgml">
+<!entity dropAggregate system "drop_aggregate.sgml">
+<!entity dropDatabase system "drop_database.sgml">
+<!entity dropFunction system "drop_function.sgml">
+<!entity dropIndex system "drop_index.sgml">
+<!entity dropLanguage system "drop_language.sgml">
+<!entity dropOperator system "drop_operator.sgml">
+<!entity dropRule system "drop_rule.sgml">
+<!entity dropSequence system "drop_sequence.sgml">
+<!entity dropTable system "drop_table.sgml">
+<!entity dropTrigger system "drop_trigger.sgml">
+<!entity dropType system "drop_type.sgml">
+<!entity dropUser system "drop_user.sgml">
+<!entity dropView system "drop_view.sgml">
+<!entity explain system "explain.sgml">
+<!entity fetch system "fetch.sgml">
+<!entity grant system "grant.sgml">
+<!entity insert system "insert.sgml">
+<!entity listen system "listen.sgml">
+<!entity load system "load.sgml">
+<!entity lock system "lock.sgml">
+<!entity move system "move.sgml">
+<!entity notify system "notify.sgml">
+<!entity reset system "reset.sgml">
+<!entity revoke system "revoke.sgml">
+<!entity rollback system "rollback.sgml">
+<!entity select system "select.sgml">
+<!entity set system "set.sgml">
+<!entity show system "show.sgml">
+<!entity update system "update.sgml">
+<!entity vacuum system "vacuum.sgml">
--- /dev/null
+<REFENTRY ID="SQL-ALTERTABLE-1">
+<REFMETA>
+<REFENTRYTITLE>
+ALTER TABLE
+</REFENTRYTITLE>
+<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+ALTER TABLE
+</REFNAME>
+<REFPURPOSE>
+Modifies table properties
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-04-15</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ [*] ADD [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ [*] RENAME [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> TO <REPLACEABLE CLASS="PARAMETER">newcolumn</REPLACEABLE>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ RENAME TO <REPLACEABLE CLASS="PARAMETER">newtable</REPLACEABLE>
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-SQL-ALTERTABLE-1">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER"> table </REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ The name of an existing table to alter.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER"> column </REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ Name of a new or existing column.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER"> type </REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ Type of the new column.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER"> newcolumn </REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ New name for an existing column.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER"> newtable </REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ New name for an existing column.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+</VARIABLELIST>
+
+</REFSECT2>
+
+<REFSECT2 ID="R2-SQL-ALTERTABLE-2">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+<ReturnValue>status</ReturnValue>
+</TERM>
+<LISTITEM>
+<PARA>
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+<ReturnValue>ALTER</ReturnValue>
+</TERM>
+<LISTITEM>
+<PARA>
+ Message returned from column or table renaming.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<ReturnValue>NEW</ReturnValue>
+</TERM>
+<LISTITEM>
+<PARA>
+ Message returned from column addition.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<ReturnValue>ERROR</ReturnValue>
+</TERM>
+<LISTITEM>
+<PARA>
+ Message returned if table or column is not available.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+</VARIABLELIST>
+</LISTITEM>
+</VARLISTENTRY>
+</VARIABLELIST>
+
+</REFSECT2>
+</REFSYNOPSISDIV>
+
+<REFSECT1 ID="R1-SQL-ALTERTABLE-1">
+<REFSECT1INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+ ALTER TABLE changes the definition of an existing table.
+ The new columns and their types are specified in the same style
+ and with the the same restrictions as in CREATE TABLE.
+ The RENAME clause causes the name of a table or column
+ to change without changing any of the data contained in
+ the affected table. Thus, the table or column will
+ remain of the same type and size after this command is
+ executed.
+<PARA>
+ You must own the table in order to change its schema.
+</PARA>
+
+<REFSECT2 ID="R2-SQL-ALTERTABLE-3">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+Notes
+</TITLE>
+<PARA>
+The keyword COLUMN is noise and can be omitted.
+
+<PARA>
+ALTER TABLE/RENAME is a PostgreSQL language extension.
+
+<PARA>
+<Quote>[*]</Quote> following a name of a table indicates that statement
+ should be run over that table and all tables below it in the
+ inheritance hierarchy.
+ Refer to PostgreSQL User's Guide for further
+ information on inheritance.
+
+<PARA>
+ Refer to the CREATE TABLE reference for further description
+ of valid arguments.
+
+</REFSECT2>
+</REFSECT1>
+
+<REFSECT1 ID="R1-SQL-ALTERTABLE-2">
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+ To add a column of type VARCHAR to a table:
+<ProgramListing>
+ ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
+</ProgramListing>
+
+<PARA>
+ To rename an existing column:
+<ProgramListing>
+ ALTER TABLE distributors RENAME COLUMN address TO city;
+</ProgramListing>
+
+<PARA>
+ To rename an existing table:
+<ProgramListing>
+ ALTER TABLE distributors RENAME TO suppliers;
+</ProgramListing>
+
+</REFSECT1>
+
+<REFSECT1 ID="R1-SQL-ALTERTABLE-3">
+<TITLE>
+Compatibility
+</TITLE>
+
+<REFSECT2 ID="R2-SQL-ALTERTABLE-4">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+SQL92
+</TITLE>
+<PARA>
+ SQL92 specifies some additional capabilities for ALTER TABLE
+ statement which are not yet directly supported by <ProductName>Postgres</ProductName>:
+
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+<Synopsis>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
+ SET DEFAULT <REPLACEABLE CLASS="PARAMETER">default</REPLACEABLE>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
+ ADD [CONSTRAINT <REPLACEABLE CLASS="PARAMETER">constraint</REPLACEABLE>] <REPLACEABLE CLASS="PARAMETER">table-constraint</REPLACEABLE>
+</Synopsis>
+</TERM>
+<LISTITEM>
+<PARA>
+ Puts the default value or constraint specified into the
+ definition of column in the table. See CREATE TABLE for the
+ syntax of the default and table-constraint clauses.
+ If a default clause already exists, it will be replaced by
+ the new definition. If any constraints on this column already
+ exist, they will be retained using a boolean AND with the new
+ constraint.
+
+<PARA>
+Currently, to set new default constraints on an existing column
+ the table must be recreated and reloaded:
+
+<ProgramListing>
+CREATE TABLE temp AS SELECT * FROM distributors;
+DROP TABLE distributors;
+CREATE TABLE distributors (
+ did DECIMAL(3) DEFAULT 1,
+ name VARCHAR(40) NOT NULL,
+ city VARCHAR(30)
+);
+INSERT INTO distributors SELECT * FROM temp;
+DROP TABLE temp;
+</ProgramListing>
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<Synopsis>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ DROP DEFAULT <REPLACEABLE CLASS="PARAMETER">default</REPLACEABLE>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ DROP CONSTRAINT <REPLACEABLE CLASS="PARAMETER">constraint</REPLACEABLE> { RESTRICT | CASCADE }
+</Synopsis>
+</TERM>
+<LISTITEM>
+<PARA>
+ Removes the default value specified by default or the rule
+ specified by constraint from the definition of a table.
+ If RESTRICT is specified only a constraint with no dependent
+ constraints can be destroyed.
+ If CASCADE is specified, Any constraints that are dependent on
+ this constraint are also dropped.
+
+<PARA>
+Currently, to remove a default value or constraints on an
+ existing column the table must be recreated and reloaded:
+
+<ProgramListing>
+CREATE TABLE temp AS SELECT * FROM distributors;
+DROP TABLE distributors;
+CREATE TABLE distributors AS SELECT * FROM temp;
+DROP TABLE temp;
+</ProgramListing>
+
+<VARLISTENTRY>
+<TERM>
+<Synopsis>
+ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ DROP [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> { RESTRICT | CASCADE }
+</Synopsis>
+</TERM>
+<LISTITEM>
+<PARA>
+ Removes a column from a table.
+ If RESTRICT is specified only a column with no dependent
+ objects can be destroyed.
+ If CASCADE is specified, all objects that are dependent on
+ this column are also dropped.
+
+<PARA>
+Currently, to remove an existing column the table must be
+ recreated and reloaded:
+
+<ProgramListing>
+CREATE TABLE temp AS SELECT did, city FROM distributors;
+DROP TABLE distributors;
+CREATE TABLE distributors (
+ did DECIMAL(3) DEFAULT 1,
+ name VARCHAR(40) NOT NULL,
+);
+INSERT INTO distributors SELECT * FROM temp;
+DROP TABLE temp;
+</ProgramListing>
+</PARA>
+</VARIABLELIST>
+</REFENTRY>
+
+<!--
+<REPLACEABLE CLASS="PARAMETER">
+</REPLACEABLE>
+<ReturnValue></ReturnValue>
+<PARA>
+</PARA>
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>•
+</TERM>
+<LISTITEM>
+<PARA>
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+</VARIABLELIST>
+<PARA>
+</PARA>
+-->
--- /dev/null
+ <REFENTRY ID="SQL-ALTERUSER-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ ALTER USER
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ ALTER USER
+ </REFNAME>
+ <REFPURPOSE>
+ Modifies user account information
+ </REFPURPOSE>
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <synopsis>
+ ALTER USER <replaceable class="PARAMETER">username</replaceable>
+ [WITH PASSWORD <replaceable class="PARAMETER">password</replaceable>]
+ [CREATEDB | NOCREATEDB]
+ [CREATEUSER | NOCREATEUSER]
+ [IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...] ]
+ [VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>']
+ </synopsis>
+
+ <REFSECT2 ID="R2-SQL-ALTERUSER-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ Refer to CREATE USER statement for a detailed description of each
+ clause.
+ </para>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <REPLACEABLE CLASS="PARAMETER"> username </REPLACEABLE>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The Postgres account name of the user whose details are to be altered.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <REPLACEABLE CLASS="PARAMETER"> password </REPLACEABLE>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The new password to be used for this account.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <REPLACEABLE CLASS="PARAMETER"> groupname </REPLACEABLE>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of an access group into which this account is to be put.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <REPLACEABLE CLASS="PARAMETER"> abstime </REPLACEABLE>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The date (and, optionally, the time) at which this user's access is to be terminated.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-ALTERUSER-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>status</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ALTER USER</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the alteration was successful.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: alterUser: user "username" does not exist</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Error message returned if the user specified doesn't
+ exist.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-ALTERUSER-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ ALTER USER is used to change the attributes of a user's
+ PostgreSQL account. Please note that it is not possible
+ to alter a user's "usesysid" via the alter user
+ statement. Also, it is only possible for the PostgreSQL
+ user or any user with read and modify permissions on
+ "pg_shadow" to alter user passwords.
+ </PARA>
+ <para>
+ If any of the clauses of the alter user statement are
+ omitted, the corresponding value in the "pg_shadow" table
+ is left unchanged.
+ </para>
+
+ <REFSECT2 ID="R2-SQL-ALTERUSER-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ ALTER USER statement is a PostgreSQL language extension.
+ </para>
+ <para>
+ Refer to CREATE/DROP USER statements to create/remove an user
+ account.
+ </para>
+ <para>
+ At the current release (6.3.2), the IN GROUP clause is parsed
+ but has no effect. When it is fully implemented, it is
+ intended to modify the pg_group relation.
+ </para>
+ </REFSECT2>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-ALTERUSER-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ Change a user password
+ </PARA>
+ <ProgramListing>
+ ALTER USER davide WITH PASSWORD hu8jmn3;
+ </ProgramListing>
+ <para>
+ Change a user's valid until date
+ </para>
+ <ProgramListing>
+ ALTER USER manuel VALID UNTIL 'Jan 31 2030';
+ </ProgramListing>
+ <para>
+ Change a user's valid until date, specifying that his
+authorisation should expire at midday on 4th May 1998 using
+the time zone which is one hour ahead of UTC
+ </para>
+ <ProgramListing>
+ ALTER USER chris VALID UNTIL 'May 4 12:00:00 1998 +1';
+ </ProgramListing>
+ <para>
+ Give a user the ability to create other users and new databases.
+ </para>
+ <programlisting>
+ ALTER USER miriam CREATEUSER CREATEDB;
+ </programlisting>
+ <para>
+ Place a user in two groups
+ </para>
+ <programlisting>
+ ALTER USER miriam IN GROUP sales, payroll;
+ </programlisting>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-ALTERUSER-3">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-ALTERUSER-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no ALTER USER statement in SQL92. The standard leaves
+ the definition of users to the implementation.
+ </PARA>
+ </refsect1>
+ </REFENTRY>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-BEGINWORK-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ BEGIN WORK
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ BEGIN WORK
+ </REFNAME>
+ <REFPURPOSE>
+ Begins a transaction
+ </REFPURPOSE>
+
+
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ BEGIN { WORK | TRANSACTION }
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-BEGINWORK-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ None
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <para></para>
+ </LISTITEM>
+ </varlistentry>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-BEGINWORK-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ status
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>BEGIN</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This signifies that a new transaction has been started.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ NOTICE: BeginTransactionBlock and not in default state
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This indicates that a transaction was already in progress.
+ <comment>
+ What happens to command queries already run
+ in the transaction? Does this have no effect, or does
+ it restart the transaction?
+ </comment>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </para>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-BEGINWORK-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <para>
+ BEGIN begins a user transaction which PostgreSQL will
+ guarantee is serialisable with respect to all concurrently
+ executing transactions. PostgreSQL uses two-phase locking
+ to perform this task. If the transaction is committed,
+ PostgreSQL will ensure either that all updates are done orelse
+ that none of
+ them are done. Transactions have the standard ACID
+ (atomic, consistent, isolatable, and durable) property.
+ </para>
+
+ <REFSECT2 ID="R2-SQL-BEGINWORK-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ The keyword TRANSACTION is just a cosmetic alternative to WORK.
+ Neither keyword need be specified.
+ </PARA>
+
+ <PARA>
+ BEGIN statement is a PostgreSQL language extension.
+ </PARA>
+
+ <PARA>
+ Refer to the LOCK statement for further information about locking
+ tables inside a transaction.
+ </PARA>
+
+ <PARA>
+ Use COMMIT or ROLLBACK to terminate a transaction.
+ </PARA>
+ </REFSECT2>
+
+ <REFSECT1 ID="R1-SQL-BEGINWORK-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>To begin a user transaction:
+ </PARA>
+ <ProgramListing>
+ BEGIN WORK;
+ </ProgramListing>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-BEGINWORK-3">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-BEGINWORK-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no explicit "BEGIN WORK" in SQL92; transaction initiation
+ is always implicit and it terminates either with a COMMIT or with
+ a ROLLBACK statement.
+ </PARA>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-CLOSE-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ CLOSE
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ CLOSE
+ </REFNAME>
+ <REFPURPOSE>
+ Close a cursor
+ </REFPURPOSE>
+
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-CLOSE-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of an open cursor to close.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-CLOSE-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ CLOSE
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the cursor is successfully closed.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ NOTICE PerformPortalClose: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>" not found
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This warning is given if
+ <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> is not
+ declared or has already been closed.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-CLOSE-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ CLOSE frees the resources associated with an open cursor.
+ After the cursor is closed, no subsequent operations
+ are allowed on it. A cursor should be closed when it is
+ no longer needed.
+ </PARA>
+ <PARA>
+ An implicit close is executed for every open cursor when a
+ transaction is terminated by COMMIT or ROLLBACK.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CLOSE-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ PostgreSQL does not have an explicit OPEN cursor statement;
+ a cursor is considered open when it is DECLAREd.
+ Use DECLARE to declare a cursor.
+ </PARA>
+ </REFSECT2>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-CLOSE-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ Close the cursor liahona:
+ </PARA>
+ <ProgramListing>
+ CLOSE liahona;
+ </ProgramListing>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CLOSE-3">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CLOSE-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ CLOSE is fully compatibile with SQL92.
+ </PARA>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-CLUSTER-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ CLUSTER
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ CLUSTER
+ </REFNAME>
+ <REFPURPOSE>
+ Gives storage clustering advice to PostgreSQL
+ </REFPURPOSE>
+
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-CLUSTER-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE>
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of an index.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+ </ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of a table.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-CLUSTER-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CLUSTER</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The clustering was done successfully.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: relation <<REPLACEABLE CLASS="PARAMETER">tablerelation_number</REPLACEABLE>> inherits "invoice"</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ ???
+ <comment>
+ This is not documented anywhere. It seems not to be possible to
+ cluster a table that is inherited.
+ </comment>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: Relation x does not exist!</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ ???
+ <comment>
+ The relation complained of was not shown in the error message,
+ which contained a random string instead of the relation name.
+ </comment>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-CLUSTER-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ This command instructs PostgreSQL to cluster the class specified
+ by <replaceable class="parameter">classname</replaceable> approximately
+ based on the index specified by
+ <replaceable class="parameter">indexname</replaceable>. The index must
+ already have been defined on <replaceable class="parameter">classname</replaceable>.
+ </PARA>
+ <para>
+ When a class is clustered, it is physically reordered
+ based on the index information. The clustering is static.
+ In other words, as the class is updated, the changes are
+ not clustered. No attempt is made to keep new instances or
+ updated tuples clustered. If he wishes, the user can
+ recluster manually by issuing the command again.
+ </para>
+
+ <para>
+ The table is actually copied to a temporary table in index
+ order, then renamed back to the original name. For this
+ reason, all grant permissions and other indexes are lost
+ when clustering is performed.
+ </para>
+
+ <para>
+ In cases where you are accessing single rows randomly
+ within a table, the actual order of the data in the heap
+ table is unimportant. However, if you tend to access some
+ data more than others, and there is an index that groups
+ them together, you will benefit from using the CLUSTER
+ command.
+ </para>
+
+ <para>
+ Another place CLUSTER is good is in cases where you use an
+ index to pull out several rows from a table. If you are
+ requesting a range of indexed values from a table, or a
+ single indexed value that has multiple rows that match,
+ CLUSTER will help because once the index identifies the
+ heap page for the first row that matches, all other rows
+ that match are probably already on the same heap page,
+ saving disk accesses and speeding up the query.
+ </para>
+
+ <para>
+ There are two ways to cluster data. The first is with the
+ CLUSTER command, which reorders the original table with
+ the ordering of the index you specify. This can be slow
+ on large tables because the rows are fetched from the heap
+ in index order, and if the heap table is unordered, the
+ entries are on random pages, so there is one disk page
+ retrieved for every row moved. PostgreSQL has a cache,
+ but the majority of a big table will not fit in the cache.
+ </para>
+
+ <para>
+ Another way is to use
+ <programlisting>SELECT ... INTO TABLE temp FROM ... ORDER BY ...</programlisting>
+ This uses the PostgreSQL sorting code in
+ ORDER BY to match the index, and is much faster for
+ unordered data. You then drop the old table, use
+<programlisting>ALTER TABLE RENAME</programlisting>
+ to rename 'temp' to the old name, and
+ recreate the b bindexes. The only problem is that oids
+ will not be preserved. From then on, CLUSTER should be
+ fast because most of the heap data has already been
+ ordered, and the existing index is used.
+ </para>
+
+
+ <REFSECT1 ID="R1-SQL-CLUSTER-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ Cluster the employees relation on the basis of its salary attribute
+ </PARA>
+ <ProgramListing>
+ CLUSTER emp_ind ON emp
+ </ProgramListing>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CLUSTER-3">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CLUSTER-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no CLUSTER statement in SQL92.
+ </PARA>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<Chapter>
+<Title>Commands</Title>
+
+<Para>
+</Para>
+
+&alterTable;
+&alterUser;
+&begin;
+&close;
+&cluster;
+&commit;
+©
+&createAggregate;
+&createDatabase;
+&createFunction;
+&createIndex;
+&createLanguage;
+&dropFunction;
+&select;
+
+</Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
\ No newline at end of file
--- /dev/null
+<REFENTRY ID="SQL-COMMIT-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ COMMIT
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ COMMIT
+ </REFNAME>
+ <REFPURPOSE>
+ Commits the current transaction
+ </REFPURPOSE>
+
+
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ COMMIT [ WORK ]
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-COMMIT-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>None</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-COMMIT-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>END</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+Message returned if the transaction is successfully committed.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>NOTICE EndTransactionBlock and not inprogress/abort state
+</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+If there is no transaction in progress.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-COMMIT-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ COMMIT commits the current transaction. All
+ changes made by the transaction become visible to others
+ and are guaranteed to be durable if a crash occurs.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-COMMIT-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ The keyword WORK is noise and can be omitted.
+ </PARA>
+ <para>
+ Refer to ROLLBACK statements to abort a transaction.
+ </para>
+ </REFSECT2>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-COMMIT-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+To make all changes permanent:
+ </PARA>
+ <ProgramListing>
+ COMMIT WORK;
+ </ProgramListing>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-COMMIT-3">
+ <TITLE>
+ Compatibility
+</TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-COMMIT-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ Full compatibility.
+ </PARA>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-COPY-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ COPY
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ COPY
+ </REFNAME>
+ <REFPURPOSE>
+ Copies data between files and tables
+ </REFPURPOSE>
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ COPY [BINARY] <replaceable class="parameter">table</replaceable> [WITH OIDS]
+ TO|FROM '<replaceable class="parameter">filename</replaceable>'|stdin|stdout
+ [USING DELIMITERS '<replaceable class="parameter">delimiter</replaceable>']
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-COPY-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue><replaceable class="parameter">table</replaceable></ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of a table.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue><replaceable class="parameter">delimiter</replaceable></ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ A character that delimits fields.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-COPY-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ Status
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>COPY</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The copy completed successfully.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: <replaceable>error message</replaceable></ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The copy failed for the reason stated in the error message.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-COPY-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ <command>COPY</command> moves data between PostgreSQL tables and
+ standard Unix files. The keyword <function>BINARY</function>
+ changes the behavior of field formatting, as described
+ below. <replaceable class="parameter">Table</replaceable> is the
+ name of an existing table. The keyword <function>WITH
+ OIDS</function> copies the internal unique object id (OID) for each
+ row. <replaceable class="parameter">Filename</replaceable> is the
+ absolute Unix pathname of the file. In place of a filename, the
+ keywords <function>stdin</function> and <function>stdout</function>
+ can be used, so that input to <command>COPY</command> can be written
+ by a libpq application and output from <command>COPY</command> can
+ be read by a libpq application.
+ </para>
+ <para>
+ The <function>BINARY</function> keyword will force all data to be
+ stored/read as binary objects rather than as ASCII text. It is
+ somewhat faster than the normal copy command, but is not
+ generally portable, and the files generated are somewhat larger,
+ although this factor is highly dependent on the data itself. By
+ default, an ASCII copy uses a tab (\t) character as a delimiter.
+ The delimiter may also be changed to any other single character
+ with the keyword <function>USING DELIMITERS</function>. Characters
+ in data fields which happen to match the delimiter character will
+ be quoted.
+ </para>
+
+ <REFSECT2 ID="R2-SQL-COPY-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <para>
+ You must have select access on any table whose values are read by
+ <command>COPY</command>, and either insert or update access to a
+ table into which values are being inserted by <command>COPY</command>.
+ The backend also needs appropriate Unix permissions for any file read
+ or written by <command>COPY</command>.
+<comment>
+Is this right? The man page talked of read, write and append access, which
+is neither SQL nor Unix terminology.
+</comment>
+ </para>
+ <para>
+ The keyword <function>USING DELIMITERS</function> is inaptly
+ named, since only a single character may be specified. (If a
+ group of characters is specified, only the first character is
+ used.)
+ </para>
+ <para>
+ WARNING: do not confuse <command>COPY</command> with the
+ <command>psql</command> instruction <command>\copy</command>.
+ </para>
+ </REFSECT2>
+ </refsect1>
+ <refsect1 ID="R1-SQL-COPY-2">
+ <refsect1info>
+ <date>1998-05-04</date>
+ </refsect1info>
+ <title>Format of output files</title>
+ <refsect2>
+ <refsect2info>
+ <date>1998-05-04</date>
+ </refsect2info>
+ <title>ASCII copy format</title>
+ <para>
+ When <command>COPY</command> is used without <function>BINARY</function>,
+ the file generated will have each instance on a single line, with each
+ attribute separated by the delimiter character. Embedded
+ delimiter characters will be preceded by a backslash character
+ (\). The attribute values themselves are strings generated by the
+ output function associated with each attribute type. The output
+ function for a type should not try to generate the backslash
+ character; this will be handled by <command>COPY</command> itself.
+ </para>
+ <para>
+ The actual format for each instance is
+ <programlisting>
+ <attr1><<replaceable class=parameter>separator</replaceable>><attr2><<replaceable class=parameter>separator</replaceable>>...<<replaceable class=parameter>separator</replaceable>><attr<replaceable class="parameter">n</replaceable>><newline></programlisting>
+ The oid is placed on the beginning of the line
+ if <function>WITH OIDS</function> is specified.
+ </para>
+ <para>
+ If <command>COPY</command> is sending its output to standard
+ output instead of a file, it will send a backslash(\) and a period
+ (.) followed immediately by a newline, on a separate line,
+ when it is done. Similarly, if <command>COPY</command> is reading
+ from standard input, it will expect a backslash (\) and a period
+ (.) followed by a newline, as the first three characters on a
+ line, to denote end-of-file. However, <command>COPY</command>
+ will terminate (followed by the backend itself) if a true EOF is
+ encountered.
+ </para>
+ <para>
+ The backslash character has special meaning. NULL attributes are
+ output as \N. A literal backslash character is output as two
+ consecutive backslashes. A literal tab character is represented
+ as a backslash and a tab. A literal newline character is
+ represented as a backslash and a newline. When loading ASCII data
+ not generated by PostgreSQL, you will need to convert backslash
+ characters (\) to double-backslashes (\\) to ensure that they are loaded
+ properly.
+ </para>
+ </refsect2>
+ <refsect2>
+ <refsect2info>
+ <date>1998-05-04</date>
+ </refsect2info>
+ <title>Binary copy format</title>
+ <para>
+ In the case of <command>COPY BINARY</command>, the first four
+ bytes in the file will be the number of instances in the file. If
+ this number is zero, the <command>COPY BINARY</command> command
+ will read until end of file is encountered. Otherwise, it will
+ stop reading when this number of instances has been read.
+ Remaining data in the file will be ignored.
+ </para>
+ <para>
+ The format for each instance in the file is as follows. Note that
+ this format must be followed <emphasis>exactly</emphasis>.
+ Unsigned four-byte integer quantities are called uint32 in the
+ table below.
+ </para>
+ <table frame="all">
+ <title>Contents of a binary copy file</title>
+ <tgroup cols="2"colsep="1" rowsep="1" align="center">
+ <COLSPEC COLNAME="col1">
+ <COLSPEC COLNAME="col2">
+ <spanspec namest="col1" nameend="col2" spanname="subhead">
+ <tbody>
+ <row>
+ <entry align="center" spanname="subhead">At the start of the file</entry>
+ </row>
+ <row>
+ <entry>uint32</entry>
+ <entry>number of tuples</entry>
+ </row>
+ <row>
+ <entry align="center" spanname="subhead">For each tuple</entry>
+ </row>
+ <row>
+ <entry>uint32</entry>
+ <entry>total length of tuple data</entry>
+ </row>
+ <row>
+ <entry>uint32</entry>
+ <entry>oid (if specified)</entry>
+ </row>
+ <row>
+ <entry>uint32</entry>
+ <entry>number of null attributes</entry>
+ </row>
+ <row>
+ <entry>[uint32</entry>
+ <entry>attribute number of first null attribute, counting from 0</entry>
+ </row>
+ <row>
+ <entry>...</entry>
+ <entry>...</entry>
+ </row>
+ <row>
+ <entry>uint32</entry>
+ <entry>attribute number of last null attribute]</entry>
+ </row>
+ <row>
+ <entry>-</entry>
+ <entry><tuple data></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </refsect2>
+ <refsect2>
+ <refsect2info>
+ <date>1998-05-04</date>
+ </refsect2info>
+ <title>Alignment of binary data</title>
+ <para>
+ On Sun-3s, 2-byte attributes are aligned on two-byte boundaries,
+ and all larger attributes are aligned on four-byte boundaries.
+ Character attributes are aligned on single-byte boundaries. On
+ other machines, all attributes larger than 1 byte are aligned on
+ four-byte boundaries. Note that variable length attributes are
+ preceded by the attribute's length; arrays are simply contiguous
+ streams of the array element type.
+ </para>
+ </refsect2>
+ </refsect1>
+
+
+ <REFSECT1 ID="R1-SQL-COPY-3">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+To copy a table to standard output, using | as a delimiter
+ </PARA>
+ <ProgramListing>
+ COPY country TO stdout USING DELIMITERS '|';
+ </ProgramListing>
+ <PARA>
+ To copy data from a Unix file into a table:
+ </PARA>
+ <ProgramListing>
+ COPY country FROM '/usr1/proj/bray/sql/country_data';
+ </ProgramListing>
+ <PARA>
+ A sample of data suitable for copying into a table from <filename>stdin</filename> (so it
+has the termination sequence on the last line):
+ </PARA>
+ <ProgramListing>
+ AF AFGHANISTAN
+ AL ALBANIA
+ DZ ALGERIA
+ ...
+ ZM ZAMBIA
+ ZW ZIMBABWE
+ \.
+ </ProgramListing>
+ <PARA>
+ The same data, output in binary format on a Linux Intel machine.
+ The data is shown after filtering through the Unix utility <command>od -c</command>. The table has
+ three fields; the first is <classname>char(2)</classname> and the second is <classname>text</classname>. All the
+ rows have a null value in the third field). Notice how the <classname>char(2)</classname>
+ field is padded with nulls to four bytes and the text field is
+ preceded by its length:
+ </PARA>
+ <ProgramListing>
+ 355 \0 \0 \0 027 \0 \0 \0 001 \0 \0 \0 002 \0 \0 \0
+ 006 \0 \0 \0 A F \0 \0 017 \0 \0 \0 A F G H
+ A N I S T A N 023 \0 \0 \0 001 \0 \0 \0 002
+ \0 \0 \0 006 \0 \0 \0 A L \0 \0 \v \0 \0 \0 A
+ L B A N I A 023 \0 \0 \0 001 \0 \0 \0 002 \0
+ \0 \0 006 \0 \0 \0 D Z \0 \0 \v \0 \0 \0 A L
+ G E R I A
+ ... \n \0 \0 \0 Z A M B I A 024 \0
+ \0 \0 001 \0 \0 \0 002 \0 \0 \0 006 \0 \0 \0 Z W
+ \0 \0 \f \0 \0 \0 Z I M B A B W E
+ </ProgramListing>
+ </refsect1>
+
+ <refsect1 ID="R1-SQL-COPY-4">
+ <title>See also</title>
+ <para>
+ insert(l), create table(l), vacuum(l), libpq.
+ </para>
+ </refsect1>
+
+ <refsect1 ID="R1-SQL-COPY-5">
+ <title>Bugs</title>
+ <para>
+ <command>COPY</command> stops operation at the first error. This
+ should not lead to problems in the event of a copy from, but the
+ target relation will, of course, be partially modified in a copy
+ to. The <command>VACUUM</command> query should be used to clean up
+ after a failed copy.
+ </para>
+ <para>
+ Because Postgres' current directory is not the same as the user's
+ working directory, the result of copying to a file "foo" (without
+ additional path information) may yield unexpected results for the
+ naive user. In this case, "foo" will wind up in $PGDATA/foo. In
+ general, the full pathname should be used when specifying files to
+ be copied.
+ </para>
+ <para>
+ Files used as arguments to the copy command must reside on or be
+ accessible to the database server machine by being either on
+ local disks or on a networked file system.
+ </para>
+ <para>
+ When a TCP/IP connection from one machine to another is used, and a
+ target file is specified, the target file will be written on the
+ machine where the backend is running rather than the user's
+ machine.
+ </para>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-COPY-6">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-COPY-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no COPY statement in SQL92.
+ </PARA>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-CREATEAGGREGATE-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ CREATE AGGREGATE
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+
+<comment>This entry needs a lot of work, especially some
+usefully complex examples. Since I don't yet understand it, I
+haven't done this.</comment>
+
+ <REFNAMEDIV>
+ <REFNAME>
+ CREATE AGGREGATE
+ </REFNAME>
+ <REFPURPOSE>
+ Defines a new aggregate function
+ </REFPURPOSE>
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ CREATE AGGREGATE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [AS]
+ ([ SFUNC1 = <REPLACEABLE CLASS="PARAMETER">state_transition_function1</REPLACEABLE>
+ , BASETYPE = <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
+ , STYPE1 = <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> ]
+ [, SFUNC2 = <REPLACEABLE CLASS="PARAMETER">state_transition_function2</REPLACEABLE>
+ , STYPE2 = <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE> ]
+ [, FINALFUNC = <REPLACEABLE CLASS="PARAMETER">final_function</REPLACEABLE> ]
+ [, INITCOND1 = <REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE> ]
+ [, INITCOND2 = <REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE> ]
+ )
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <variablelist>
+ <varlistentry>
+ <term></term>
+ <listitem>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>
+ </TERM>
+ <LISTITEM>
+ <para>
+ The name of an aggregate function to create.
+ </para>
+ </LISTITEM>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">state_transition_function1</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">state-transition_function2</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">final_function</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </PARA>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATE</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the command completes successfully.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-CREATEAGGREGATE-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ An aggregate function can use up to three functions, two
+ state transition functions, X1 and X2:
+ X1( internal-state1, next-data_item ) ---> next-internal-state1
+ X2( internal-state2 ) ---> next-internal-state2
+ and a final calculation function, F:
+ F(internal-state1, internal-state2) ---> aggregate-value
+ These functions are required to have the following properties:
+ <itemizedlist>
+ <listitem>
+ <para>
+ The arguments to state-transition-function-1 must
+ be (stype1,basetype), and its return value must be
+ stype1.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The argument and return value of state-transition-
+ function-2 must be stype2.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The arguments to the final-calculation-function
+ must be (stype1,stype2), and its return value must
+ be a POSTGRES base type (not necessarily the same
+ as basetype.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The final-calculation-function should be specified
+ if and only if both state-transition functions are
+ specified.
+ </para
+ </listitem>
+ </itemizedlist>
+ </PARA>
+ <para>
+ Note that it is possible to specify aggregate functions
+ that have varying combinations of state and final functions.
+ For example, the "count" aggregate requires sfunc2
+ (an incrementing function) but not sfunc1 or finalfunc,
+ whereas the "sum" aggregate requires sfunc1 (an addition
+ function) but not sfunc2 or finalfunc and the "average"
+ aggregate requires both of the above state functions as
+ well as a finalfunc (a division function) to produce its
+ answer. In any case, at least one state function must be
+ defined, and any sfunc2 must have a corresponding initcond2.
+ </para>
+ <para>
+ Aggregates also require two initial conditions, one for
+ each transition function. These are specified and stored
+ in the database as fields of type text.
+ </para>
+
+ <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ CREATE AGGREGATE function is a PostgreSQL language extension.
+ </PARA>
+
+ <para>
+ Refer to DROP AGGREGATE function to drop aggregate functions.
+ </para>
+ </REFSECT2>
+
+ <REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ </PARA>
+ <ProgramListing>
+ </ProgramListing>
+
+
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CREATEAGGREGATE-3">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4">
+ <REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no CREATE AGGREGATE function on SQL92.
+ </PARA>
+
+</REFENTRY>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-CREATEDATABASE-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ CREATE DATABASE
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ CREATE DATABASE
+ </REFNAME>
+ <REFPURPOSE>
+ Creates a new database
+ </REFPURPOSE>
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ CREATE DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [WITH LOCATION = '<replaceable class="parameter">dbpath</replaceable>']
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-CREATEDATABASE-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of a database to create.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">dbpath</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ An alternate location can be specified as either an
+ environment variable known to the backend server
+ (e.g. '<envar>PGDATA2</envar>') or as an absolute path name
+ (e.g. '<filename>/usr/local/pgsql/data</filename>').
+ In either case, the location must be pre-configured
+ by <command>initlocation</command>.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-CREATEDATABASE-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATEDB</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the command completes successfully.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>WARN: createdb: database "<replaceable class="parameter">name</replaceable>" already exists.</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This occurs if <replaceable class="parameter">database</replaceable> specified already exists.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: Unable to create database directory <replaceable class="parameter">directory</replaceable>
+</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+There was a problem with creating the required directory; this operation will
+ need permissions for the <literal>postgres</literal> user on the specified location.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-CREATEDATABASE-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ CREATE DATABASE creates a new PostgreSQL database.
+ The creator becomes the administrator of the new database.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATEDATABASE-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ CREATE DATABASE statement is a PostgreSQL language extension.
+ </PARA>
+ <para>
+ Refer to DROP DATABASE statement to remove a database.
+ </para>
+ </REFSECT2>
+
+ <REFSECT1 ID="R1-SQL-CREATEDATABASE-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ To create a new database:
+ </PARA>
+ <ProgramListing>
+ CREATE DATABASE lusiadas;
+ </ProgramListing>
+ <PARA>
+ To create a new database in <filename>~/private_db</filename>:
+ </PARA>
+ <ProgramListing>
+ $ mkdir private_db
+ $ initlocation ~/private_db
+ <computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
+
+ $ chmod a+rx private_db
+ $ chmod a+rwx private_db/base
+ $ psql
+ <computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
+ Please read the file COPYRIGHT for copyright terms of POSTGRESQL
+
+ type \? for help on slash commands
+ type \q to quit
+ type \g or terminate with semicolon to execute query
+ You are currently connected to the database: template1
+
+ template1=></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput>
+ <computeroutput>CREATEDB</computeroutput>
+ </ProgramListing>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CREATEDATABASE-3">
+ <TITLE>
+ Bugs
+ </TITLE>
+ <PARA>
+ Where an ordinary user cannot change the ownership of files to other users
+ (which is correct from a security point of view), there is no easy way
+ to give the postgres backend access to files in a database at a
+ non-standard location without
+ giving similar access to all users. The situation shown in the usage
+ example makes <filename>/home/olly/private_db</filename> world-accessible.
+ </PARA>
+ <para>
+ If, on the other hand, the user gets the system administrator to give
+ file ownership to the <literal>postgres</literal> superuser and restrict access, he will
+ then be unable to delete the <filename><replaceable>directory</replaceable>/base</filename> directory.
+ </para>
+ <comment>
+ initlocation does not create a PG_VERSION file in the specified location.
+ How will PostgreSQL handle the situation if it is upgraded to an
+ incompatible database version?
+ </comment>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-CREATEDATABASE-4">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATEDATABASE-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no <command>CREATE DATABASE</command> statement on SQL92.
+ </PARA>
+ <para>
+ The equivalent command in standard SQL is <command>CREATE SCHEMA</command>.
+ </para>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-CREATEFUNCTION-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ CREATE FUNCTION
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ CREATE FUNCTION
+ </REFNAME>
+ <REFPURPOSE>
+ Defines a new function
+ </REFPURPOSE>
+
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ([<replaceable class="parameter">ftype</replaceable> [, ...]])
+ RETURNS <replaceable class="parameter">rtype</replaceable>
+ AS <replaceable class="parameter">path</replaceable>
+ LANGUAGE '<replaceable class="parameter">langname</replaceable>'
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-CREATEFUNCTION-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of a function to create.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">ftype</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The data type of function arguments.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">rtype</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The return data type.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">path</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ May be either an SQL-query or an absolute path to an
+ object file.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">langname</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ may be '<literal>c</literal>', '<literal>sql</literal>', '<literal>internal</literal>' or '<replaceable class="parameter">plname</replaceable>'.
+ (where '<replaceable class="parameter">plname</replaceable>' is the language name of a created procedural
+ language. See <command>CREATE LANGUAGE</command> for details).
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-CREATEFUNCTION-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATE</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This is returned if the command completes successfully.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-CREATEFUNCTION-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ With this command, a PostgreSQL user can register a function
+ with PostgreSQL. Subsequently, this user is treated as the
+ owner of the function.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATEFUNCTION-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ Refer to <citetitle>PostgreSQL User's Guide</citetitle> chapter 6 for further information.
+ <comment>This reference needs to be corrected.</comment>
+ </PARA>
+ <PARA>
+ Refer to the <citerefentry>
+ <refentrytitle>DROP FUNCTION</refentrytitle>
+ </citerefentry> statement to drop functions.
+ </PARA>
+ </REFSECT2>
+
+ <REFSECT1 ID="R1-SQL-CREATEFUNCTION-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ To create a simple SQL function:
+ </PARA>
+ <ProgramListing>
+ CREATE FUNCTION one() RETURNS int4
+ AS 'SELECT 1 AS RESULT'
+ LANGUAGE 'sql';
+
+ SELECT one() AS answer;
+
+ <computeroutput>answer
+ ------
+ 1 </computeroutput>
+ </ProgramListing>
+ <para>
+ To create a C function, calling a routine from a user-created
+ shared library. This particular routine calculates a check
+ digit and returns TRUE if the check digit in the function parameters
+ is correct. It is intended for use in a CHECK contraint.
+ </para>
+ <programlisting>
+ <userinput>CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
+ AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
+
+ CREATE TABLE product
+ (
+ id char(8) PRIMARY KEY,
+ eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
+ REFERENCES brandname(ean_prefix),
+ eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
+ CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
+ );</userinput>
+ </programlisting>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CREATEFUNCTION-3">
+ <TITLE>
+ Bugs
+ </TITLE>
+ <PARA>
+ A C function cannot return a set of values.
+ </PARA>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CREATEFUNCTION-4">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ The CREATE FUNCTION statement is a PostgreSQL language extension.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATEFUNCTION-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL/PSM<footnote>
+ <para>
+ PSM stands for Persistent Stored Modules, it is a procedural
+ language and it was originally hoped that PSM would be ratified
+ as an official standard by late 1996. However PSM will
+ eventually become a standard.
+ </para>
+ </footnote>
+ </TITLE>
+ <para>
+ The SQL/PSM CREATE FUNCTION statement has the following syntax:
+ <programlisting>
+ CREATE FUNCTION <replaceable class="parameter">name</replaceable>
+ ( [ [IN|OUT|INOUT] <replaceable class="parameter">parm</replaceable> <replaceable class="parameter">type</replaceable> [, ...] ])
+ RETURNS <replaceable class="parameter">rtype</replaceable>
+ LANGUAGE '<replaceable class="parameter">langname</replaceable>'
+ ESPECIFIC <replaceable class="parameter">routine</replaceable>
+ <replaceable class="parameter">SQL-statement</replaceable>
+ </programlisting>
+ </para>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-CREATEINDEX-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ CREATE INDEX
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ CREATE INDEX
+ </REFNAME>
+ <REFPURPOSE>
+ Constructs a secondary index
+ </REFPURPOSE>
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ CREATE [UNIQUE] INDEX <replaceable class="parameter">index_name</replaceable>
+ ON <replaceable class="parameter">table</replaceable> [USING <replaceable class="parameter">acc_name</replaceable> ]
+ ( <replaceable class="parameter">column</replaceable> [<replaceable class="parameter">ops_name</replaceable>] [, ...] )
+
+ CREATE [UNIQUE] INDEX <replaceable class="parameter">index_name</replaceable>
+ ON <replaceable class="parameter">table</replaceable> [USING <replaceable class="parameter">acc_name</replaceable> ]
+ ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-CREATEINDEX-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <function>UNIQUE</function>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <function>UNIQUE</function> causes the system to check for
+ duplicate values when the index is created (if data
+ already exist) and each time data is added. Attempts to
+ insert or update non-duplicate data will generate an
+ error.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">index_name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of the index to be created.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">table</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of the table to be indexed.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">acc_name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ the name of the access method which is to be used for
+ the index. The default access method is BTREE.
+ Postgres provides three access methods for secondary indices:
+ <variablelist>
+ <varlistentry>
+ <term>BTREE</term>
+ <listitem>
+ <para>
+ an implementation of the Lehman-Yao
+ high-concurrency btrees.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RTREE</term>
+ <listitem>
+ <para>implements standard rtrees using Guttman's
+ quadratic split algorithm.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>HASH</term>
+ <listitem>
+ <para>
+ an implementation of Litwin's linear hashing.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">column</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of a column of the table.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">ops_name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ An associated operator class.
+ The following select list returns all ops_names:
+
+ <programlisting>
+ SELECT am.amname AS acc_name,
+ opc.opcname AS ops_name,
+ opr.oprname AS ops_comp
+ FROM pg_am am, pg_amop amop,
+ pg_opclass opc, pg_operator opr
+ WHERE amop.amopid = am.oid AND
+ amop.amopclaid = opc.oid AND
+ amop.amopopr = opr.oid
+ ORDER BY acc_name, ops_name, ops_comp
+ </programlisting>
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">func_name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ A user-defined function, which returns a value that can
+ be indexed.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-CREATEINDEX-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATE</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The message returned if the index is successfully created.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This error occurs if it is impossible to create the index.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-CREATEINDEX-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ This command constructs an index called <replaceable class="parameter">index_name</replaceable>.
+ </PARA>
+ <para>
+ In the first syntax shown above, the key fields for the
+ index are specified as column names; a column may also have
+ an associated operator class. An operator class is used
+ to specify the operators to be used for a particular
+ index. For example, a btree index on four-byte integers
+ would use the <literal>int4_ops</literal> class;
+ this operator class includes
+ comparison functions for four-byte integers. The default
+ operator class is the appropriate operator class for that
+ field type.
+ </para>
+ <para>
+ In the second syntax, an index is defined
+ on the result of a user-defined function
+ <replaceable class="parameter">func_name</replaceable> applied
+ to one or more attributes of a single class. These functional
+ indices can be used to obtain fast access to data
+ based on operators that would normally require some
+ transformation to apply them to the base data.
+ </para>
+
+ <REFSECT2 ID="R2-SQL-CREATEINDEX-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ Currently, only the BTREE access method supports multi-column
+ indices. Up to 7 keys may be specified.
+ </PARA>
+ <para>
+ Use the <citerefentry>
+ <refentrytitle>DROP INDEX</refentrytitle>
+ </citerefentry>
+ statement to remove indexes.
+ </para>
+ </REFSECT2>
+
+ <REFSECT1 ID="R1-SQL-CREATEINDEX-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>To create a btree index on the field <literal>title</literal>
+ in the table <literal>films</literal>:
+ </PARA>
+ <ProgramListing>
+ CREATE UNIQUE INDEX title_idx
+ ON films (title);
+ </ProgramListing>
+ <para>
+ To create a rtree index on a point attribute so that we
+ can efficiently use box operators on the result of the
+ conversion function:
+ </para>
+ <programlisting>
+ CREATE INDEX pointloc
+ ON points USING RTREE (point2box(location) box_ops);
+
+ SELECT * FROM points
+ WHERE point2box(points.pointloc) = boxes.box;
+<comment>
+Is this example correct?
+</comment>
+ </programlisting>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CREATEINDEX-3">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATEINDEX-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ CREATE INDEX is a PostgreSQL language extension.
+ </PARA>
+ <para>
+ There is no CREATE INDEX command in SQL92.
+ </para>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-CREATELANGUAGE-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ CREATE LANGUAGE
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ CREATE LANGUAGE
+ </REFNAME>
+ <REFPURPOSE>
+ Defines a new language for functions
+ </REFPURPOSE>
+
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ CREATE [TRUSTED] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname</replaceable>'
+ HANDLER <replaceable class="parameter">call_handler</replaceable>
+ LANCOMPILER '<replaceable class="parameter">comment</replaceable>'
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-CREATELANGUAGE-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <function>TRUSTED</function>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <function> TRUSTED</function> specifies that the call handler for
+ the language is safe; that is, it offers an unprivileged user
+ no functionality to get around access restrictions. If
+ this keyword is omitted when registering the language,
+ only users with the PostgreSQL superuser privilege can use
+ this language to create new functions
+ (like the 'C' language).
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">langname</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of the new procedural language.
+ The language name is case insensitive. A procedural
+ language cannot override one of the built-in languages of
+ PostgreSQL.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">call_handler</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The argument for <function>HANDLER</function> is the name
+ of a previously
+ registered function that will be called to execute the PL
+ procedures.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">comment</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The <function>LANCOMPILER</function> argument is the
+ string that will be
+ inserted in the <literal>LANCOMPILER</literal> attribute
+ of the new
+ <filename>pg_language</filename> entry. At present,
+ PostgreSQL doesn't use
+ this attribute in any way.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-CREATELANGUAGE-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>CREATE</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This message is returned if the language is successfully
+ created.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This error is returned if the function
+ <replaceable class="parameter">funcname</replaceable>()
+ is not found.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-CREATELANGUAGE-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ Using <command>CREATE LANGUAGE</command>, a PostgreSQL user can register
+ a new language with PostgreSQL. Subsequently, functions and
+ trigger procedures can be defined in this new language.
+ The user must have the PostgreSQL superuser privilege to
+ register a new language.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATELANGUAGE-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Writing PL handlers
+ </TITLE>
+ <PARA>
+ The call handler for a procedural language must be written
+ in a compiler language such as 'C' and registered with
+ PostgreSQL as a function taking no arguments and returning
+ opaque type.
+ <comment>What does `opaque type' mean?</comment>
+ This prevents the call handler from being
+ called directly as a function from queries.
+ </para>
+ <para>
+ However, arguments must be supplied on the actual call when a
+ PL function or trigger
+ procedure in the language offered by the handler is to be
+ executed.
+ <itemizedlist>
+ <listitem>
+ <para>
+ When called from the trigger manager, the only argument is
+ the object ID from the procedure's <filename>pg_proc</filename>
+ entry. All other
+ information from the trigger manager is found in the
+ global <structname>CurrentTriggerData</structname> pointer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When called from the function manager, the arguments are
+ the object ID of the procedure's <filename>pg_proc</filename>
+ entry, the number
+ of arguments given to the PL function, the arguments in a
+ <structname>FmgrValues</structname> structure and a pointer
+ to a boolean where the
+ function tells the caller if the return value is the SQL
+ NULL value.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </PARA>
+ <para>
+ It's up to the call handler to fetch the
+ <filename>pg_proc</filename> entry and
+ to analyze the argument and return types of the called
+ procedure. The <function>AS</function> clause from the
+ <command>CREATE FUNCTION</command> of
+ the procedure will be found in the <literal>prosrc</literal>
+ attribute of the
+ <filename>pg_proc</filename> entry. This may be the
+ source text in the procedural
+ language itself (like for PL/Tcl), a pathname to a
+ file or anything else that tells the call handler what to
+ do in detail.
+ </para>
+
+ <REFSECT2 ID="R2-SQL-CREATELANGUAGE-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ Use <citerefentry>
+ <refentrytitle>CREATE FUNCTION</refentrytitle>
+ </citerefentry>
+ to create a function.
+ </para>
+ <para>
+ Use <citerefentry>
+ <refentrytitle>DROP LANGUAGE</refentrytitle>
+ </citerefentry> to drop procedural languages.
+ </para>
+ <para>
+ Refer to the table <filename>pg_language</filename>
+ for further information:
+ <programlisting>
+ <computeroutput>
+ Table = pg_language
+ +--------------------------+--------------------------+-------+
+ | Field | Type | Length|
+ +--------------------------+--------------------------+-------+
+ | lanname | name | 32 |
+ | lancompiler | text | var |
+ +--------------------------+--------------------------+-------+
+
+ lanname |lancompiler
+ --------+--------------
+ internal|n/a
+ lisp |/usr/ucb/liszt
+ C |/bin/cc
+ sql |postgres
+ </computeroutput>
+ </programlisting>
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-CREATELANGUAGE-4">
+ <TITLE>
+ Restrictions
+ </TITLE>
+ <PARA>
+ Since the call handler for a procedural language must be
+ registered with PostgreSQL in the 'C' language, it inherits
+ all the restrictions of 'C' functions.
+ <comment>
+ What are these restrictions?
+ </comment>
+ </para>
+ </refsect1>
+ <REFSECT1 ID="R1-SQL-CREATELANGUAGE-5">
+ <TITLE>
+ Bugs
+ </TITLE>
+ <PARA>
+ At present, the definitions for a procedural language cannot be
+ changed once they have been created.
+ </para>
+ </refsect1>
+
+ <REFSECT1 ID="R1-SQL-CREATELANGUAGE-6">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ This is a template for a PL handler written in 'C':
+ </PARA>
+ <ProgramListing>
+ #include "executor/spi.h"
+ #include "commands/trigger.h"
+ #include "utils/elog.h"
+ #include "fmgr.h" /* for FmgrValues struct */
+ #include "access/heapam.h"
+ #include "utils/syscache.h"
+ #include "catalog/pg_proc.h"
+ #include "catalog/pg_type.h"
+
+ Datum
+ plsample_call_handler(
+ Oid prooid,
+ int pronargs,
+ FmgrValues *proargs,
+ bool *isNull)
+ {
+ Datum retval;
+ TriggerData *trigdata;
+
+ if (CurrentTriggerData == NULL) {
+ /*
+ * Called as a function
+ */
+
+ retval = ...
+ } else {
+ /*
+ * Called as a trigger procedure
+ */
+ trigdata = CurrentTriggerData;
+ CurrentTriggerData = NULL;
+
+ retval = ...
+ }
+
+ *isNull = false;
+ return retval;
+ }
+ </ProgramListing>
+ <para>
+ Only a few thousand lines of code have to be added instead
+ of the dots to complete the PL call handler. See <citerefentry>
+ <refentrytitle>CREATE FUNCTION</refentrytitle>
+ </citerefentry> for information on how to compile
+ it into a loadable module
+.</para>
+ <para>
+ The following commands then register the sample procedural
+ language.</para>
+ <programlisting>
+ CREATE FUNCTION plsample_call_handler () RETURNS opaque
+ AS '/usr/local/pgsql/lib/plsample.so'
+ LANGUAGE 'C';
+
+ CREATE PROCEDURAL LANGUAGE 'plsample'
+ HANDLER plsample_call_handler
+ LANCOMPILER 'PL/Sample';
+ </programlisting>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-CREATELANGUAGE-7">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA>
+ CREATE LANGUAGE is a PostgreSQL extension.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-CREATELANGUAGE-5">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL92
+ </TITLE>
+ <PARA>
+ There is no CREATE LANGUAGE statement in SQL92.
+ </PARA>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-DROPFUNCTION-1">
+ <REFMETA>
+ <REFENTRYTITLE>
+ DROP FUNCTION
+ </REFENTRYTITLE>
+ <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+ </REFMETA>
+ <REFNAMEDIV>
+ <REFNAME>
+ DROP FUNCTION
+ </REFNAME>
+ <REFPURPOSE>
+ Removes a user-defined C function
+ </REFPURPOSE>
+
+ <REFSYNOPSISDIV>
+ <REFSYNOPSISDIVINFO>
+ <DATE>1998-04-15</DATE>
+ </REFSYNOPSISDIVINFO>
+ <SYNOPSIS>
+ DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [<replaceable class="parameter">type</replaceable> [, ...]] )
+ </SYNOPSIS>
+
+ <REFSECT2 ID="R2-SQL-DROPFUNCTION-1">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Inputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter"> name</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The name of an existing function.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <replaceable class="parameter">type</replaceable>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ The type of function parameters.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+
+ <REFSECT2 ID="R2-SQL-DROPFUNCTION-2">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Outputs
+ </TITLE>
+ <PARA>
+ </PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ <VARIABLELIST>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>DROP</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ Message returned if the command completes successfully.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ <VARLISTENTRY>
+ <TERM>
+ <ReturnValue>
+ WARN RemoveFunction: Function "<replaceable class="parameter">name</replaceable>" ("<replaceable class="parameter">types</replaceable>") does not exist</ReturnValue>
+ </TERM>
+ <LISTITEM>
+ <PARA>
+ This message is given if the function specified does not
+exist into database.
+ </PARA>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </variablelist>
+ </LISTITEM>
+ </VARLISTENTRY>
+ </VARIABLELIST>
+ </REFSECT2>
+ </REFSYNOPSISDIV>
+
+ <REFSECT1 ID="R1-SQL-DROPFUNCTION-1">
+ <REFSECT1INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT1INFO>
+ <TITLE>
+ Description
+ </TITLE>
+ <PARA>
+ DROP FUNCTION will remove references to an existing C
+ function. To execute this command the user must be the
+ owner of the function. The input argument types to the
+ function must be specified, as only the function with the
+ given name and argument types will be removed.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-DROPFUNCTION-3">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
+ <PARA>
+ Refer to the <citerefentry>
+ <refentrytitle>
+ CREATE FUNCTION</refentrytitle>
+ </citerefentry>
+ statement to create aggregate functions.
+ </PARA>
+ </REFSECT2>
+
+ <REFSECT1 ID="R1-SQL-DROPFUNCTION-2">
+ <TITLE>
+ Usage
+ </TITLE>
+ <PARA>
+ This command removes the square root function:
+ </PARA>
+ <ProgramListing>
+ DROP FUNCTION sqrt(int4);
+ </ProgramListing>
+ </REFSECT1>
+ <REFSECT1 ID="R1-SQL-DROPFUNCTION-3">
+ <TITLE>
+ Bugs
+ </TITLE>
+ <PARA>
+ No checks are made to ensure that types, operators or access
+ methods that rely on the function have been removed first.
+ </PARA>
+ </REFSECT1>
+
+ <REFSECT1 ID="R1-SQL-DROPFUNCTION-4">
+ <TITLE>
+ Compatibility
+ </TITLE>
+ <PARA
+ >DROP FUNCTION statement is a PostgreSQL language extension.
+ </PARA>
+
+ <REFSECT2 ID="R2-SQL-DROPFUNCTION-4">
+ <REFSECT2INFO>
+ <DATE>1998-04-15</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ SQL/PSM
+ </TITLE>
+ <PARA>
+ The SQL/PSM DROP FUNCTION statement has the following syntax:
+ <programlisting>
+ DROP [ SPECIFIC ] FUNCTION <replaceable class="parameter">name</replaceable> { RESTRICT | CASCADE }</programlisting>
+ </PARA>
+ </refsect2>
+ </refsect1>
+</REFENTRY>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
--- /dev/null
+<REFENTRY ID="SQL-SELECT-1">
+<REFMETA>
+<REFENTRYTITLE>
+SELECT
+</REFENTRYTITLE>
+<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+SELECT
+</REFNAME>
+<REFPURPOSE>
+Retrieve rows from a table or view
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-04-15</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+<REPLACEABLE CLASS="PARAMETER">
+</REPLACEABLE>
+SELECT [ALL|DISTINCT]
+ <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [AS <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>] [, ...]
+ [INTO [TABLE] <REPLACEABLE CLASS="PARAMETER">intable</REPLACEABLE>]
+ [FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [<REPLACEABLE CLASS="PARAMETER">alias</REPLACEABLE>] [, ...] ]
+ [WHERE <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE>]
+ [GROUP BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ]
+ [HAVING <REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE> [, ...] ]
+ [UNION [ALL] <REPLACEABLE CLASS="PARAMETER">select</REPLACEABLE>]
+ [ORDER BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [ASC | DESC] [, ...] ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-SQL-SELECT-1">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+
+<PARA>
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ The name of a table's column or an expression.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ Specifies another name for a column or an expression using
+ the AS clause. <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> cannot be used in the WHERE
+ condition. It can, however, be referenced in associated
+ ORDER BY or GROUP BY clauses.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">intable</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ If the INTO TABLE clause is specified, the result of the
+ query will be stored in another table with the indicated
+ name.
+If <REPLACEABLE CLASS="PARAMETER">intable</REPLACEABLE> does not exist, it will be created automatically.
+
+<Note>
+<Para>
+The CREATE TABLE AS statement will also create a new table from a select query.
+</Para>
+</Note>
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ The name of an existing table referenced by FROM clause.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">alias</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+An alternate name for the preceeding <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
+Used for brevity or to eliminate ambiguity for joins within a single table.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">condition</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+An expression leading to a boolean (true/false) result.
+See the WHERE clause.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+ The name of a table's column.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">select</REPLACEABLE>
+</TERM>
+<LISTITEM>
+<PARA>
+A select statement with all features except the ORDER BY clause.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+</VARIABLELIST>
+</PARA>
+</REFSECT2>
+
+<REFSECT2 ID="R2-SQL-SELECT-2">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+ Rows
+</TERM>
+<LISTITEM>
+<PARA>
+The complete set of rows resulting from the query specification.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+
+<VARLISTENTRY>
+<TERM>
+<ReturnValue>count</ReturnValue>
+</TERM>
+<LISTITEM>
+<PARA>
+The count of rows returned by the query.
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+</VARIABLELIST>
+
+</REFSECT2>
+</REFSYNOPSISDIV>
+
+<REFSECT1 ID="R1-SQL-SELECT-1">
+<REFSECT1INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+ SELECT will get all rows which satisfy the WHERE condition
+ or all rows of a table if WHERE is omitted.
+
+<PARA>
+ The GROUP BY clause allows a user to divide a table
+ conceptually into groups. (See GROUP BY clause).
+
+<PARA>
+ The HAVING clause specifies a grouped table derived by the
+ elimination of groups from the result of the previously
+ specified clause. (See HAVING clause).
+
+<PARA>
+ The ORDER BY clause allows a user to specify that he/she
+ wishes the rows sorted according to the ASCending or
+ DESCending mode operator. (See ORDER BY clause)
+
+<PARA>
+ The UNION clause specifies a table derived from a Cartesian
+ product union join. (See UNION clause).
+
+<PARA>
+ You must have SELECT privilege to a table to read its values
+ (See GRANT/REVOKE statements).
+
+<REFSECT2 ID="R2-SQL-WHERE-2">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+WHERE clause
+</TITLE>
+<PARA>
+ The optional WHERE condition has the general form:
+
+<Synopsis>
+WHERE <REPLACEABLE CLASS="PARAMETER">expr</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">cond_op</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">expr</REPLACEABLE> [<REPLACEABLE CLASS="PARAMETER">log_op</REPLACEABLE> ...]
+</Synopsis>
+
+ where <REPLACEABLE CLASS="PARAMETER">cond_op</REPLACEABLE> can be one of: =, <, <=, >, >=, <>
+ or a conditional operator like ALL, ANY, IN, LIKE, et cetera
+ and <REPLACEABLE CLASS="PARAMETER">log_op</REPLACEABLE> can be one of: AND, OR, NOT.
+ The comparison returns either TRUE or FALSE and all
+ instances will be discarded
+ if the expression evaluates to FALSE.
+</PARA>
+</REFSECT2>
+
+<REFSECT2 ID="R2-SQL-GROUPBY-2">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+GROUP BY clause
+</TITLE>
+<PARA>
+ GROUP BY specifies a grouped table derived by the application
+ of the this clause:
+<SYNOPSIS>
+GROUP BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-SQL-HAVING-2">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+HAVING clause
+</TITLE>
+<PARA>
+ The optional HAVING condition has the general form:
+
+<Synopsis>
+HAVING <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE>
+</Synopsis>
+
+ where <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE> is the same
+as specified for the WHERE clause.
+
+<Para>
+ HAVING specifies a grouped table derived by the elimination
+ of groups from the result of the previously specified clause
+ that do not meet the <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE>.
+
+<Para>
+ Each column referenced in <REPLACEABLE CLASS="PARAMETER">cond_expr</REPLACEABLE> shall unambiguously
+ reference a grouping column.
+</PARA>
+</REFSECT2>
+
+<REFSECT2 ID="R2-SQL-ORDERBYCLAUSE-2">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+ORDER BY clause
+</TITLE>
+<PARA>
+<Synopsis>
+ORDER BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [ASC | DESC] [, ...]
+</Synopsis>
+
+<PARA>
+<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> can be either a column
+name or an ordinal number.
+<PARA>
+ The ordinal numbers refers to the ordinal (left-to-right) position
+ of the column. This feature makes it possible to define an ordering
+ on the basis of a column that does not have a proper name.
+ This is never absolutely necessary because it is always possible assign a name
+ to a calculated column using the AS clause, e.g.:
+<ProgramListing>
+SELECT title, date_prod + 1 AS newlen FROM films ORDER BY newlen;
+</ProgramListing>
+
+<PARA>
+ The columns in the ORDER BY must appear in the SELECT clause.
+ Thus the following statement is illegal:
+<ProgramListing>
+SELECT name FROM distributors ORDER BY code;
+</ProgramListing>
+
+<PARA>
+ Optionally one may add the keyword DESC (descending)
+ or ASC (ascending) after each column name in the ORDER BY clause.
+ If not specified, ASC is assumed by default.
+</REFSECT2>
+
+<REFSECT2 ID="R2-SQL-UNION-2">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+UNION clause
+</TITLE>
+<PARA>
+<Synopsis>
+<REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE> UNION [ALL] <REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE>
+ [ORDER BY <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [ASC | DESC] [, ...] ]
+</Synopsis>
+
+where
+ <REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE>
+ specifies any select expression without an ORDER BY clause.
+
+<PARA>
+ The UNION operator specifies a table derived from a Cartesian product.
+ The two tables that represent the direct operands of the UNION must
+ have the same number of columns, and corresponding columns must be
+ of compatible data types.
+
+<PARA>
+ By default, the result of UNION does not contain any duplicate rows
+ unless the ALL clause is specified.
+
+<Para>
+Multiple UNION operators in the same SELECT statement are evaluated left to right.
+Note that the ALL keyword is not global in nature, being applied only for the current pair of
+table results.
+
+</REFSECT2>
+
+<REFSECT1 ID="R1-SQL-SELECT-2">
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+</PARA>
+<ProgramListing>
+ --Join table films with their distributors:
+ --
+ SELECT f.title, f.did, d.name, f.date_prod, f.kind
+ FROM distributors d, films f
+ WHERE f.did = d.did;
+
+ title |did|name | date_prod|kind
+ -------------------------+---+----------------+----------+----------
+ The Third Man |101|British Lion |1949-12-23|Drama
+ The African Queen |101|British Lion |1951-08-11|Romantic
+ Une Femme est une Femme |102|Jean Luc Godard |1961-03-12|Romantic
+ Vertigo |103|Paramount |1958-11-14|Action
+ Becket |103|Paramount |1964-02-03|Drama
+ 48 Hrs |103|Paramount |1982-10-22|Action
+ War and Peace |104|Mosfilm |1967-02-12|Drama
+ West Side Story |105|United Artists |1961-01-03|Musical
+ Bananas |105|United Artists |1971-07-13|Comedy
+ Yojimbo |106|Toho |1961-06-16|Drama
+ There's a Girl in my Soup|107|Columbia |1970-06-11|Comedy
+ Taxi Driver |107|Columbia |1975-05-15|Action
+ Absence of Malice |107|Columbia |1981-11-15|Action
+ Storia di una donna |108|Westward |1970-08-15|Romantic
+ The King and I |109|20th Century Fox|1956-08-11|Musical
+ Das Boot |110|Bavaria Atelier |1981-11-11|Drama
+ Bed Knobs and Broomsticks|111|Walt Disney | |Musical
+</ProgramListing>
+
+<ProgramListing>
+ --sum column "len" of all films group by "kind":
+ --
+ SELECT kind, SUM(len) AS total FROM films GROUP BY kind;
+
+ kind |total
+ ----------+------
+ Action | 07:34
+ Comedy | 02:58
+ Drama | 14:28
+ Musical | 06:42
+ Romantic | 04:38
+</ProgramListing>
+
+<ProgramListing>
+ --sum column length of all films group by "kind"
+ --having total duration < 5 hours:
+ --
+ SELECT kind, SUM(len) AS total
+ FROM films
+ GROUP BY kind
+ HAVING SUM(len) < INTERVAL '5 hour';
+
+ kind |total
+ ----------+------
+ Comedy | 02:58
+ Romantic | 04:38
+</ProgramListing>
+
+<ProgramListing>
+ --The following two examples are identicals:
+ --
+ SELECT * FROM distributors ORDER BY name;
+ SELECT * FROM distributors ORDER BY 2;
+
+ did|name
+ ---+----------------
+ 109|20th Century Fox
+ 110|Bavaria Atelier
+ 101|British Lion
+ 107|Columbia
+ 102|Jean Luc Godard
+ 113|Luso films
+ 104|Mosfilm
+ 103|Paramount
+ 106|Toho
+ 105|United Artists
+ 111|Walt Disney
+ 112|Warner Bros.
+ 108|Westward
+</ProgramListing>
+
+<ProgramListing>
+ --union of table distributors and table actors:
+ -- (only those that begin with letter W):
+ --
+ -- distributors: actors:
+ -- did|name id|name
+ -- ---+------------ --+--------------
+ -- 108|Westward 1|Woody Allen
+ -- 111|Walt Disney 2|Warren Beatty
+ -- 112|Warner Bros. 3|Walter Matthau
+ -- ... ...
+ --
+ --select only distinct rows (without ALL):
+ --
+ SELECT distributors.name
+ FROM distributors
+ WHERE distributors.name LIKE 'W%'
+ UNION
+ SELECT actors.name
+ FROM actors
+ WHERE actors.name LIKE 'W%';
+
+ name
+ --------------
+ Walt Disney
+ Walter Matthau
+ Warner Bros.
+ Warren Beatty
+ Westward
+ Woody Allen
+</ProgramListing>
+
+</REFSECT1>
+
+<REFSECT1 ID="R1-SQL-SELECT-3">
+<TITLE>
+Compatibility
+</TITLE>
+<PARA>
+</PARA>
+
+<REFSECT2 ID="R2-SQL-SELECT-4">
+<REFSECT2INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT2INFO>
+<TITLE>
+<Acronym>SQL92</Acronym>
+</TITLE>
+<PARA>
+</PARA>
+
+<REFSECT3 ID="R3-SQL-SELECT-1">
+<REFSECT3INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT3INFO>
+<TITLE>
+SELECT clause
+</TITLE>
+<PARA>
+In the <Acronym>SQL92</Acronym> standard, the optional keyword "AS" is just noise and can be
+omitted without affecting the meaning.
+The <ProductName>Postgres</ProductName> parser requires this keyword when
+renaming columns because the type extensibility features lead to parsing ambiguities
+in this context.
+
+<PARA>
+In the <Acronym>SQL92</Acronym> standard, the new column name specified in an
+"AS" clause may be referenced in GROUP BY and HAVING clauses. This is not currently
+allowed in <ProductName>Postgres</ProductName>.
+</PARA>
+</REFSECT3>
+
+<REFSECT3 ID="R3-SQL-UNION-1">
+<REFSECT3INFO>
+<DATE>1998-04-15</DATE>
+</REFSECT3INFO>
+<TITLE>
+UNION clause
+</TITLE>
+<PARA>
+The <Acronym>SQL92</Acronym> syntax for UNION allows an additional CORRESPONDING BY clause:
+<Synopsis>
+<REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE> UNION [ALL]
+ [CORRESPONDING [BY (<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [,...])]]
+ <REPLACEABLE CLASS="PARAMETER">table_query</REPLACEABLE>
+</Synopsis>
+
+<Para>
+The CORRESPONDING BY clause is not supported by <ProductName>Postgres</ProductName>.
+</PARA>
+</REFSECT3>
+
+</REFSECT2>
+</REFSECT1>
+</REFENTRY>
+
+<!--
+<REPLACEABLE CLASS="PARAMETER">
+</REPLACEABLE>
+<ReturnValue></ReturnValue>
+<PARA>
+</PARA>
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>•
+</TERM>
+<LISTITEM>
+<PARA>
+</PARA>
+</LISTITEM>
+</VARLISTENTRY>
+</VARIABLELIST>
+<PARA>
+</PARA>
+-->
projects / postgresql / commitdiff