rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add new reference pages adapted from Jose'.

This commit is contained in:
Thomas G. Lockhart 1998-09-05 06:02:57 +00:00
parent 3a29400141
commit 7d1e32b51c
5 changed files with 1134 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/ref/commands.sgml
View File

@ -27,6 +27,10 @@
&declare;
&delete;
&dropFunction;
&explain;
&fetch;
&grant;
&insert;
&listen;
&load;
&lock;

162
doc/src/sgml/ref/explain.sgml Normal file
View File

@ -0,0 +1,162 @@
<REFENTRY ID="SQL-EXPLAIN">
<REFMETA>
<REFENTRYTITLE>
EXPLAIN
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
EXPLAIN
</REFNAME>
<REFPURPOSE>
Shows statement execution details.
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
EXPLAIN [ VERBOSE ] <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-EXPLAIN-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
VERBOSE
</TERM>
<LISTITEM>
<PARA>
Flag to show detailed query plan.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Any <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-EXPLAIN-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
NOTICE: QUERY PLAN:
</TERM>
<LISTITEM>
<PARA>
Explicit query plan from the <productname>Postgres</productname> backend.
<VARLISTENTRY>
<TERM>
EXPLAIN
</TERM>
<LISTITEM>
<PARA>
Flag sent after query plan is shown.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-EXPLAIN-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
This command outputs details about the supplied query.
The default output is the computed query cost.
VERBOSE displays the full query plan and cost.
<REFSECT2 ID="R2-SQL-EXPLAIN-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-EXPLAIN-2">
<TITLE>
Usage
</TITLE>
<PARA>
To show a query plan for a simple query:
<ProgramListing>
postgres=> explain select * from foo;
NOTICE: QUERY PLAN:
Seq Scan on foo (cost=0.00 size=0 width=4)
EXPLAIN
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-EXPLAIN-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-EXPLAIN-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no EXPLAIN statement defined in SQL92.
</REFENTRY>
<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
-->

331
doc/src/sgml/ref/fetch.sgml Normal file
View File

