From 7d1e32b51c680eb0c6519f9f42cb8332f99e87ef Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Sat, 5 Sep 1998 06:02:57 +0000 Subject: [PATCH] Add new reference pages adapted from Jose'. --- doc/src/sgml/ref/commands.sgml | 4 + doc/src/sgml/ref/explain.sgml | 162 +++++++++++++ doc/src/sgml/ref/fetch.sgml | 331 ++++++++++++++++++++++++++ doc/src/sgml/ref/grant.sgml | 422 +++++++++++++++++++++++++++++++++ doc/src/sgml/ref/insert.sgml | 215 +++++++++++++++++ 5 files changed, 1134 insertions(+) create mode 100644 doc/src/sgml/ref/explain.sgml create mode 100644 doc/src/sgml/ref/fetch.sgml create mode 100644 doc/src/sgml/ref/grant.sgml create mode 100644 doc/src/sgml/ref/insert.sgml diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index ebf8091b87..8b87a9857d 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 0000000000..166bbbf4c3 --- /dev/null +++ b/doc/src/sgml/ref/explain.sgml @@ -0,0 +1,162 @@ + + + +EXPLAIN + +SQL - Language Statements + + + +EXPLAIN + + +Shows statement execution details. + + + + +1998-09-01 + + +EXPLAIN [ VERBOSE ] query + + + + +1998-09-01 + + +Inputs + + + + + + +VERBOSE + + + +Flag to show detailed query plan. + + + +query + + + +Any query. + + + + + + + +1998-04-15 + + +Outputs + + + + + + +NOTICE: QUERY PLAN: + + + +Explicit query plan from the Postgres backend. + + + +EXPLAIN + + + +Flag sent after query plan is shown. + + + + + + + + +1998-04-15 + + +Description + + + This command outputs details about the supplied query. + The default output is the computed query cost. + VERBOSE displays the full query plan and cost. + + + +1998-04-15 + + +Notes + + + + + + + +Usage + + +To show a query plan for a simple query: + + +postgres=> explain select * from foo; +NOTICE: QUERY PLAN: + +Seq Scan on foo (cost=0.00 size=0 width=4) + +EXPLAIN + + + + + + +Compatibility + + + + + + +1998-09-01 + + +SQL92 + + + There is no EXPLAIN statement defined in SQL92. + + + diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml new file mode 100644 index 0000000000..7a00c7a611 --- /dev/null +++ b/doc/src/sgml/ref/fetch.sgml @@ -0,0 +1,331 @@ + + + +FETCH + +SQL - Language Statements + + + +FETCH + + +Gets rows using a cursor + + + +1998-09-01 + + +FETCH [ selector ] { [ # | ALL ] } { IN | FROM } cursor + + + + +1998-09-01 + + +Inputs + + + + + + +selector + + + +Selector define fetch direction and it can be one + the following: + + + + +FORWARD + + + +fetch next row(s), it is assumed by default + if selector is omitted. + + + +BACKWARD + + + +fetch previous row(s). + + + + + +# + + + +An unsigned integer that specify how many rows to fetch. + + + +ALL + + + +Retrieve all remaining rows. + + + +cursor + + + +An open cursor's name. + + + + + + + +1998-04-15 + + +Outputs + + +FETCH returns the results of the query defined by the specified cursor. +The following messages will be returned if the query fails: + + + + +NOTICE: PerformPortalFetch: portal "cursor" not found + + + +If cursor is not previously declared. +The cursor must be declared within a transaction block. + + + + + + + + +1998-04-15 + + +Description + + + 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. + + + Once all rows are fetched, every other fetch access returns + no rows. + + + Updating data in a cursor is not supported by +Postgres, + 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. + + + Cursors may only be used inside of transactions because + the data that they store spans multiple user queries. + + + +1998-04-15 + + +Notes + + + 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. + + + + + +Usage + + + + --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; + + + + + + +Compatibility + + + + + + +1998-09-01 + + +SQL92 + + + SQL92 specifies some additional capabilities for FETCH statement. + + +FETCH [ [ selector ] FROM ] cursor + INTO :variable [, ...] + + + + + +selector + + + +Defines the fetch direction with one of the following values: + + + + +NEXT + + + +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. + + + +PRIOR + + + +Fetch previous row. + + + +FIRST + + + +Fetch first row. + + + +LAST + + + +Fetch last row. + + + +ABSOLUTE # + + + +Refers to the #th row + in the table associated with the cursor. + + + +RELATIVE # + + + +Refers to the #th row + relative to the cursor position. +A negative number is equivalent to reversing the sense of the FORWARD and + BACKWARD keywords. + + + + + +cursor + + + +A cursor previously defined in the same transaction block using BEGIN and DECLARE. + + + +:variable + + + +Target host variable(s). + + + + + + diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml new file mode 100644 index 0000000000..f0c14c0c17 --- /dev/null +++ b/doc/src/sgml/ref/grant.sgml @@ -0,0 +1,422 @@ + + + +GRANT + +SQL - Language Statements + + + +GRANT + + +Grants access privilege to a user, a group or all users + + + + +1998-04-15 + + +GRANT privilege [, ...] + ON object [, ...] + TO { PUBLIC | GROUP group | username } + + + + +1998-09-01 + + +Inputs + + + + + + +privilege + + + +The possible privileges are: + + + + +SELECT + + + +Access all of the columns of a specific + table/view. + + + +INSERT + + + +Insert data into all columns of a + specific table. + + + +UPDATE + + + +Update all columns of a specific + table. + + + +DELETE + + + +Delete rows from a specific table. + + + +RULE + + + +Define rules on the table/view + (See CREATE RULE statement). + + + +ALL + + + +Grant all privileges. + + + + + +object + + + +The name of an object to which to grant access. + The possible objects are: + + + table + + view + + sequence + + index + + + + +PUBLIC + + + +A short form representing all users. + + + +GROUP group + + + +A group to whom to grant privileges. +In the current release, the group must be created explicitly as described below. + + + +username + + + +The name of a user to whom grant privileges. PUBLIC is a short form +representing all users. + + + + + + + +1998-09-01 + + +Outputs + + + + + + +CHANGE + + + +Message returned if successful. + + + +ERROR: ChangeAcl: class "object" + not found + + + +Message returned if the specified object is not available or +if it is impossible + to give privileges to the specified group or users. + + + + + + + + +1998-09-01 + + +Description + + + 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. + + + 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. + + + +1998-09-01 + + +Notes + + +Use the psql \z command + for further information about permissions + on existing objects: + + 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 + + + + +Currently, to create a GROUP you have to insert + data manually into table pg_group as: + + INSERT INTO pg_group VALUES ('todos'); + CREATE USER miriam IN GROUP todos; + + Refer to REVOKE statements to revoke access privileges. + + + + + + +Usage + + + + -- grant insert privilege to all users on table films: + -- + GRANT INSERT ON films TO PUBLIC; + + + + -- grant all privileges to user manuel on view kinds: + -- + GRANT ALL ON kinds TO manuel; + + + + + + +Compatibility + + + + + + +1998-09-01 + + +SQL92 + + + 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. + + +GRANT privilege [, ...] + ON object [ ( column [, ...] ) ] [, ...] + TO { PUBLIC | username [, ...] } + [ WITH GRANT OPTION ] + + +Fields are compatible with the those in the Postgres +implementation, with the following additions: + + + + +privilege +SELECT + + + +SQL92 permits additional privileges to be specified: + + + + +REFERENCES + + + +Allowed to reference some or all of the columns of a specific +table/view in integrity constraints. + + + +USAGE + + + +Allowed to use a domain, character set, collation + or translation. + If an object specifies anything other than a table/view, +privilege +must specify only USAGE. + + + + + +Currently, to grant privileges in Postgres +to only few columns, you must + create a view having desired columns and then grant privileges + to that view. + + + + +object + + + + + + + +object + + + +SQL92 allows an additional non-functional keyword: + + + +[ TABLE ] table + + + + +CHARACTER SET + + + +Allowed to use the specified character set. + + + +COLLATION + + + +Allowed to use the specified collation sequence. + + + +TRANSLATION + + + +Allowed to use the specified character set translation. + + + +DOMAIN + + + +Allowed to use the specified domain. + + + + + + +WITH GRANT OPTION + + + +Allowed to grant the same privilege to others. + + + + + diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml new file mode 100644 index 0000000000..f11a0e9314 --- /dev/null +++ b/doc/src/sgml/ref/insert.sgml @@ -0,0 +1,215 @@ + + + +INSERT + +SQL - Language Statements + + + +INSERT + + +Inserts new rows into a table + + + +1998-09-02 + + +INSERT INTO table [ ( column [, ...] ) ] + { VALUES ( expression [, ...] ) | SELECT query } + + + + +1998-04-15 + + +Inputs + + + + + + +table + + + +The name of an existing table. + + + +column + + + +The name of a column in table. + + + +expression + + + +A valid expression or value to assign to column. + + + +query + + + +A valid query. Refer to the SELECT statement for a further description + of valid arguments. + + + + + + + +1998-04-15 + + +Outputs + + + + + + +INSERT oid 1 + + + +Message returned if only one row was inserted. +oid is the row identifier. + + + +INSERT 0 # + + + +Message returned if more than one rows were inserted. +# is the number of rows inserted. + + + + + + + + +1998-09-02 + + +Description + + + 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. + + + 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. + + + +Usage + + + + --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'); + + + + --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'); + + + + --Insert several rows into table films from table tmp: + -- + INSERT INTO films + SELECT * FROM tmp; + + + + --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,'{{,,},{,,},{,,}}'); + + + + + + +Compatibility + + + + + + +1998-04-15 + + +SQL92 + + +The INSERT statement is fully compatible with SQL92. +Possible limitations in features of the +query +clause are documented for the SELECT statement. + + + +