diff options
| -rw-r--r-- | doc/src/sgml/ref/commands.sgml | 4 | ||||
| -rw-r--r-- | doc/src/sgml/ref/explain.sgml | 162 | ||||
| -rw-r--r-- | doc/src/sgml/ref/fetch.sgml | 331 | ||||
| -rw-r--r-- | doc/src/sgml/ref/grant.sgml | 422 | ||||
| -rw-r--r-- | doc/src/sgml/ref/insert.sgml | 215 |
5 files changed, 1134 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index ebf8091b875..8b87a9857d4 100644 --- a/doc/src/sgml/ref/commands.sgml +++ b/doc/src/sgml/ref/commands.sgml @@ -27,6 +27,10 @@ &declare; &delete; &dropFunction; +&explain; +&fetch; +&grant; +&insert; &listen; &load; &lock; diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml new file mode 100644 index 00000000000..166bbbf4c32 --- /dev/null +++ b/doc/src/sgml/ref/explain.sgml @@ -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>• +</TERM> +<LISTITEM> +<PARA> +</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +<PARA> +</PARA> +--> diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml new file mode 100644 index 00000000000..7a00c7a6117 --- /dev/null +++ b/doc/src/sgml/ref/fetch.sgml @@ -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>• +</TERM> +<LISTITEM> +<PARA> +</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +<PARA> +</PARA> +--> diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml new file mode 100644 index 00000000000..f0c14c0c174 --- /dev/null +++ b/doc/src/sgml/ref/grant.sgml @@ -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>• +</TERM> +<LISTITEM> +<PARA> +</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +<PARA> +</PARA> +--> diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml new file mode 100644 index 00000000000..f11a0e9314e --- /dev/null +++ b/doc/src/sgml/ref/insert.sgml @@ -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>• +</TERM> +<LISTITEM> +<PARA> +</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +<PARA> +</PARA> +--> |