@ -0,0 +1,331 @@
<REFENTRY ID="SQL-FETCH">
<REFMETA>
<REFENTRYTITLE>
FETCH
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
FETCH
</REFNAME>
<REFPURPOSE>
Gets rows using a cursor
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
FETCH [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] { [ <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> | ALL ] } { IN | FROM } <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-FETCH-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Selector define fetch direction and it can be one
the following:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
FORWARD
</TERM>
<LISTITEM>
<PARA>
fetch next row(s), it is assumed by default
if selector is omitted.
<VARLISTENTRY>
<TERM>
BACKWARD
</TERM>
<LISTITEM>
<PARA>
fetch previous row(s).
</VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
An unsigned integer that specify how many rows to fetch.
<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Retrieve all remaining rows.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
An open cursor's name.
</variablelist>
</REFSECT2>
<REFSECT2 ID="R2-SQL-FETCH-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
FETCH returns the results of the query defined by the specified cursor.
The following messages will be returned if the query fails:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
NOTICE: PerformPortalFetch: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>" not found
</TERM>
<LISTITEM>
<PARA>
If <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> is not previously declared.
The cursor must be declared within a transaction block.
</variablelist>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-FETCH-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
FETCH allows a user to retrieve rows using a cursor.
The number of rows retrieved is specified by #.
If the number of rows remaining in the cursor is less
than #, then only those available are fetched.
Substituting the keyword ALL in place of a number will
cause all remaining rows in the cursor to be retrieved.
Instances may be fetched in both forward and backward
directions. The default direction is forward.
<para>
Once all rows are fetched, every other fetch access returns
no rows.
<para>
Updating data in a cursor is not supported by
<productname>Postgres</productname>,
because mapping cursor updates back to base tables is
not generally possible, similarly to VIEW updates. Consequently,
users must issue explicit replace commands to update data.
<para>
Cursors may only be used inside of transactions because
the data that they store spans multiple user queries.
<REFSECT2 ID="R2-SQL-FETCH-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Refer to MOVE statements to change cursor position.
Refer to DECLARE statements to declare a cursor.
Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements
for further information about transactions.
</REFSECT2>
<REFSECT1 ID="R1-SQL-FETCH-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--set up and use a cursor:
--
BEGIN WORK;
DECLARE liahona CURSOR
FOR SELECT * FROM films;
--Fetch first 5 rows in the cursor liahona:
--
FETCH FORWARD 5 IN liahona;
code |title |did| date_prod|kind |len
-----+-----------------------+---+----------+----------+------
BL101|The Third Man |101|1949-12-23|Drama | 01:44
BL102|The African Queen |101|1951-08-11|Romantic | 01:43
JL201|Une Femme est une Femme|102|1961-03-12|Romantic | 01:25
P_301|Vertigo |103|1958-11-14|Action | 02:08
P_302|Becket |103|1964-02-03|Drama | 02:28
--Fetch previous row:
--
FETCH BACKWARD 1 IN liahona;
code |title |did| date_prod|kind |len
-----+-----------------------+---+----------+----------+------
P_301|Vertigo |103|1958-11-14|Action | 02:08
-- close the cursor and commit work:
--
CLOSE liahona;
COMMIT WORK;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-FETCH-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-FETCH-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
SQL92 specifies some additional capabilities for FETCH statement.
<synopsis>
FETCH [ [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] FROM ] <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
INTO :<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> [, ...]
</synopsis>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Defines the fetch direction with one of the following values:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
NEXT
</TERM>
<LISTITEM>
<PARA>
Fetch next row, it is assumed by default
if selector is omitted.
This is the only legal selector unless cursor is
declared with the SCROLL option.
<VARLISTENTRY>
<TERM>
PRIOR
</TERM>
<LISTITEM>
<PARA>
Fetch previous row.
<VARLISTENTRY>
<TERM>
FIRST
</TERM>
<LISTITEM>
<PARA>
Fetch first row.
<VARLISTENTRY>
<TERM>
LAST
</TERM>
<LISTITEM>
<PARA>
Fetch last row.
<VARLISTENTRY>
<TERM>
ABSOLUTE <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refers to the <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>th row
in the table associated with the cursor.
<VARLISTENTRY>
<TERM>
RELATIVE <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Refers to the <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>th row
relative to the cursor position.
A negative number is equivalent to reversing the sense of the FORWARD and
BACKWARD keywords.
</variablelist>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A cursor previously defined in the same transaction block using BEGIN and DECLARE.
<VARLISTENTRY>
<TERM>
:<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Target host variable(s).
</variablelist>
</REFENTRY>
<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
-->

422
doc/src/sgml/ref/grant.sgml Normal file
View File

@ -0,0 +1,422 @@
<REFENTRY ID="SQL-GRANT">
<REFMETA>
<REFENTRYTITLE>
GRANT
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
GRANT
</REFNAME>
<REFPURPOSE>
Grants access privilege to a user, a group or all users
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [, ...]
TO { PUBLIC | GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> }
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-GRANT-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The possible privileges are:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
SELECT
</TERM>
<LISTITEM>
<PARA>
Access all of the columns of a specific
table/view.
<VARLISTENTRY>
<TERM>
INSERT
</TERM>
<LISTITEM>
<PARA>
Insert data into all columns of a
specific table.
<VARLISTENTRY>
<TERM>
UPDATE
</TERM>
<LISTITEM>
<PARA>
Update all columns of a specific
table.
<VARLISTENTRY>
<TERM>
DELETE
</TERM>
<LISTITEM>
<PARA>
Delete rows from a specific table.
<VARLISTENTRY>
<TERM>
RULE
</TERM>
<LISTITEM>
<PARA>
Define rules on the table/view
(See CREATE RULE statement).
<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Grant all privileges.
</VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an object to which to grant access.
The possible objects are:
<simplelist>
<member>
table
<member>
view
<member>
sequence
<member>
index
</simplelist>
<VARLISTENTRY>
<TERM>
PUBLIC
</TERM>
<LISTITEM>
<PARA>
A short form representing all users.
<VARLISTENTRY>
<TERM>
GROUP <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A <REPLACEABLE CLASS="PARAMETER">group</REPLACEABLE> to whom to grant privileges.
In the current release, the group must be created explicitly as described below.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a user to whom grant privileges. PUBLIC is a short form
representing all users.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-GRANT-2">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
CHANGE
</TERM>
<LISTITEM>
<PARA>
Message returned if successful.
<VARLISTENTRY>
<TERM>
ERROR: ChangeAcl: class "<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>"
not found
</TERM>
<LISTITEM>
<PARA>
Message returned if the specified object is not available or
if it is impossible
to give privileges to the specified group or users.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-GRANT-1">
<REFSECT1INFO>
<DATE>1998-09-01</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
GRANT allows the creator of an object to give specific permissions to
all users (PUBLIC) or to a certain user or group.
Users other than the creator don't have any access permission
unless the creator GRANTs permissions, after the object
is created.
<para>
Once a user has a privilege on an object, he is enabled to exercise
that privilege.
There is no need to GRANT privileges to the creator of
an object, the creator automatically holds ALL privileges, and can
also drop the object.
<REFSECT2 ID="R2-SQL-GRANT-3">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Use the <command>psql \z</command> command
for further information about permissions
on existing objects:
<programlisting>
Database = lusitania
+------------------+---------------------------------------------+
| Relation | Grant/Revoke Permissions |
+------------------+---------------------------------------------+
| mytable | {"=rw","miriam=arwR","group todos=rw"} |
+------------------+---------------------------------------------+
Legend:
uname=arwR -- privileges granted to a user
group gname=arwR -- privileges granted to a GROUP
=arwR -- privileges granted to PUBLIC
r -- SELECT
w -- UPDATE/DELETE
a -- INSERT
R -- RULE
arwR -- ALL
</programlisting>
<tip>
<para>
Currently, to create a GROUP you have to insert
data manually into table pg_group as:
<programlisting>
INSERT INTO pg_group VALUES ('todos');
CREATE USER miriam IN GROUP todos;
</programlisting>
Refer to REVOKE statements to revoke access privileges.
</tip>
</REFSECT2>
<REFSECT1 ID="R1-SQL-GRANT-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
-- grant insert privilege to all users on table films:
--
GRANT INSERT ON films TO PUBLIC;
</programlisting>
<programlisting>
-- grant all privileges to user manuel on view kinds:
--
GRANT ALL ON kinds TO manuel;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-GRANT-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-GRANT-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The SQL92 syntax for GRANT allows setting privileges
for individual columns
within a table, and allows setting a privilege to grant
the same privileges to others.
<SYNOPSIS>
GRANT <REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE> [, ...]
ON <REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] [, ...]
TO { PUBLIC | <REPLACEABLE CLASS="PARAMETER">username</REPLACEABLE> [, ...] }
[ WITH GRANT OPTION ]
</SYNOPSIS>
Fields are compatible with the those in the <acronym>Postgres</acronym>
implementation, with the following additions:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
SELECT
</TERM>
<LISTITEM>
<PARA>
<acronym>SQL92</acronym> permits additional privileges to be specified:
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
REFERENCES
</TERM>
<LISTITEM>
<PARA>
Allowed to reference some or all of the columns of a specific
table/view in integrity constraints.
<VARLISTENTRY>
<TERM>
USAGE
</TERM>
<LISTITEM>
<PARA>
Allowed to use a domain, character set, collation
or translation.
If an object specifies anything other than a table/view,
<REPLACEABLE CLASS="PARAMETER">privilege</REPLACEABLE>
must specify only USAGE.
</variablelist>
<tip>
<para>
Currently, to grant privileges in <productname>Postgres</productname>
to only few columns, you must
create a view having desired columns and then grant privileges
to that view.
</tip>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<variablelist>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">object</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<acronym>SQL92</acronym> allows an additional non-functional keyword:
<simplelist>
<member>
[ TABLE ] table
</simplelist>
<VARLISTENTRY>
<TERM>
CHARACTER SET
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified character set.
<VARLISTENTRY>
<TERM>
COLLATION
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified collation sequence.
<VARLISTENTRY>
<TERM>
TRANSLATION
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified character set translation.
<VARLISTENTRY>
<TERM>
DOMAIN
</TERM>
<LISTITEM>
<PARA>
Allowed to use the specified domain.
</variablelist>
<VARLISTENTRY>
<TERM>
WITH GRANT OPTION
</TERM>
<LISTITEM>
<PARA>
Allowed to grant the same privilege to others.
</variablelist>
</REFENTRY>
<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
-->

215
doc/src/sgml/ref/insert.sgml Normal file
View File

@ -0,0 +1,215 @@
<REFENTRY ID="SQL-INSERT">
<REFMETA>
<REFENTRYTITLE>
INSERT
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
INSERT
</REFNAME>
<REFPURPOSE>
Inserts new rows into a table
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
INSERT INTO <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ]
{ VALUES ( <REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE> [, ...] ) | SELECT <REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE> }
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-INSERT-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of a column in <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">expression</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A valid expression or value to assign to <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A valid query. Refer to the SELECT statement for a further description
of valid arguments.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-INSERT-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
INSERT <ReturnValue>oid</ReturnValue> 1
</TERM>
<LISTITEM>
<PARA>
Message returned if only one row was inserted.
<ReturnValue>oid</ReturnValue> is the row identifier.
<VARLISTENTRY>
<TERM>
INSERT 0 <ReturnValue>#</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
Message returned if more than one rows were inserted.
<ReturnValue>#</ReturnValue> is the number of rows inserted.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-INSERT-1">
<REFSECT1INFO>
<DATE>1998-09-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
INSERT allows one to insert new rows into a table. One can insert
a single row at time or several rows as a result of a query.
The columns in the target list may be listed in any order.
In every column not present in the target list will be inserted
the default value, if column has not a declared default value
it will be assumed as NULL. If the expression for each column
is not of the correct data type, automatic type coercion will be
attempted.
<para>
You must have insert privilege to a table in order to append
to it, as well as select privilege on any table specified
in a WHERE clause.
<REFSECT1 ID="R1-SQL-INSERT-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Insert a single row into table films;
--(in the second example the column date_prod is omitted
--therefore will be stored in it a default value of NULL):
--
INSERT INTO films VALUES
('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute');
INSERT INTO films (code, title, did, date_prod, kind)
VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama');
</ProgramListing>
<ProgramListing>
--Insert a single row into table distributors, note that
--only column "name" is specified, to the non specified
--column "did" will be assigned its default value:
--
INSERT INTO distributors (name) VALUES ('British Lion');
</ProgramListing>
<ProgramListing>
--Insert several rows into table films from table tmp:
--
INSERT INTO films
SELECT * FROM tmp;
</ProgramListing>
<ProgramListing>
--Insert into arrays:
--Create an empty 3x3 gameboard for noughts-and-crosses
--(all of these queries create the same board attribute)
--(Refer to PostgreSQL User's Guide chapter 7 for further
--information about arrays).
INSERT INTO tictactoe (game, board[1:3][1:3])
VALUES (1,'{{"","",""},{},{"",""}}');
INSERT INTO tictactoe (game, board[3][3])
VALUES (2,'{}');
INSERT INTO tictactoe (game, board)
VALUES (3,'{{,,},{,,},{,,}}');
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-INSERT-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-INSERT-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
The INSERT statement is fully compatible with <acronym>SQL92</acronym>.
Possible limitations in features of the
<REPLACEABLE CLASS="PARAMETER">query</REPLACEABLE>
clause are documented for the SELECT statement.
</REFENTRY>
<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
-->