+++ /dev/null
-
-The page.5 source should be run through pic when generating troff
-output. nroff doesn't handle pic.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/abort.l,v 1.1.1.1 1996/08/18 22:14:19 scrappy Exp $
-.TH ABORT SQL 01/23/93 Postgres95 Postgres95
-.\" XXX This .XA has to go after the .TH so that the index page number goes
-.\" in the right place...
-.SH Abort
-.SH NAME
-abort \(em abort the current transaction
-.SH SYNOPSIS
-.nf
-\fBabort\fP \fB[transaction]\fR
-.fi
-.SH DESCRIPTION
-This command aborts the current transaction and causes all the
-updates made by the transaction to be discarded.
-.IR "abort"
-is functionally equivalent to
-.IR "rollback".
-.SH "SEE ALSO"
-begin(l),
-end(l),
-rollback(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/alter_table.l,v 1.1.1.1 1996/08/18 22:14:19 scrappy Exp $
-.TH "ALTER TABLE" SQL 11/5/95 Postgres95 Postgres95
-.SH NAME
-alter table \(em add attributes to a class
-.SH SYNOPSIS
-.nf
-\fBalter table\fR classname [*]
- \fBadd column\fR attname type
-
-.fi
-.SH DESCRIPTION
-The
-.BR "alter table"
-command
-causes a new attribute to be added to an existing class,
-.IR classname .
-The new attributes and their types are specified
-in the same style and with the the same restrictions as in
-.IR create table (l).
-.PP
-In order to add an attribute to each class in an entire inheritance
-hierarchy, use the
-.IR classname
-of the superclass and append a \*(lq*\*(rq. (By default, the
-attribute will not be added to any of the subclasses.) This should
-.BR always
-be done when adding an attribute to a superclass. If it is not,
-queries on the inheritance hierarchy such as
-.nf
-select * from super* s
-.fi
-will not work because the subclasses will be missing an attribute
-found in the superclass.
-.PP
-For efficiency reasons, default values for added attributes are not
-placed in existing instances of a class. That is, existing instances
-will have NULL values in the new attributes. If non-NULL values are
-desired, a subsequent
-.IR update (l)
-query should be run.
-.PP
-You must own the class in order to change its schema.
-.SH EXAMPLE
-.nf
---
--- add the date of hire to the emp class
---
-alter table emp add column hiredate abstime
-.fi
-.nf
---
--- add a health-care number to all persons
--- (including employees, students, ...)
---
-alter table person * add column health_care_id int4
-.fi
-.SH "SEE ALSO"
-create table (l),
-update (l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/begin.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
-.TH BEGIN SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-begin \(em begins a transaction
-.SH SYNOPSIS
-.nf
-\fBbegin\fP \fB[transaction|work]\fR
-.fi
-.SH DESCRIPTION
-This command begins a user transaction which Postgres will guarantee is
-serializable with respect to all concurrently executing transactions.
-Postgres uses two-phase locking to perform this task. If the transaction
-is committed, Postgres will ensure that all updates are done or none of
-them are done. Transactions have the standard ACID (atomic,
-consistent, isolatable, and durable) property.
-.SH "SEE ALSO"
-abort(l),
-end(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/bki.5,v 1.2 1996/11/09 10:29:44 scrappy Exp $
-.TH BKI 5 11/04/96 Postgres Postgres
-.SH NAME
-*.bki
-.SH DESCRIPTION
-Backend Interface (BKI) files are scripts that are input to the postgres
-backend running in the special "bootstrap" mode that allows it to perform
-database functions without a database system already existing. BKI files
-can therefore be used to create the database system in the first place.
-.PP
-.IR Initdb
-uses BKI files to do just that -- create a database system. However,
-.IR initdb's
-BKI files are generated internally. It generates them using the files
-global1.bki.source and local1.template1.bki.source, which it finds in the
-Postgres "library" directory. They get installed there as part of installing
-Postgres. These .source files get build as part of the Postgres build
-process, by a build program called
-.IR genbki. Genbki
-takes as input Postgres source files that double as
-.IR genbki
-input that builds tables and C header files that describe those
-tables.
-.PP
-The Postgres backend interprets BKI files as described below. This
-description will be easier to understand if the global1.bki.source file is
-at hand as an example. (As explained above, this .source file isn't quite
-a BKI file, but you'll be able to guess what the resulting BKI file would be
-anyway).
-.PP
-Commands are composed of a command name followed by space separated
-arguments. Arguments to a command which begin with a \*(lq$\*(rq are
-treated specially. If \*(lq$$\*(rq are the first two characters, then
-the first \*(lq$\*(rq is ignored and the argument is then processed
-normally. If the \*(lq$\*(rq is followed by space, then it is treated
-as a
-.SM NULL
-value. Otherwise, the characters following the \*(lq$\*(rq are
-interpreted as the name of a macro causing the argument to be replaced
-with the macro's value. It is an error for this macro to be
-undefined.
-.PP
-Macros are defined using
-.nf
-define macro macro_name = macro_value
-.fi
-and are undefined using
-.nf
-undefine macro macro_name
-.fi
-and redefined using the same syntax as define.
-.PP
-Lists of general commands and macro commands
-follow.
-.SH "GENERAL COMMANDS"
-.TP 5n
-.BR "open" " classname"
-Open the class called
-.IR classname
-for further manipulation.
-.TP
-.BR "close" " [classname]"
-Close the open class called
-.IR classname.
-It is an error if
-.IR classname
-is not already opened. If no
-.IR classname
-is given, then the currently open class is closed.
-.TP
-.BR print
-Print the currently open class.
-.TP
-.BR "insert" " [oid=oid_value] " "(" " value1 value2 ... " ")"
-Insert a new instance to the open class using
-.IR value1 ,
-.IR value2 ,
-etc., for its attribute values and
-.IR oid_value
-for its OID. If
-.IR oid_value
-is not \*(lq0\*(rq, then this value will be used as the instance's
-object identifier. Otherwise, it is an error.
-.TP
-.BR "insert (" " value1 value2 ... " ")"
-As above, but the system generates a unique object identifier.
-.TP
-.BR "create" " classname " "(" " name1 = type1, name2 = type2, ... " ")"
-Create a class named
-.IR classname
-with the attributes given in parentheses.
-.TP
-.BR "open (" " name1 = type1, name2 = type2,... " ") as" " classname"
-Open a class named
-.IR classname
-for writing but do not record its existence in the system catalogs.
-(This is primarily to aid in bootstrapping.)
-.TP
-.BR "destroy" " classname"
-Destroy the class named
-.IR classname .
-.TP
-.BR "define index" " index-name " "on" " class-name " "using" " amname "
-( opclass attr | function({attr}) )
-.br
-Create an index named
-.IR index_name
-on the class named
-.IR classname
-using the
-.IR amname
-access method. The fields to index are called
-.IR name1 ,
-.IR name2 ,
-etc., and the operator collections to use are
-.IR collection_1 ,
-.IR collection_2 ,
-etc., respectively.
-.SH "MACRO COMMANDS"
-.TP
-.BR "define function" " macro_name " "as" " rettype function_name ( args )"
-Define a function prototype for a function named
-.IR macro_name
-which has its value of type
-.IR rettype
-computed from the execution
-.IR function_name
-with the arguments
-.IR args
-declared in a C-like manner.
-.TP
-.BR "define macro" " macro_name " "from file" " filename"
-Define a macro named
-.IR macname
-which has its value
-read from the file called
-.IR filename .
-.\" .uh "DEBUGGING COMMANDS"
-.\" .sp
-.\" .in .5i
-.\" r
-.\" .br
-.\" Randomly print the open class.
-.\" .sp
-.\" m -1
-.\" .br
-.\" Toggle display of time information.
-.\" .sp
-.\" m 0
-.\" .br
-.\" Set retrievals to now.
-.\" .sp
-.\" m 1 Jan 1 01:00:00 1988
-.\" .br
-.\" Set retrievals to snapshots of the specfied time.
-.\" .sp
-.\" m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988
-.\" .br
-.\" Set retrievals to ranges of the specified times.
-.\" Either time may be replaced with space
-.\" if an unbounded time range is desired.
-.\" .sp
-.\" \&.A classname natts name1 type1 name2 type2 ...
-.\" .br
-.\" Add attributes named
-.\" .ul
-.\" name1,
-.\" .ul
-.\" name2,
-.\" etc. of
-.\" types
-.\" .ul
-.\" type1,
-.\" .ul
-.\" type2,
-.\" etc. to the
-.\" .ul
-.\" class
-.\" classname.
-.\" .sp
-.\" \&.RR oldclassname newclassname
-.\" .br
-.\" Rename the
-.\" .ul
-.\" oldclassname
-.\" class to
-.\" .ul
-.\" newclassname.
-.\" .sp
-.\" \&.RA classname oldattname newattname
-.\" .br
-.\" Rename the
-.\" .ul
-.\" oldattname
-.\" attribute in the class named
-.\" .ul
-.\" classname
-.\" to
-.\" .ul
-.\" newattname.
-.SH EXAMPLE
-The following set of commands will create the \*(lqpg_opclass\*(rq
-class containing the
-.IR int_ops
-collection as object
-.IR 421,
-print out the class, and then close it.
-.nf
-create pg_opclass (opcname=char16)
-open pg_opclass
-insert oid=421 (int_ops)
-print
-close pg_opclass
-.fi
-.SH "SEE ALSO"
-initdb(1),
-createdb(1),
-create_database(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/built-in.3,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
-.TH BUILT-INS INTRO 11/05/95 Postgres95 Postgres95
-.SH "DESCRIPTION"
-This section describes the data types, functions and operators
-available to users in Postgres as it is distributed.
-.SH "Built-in and System Types"
-.SH "BUILT-IN TYPES"
-This section describes both
-.BR built-in
-data types.
-These Built-in types are
-are installed in every database.
-.PP
-Users may add new types to Postgres using the
-.IR "define type"
-command described in this manual. User-defined types are not
-described in this section.
-.SH "List of built-in types"
-.PP
-.if n .ta 5 +15 +40
-.if t .ta 0.5i +1.5i +3.0i
-.in 0
-.nf
- \fBPOSTGRES Type\fP \fBMeaning\fP
- abstime absolute date and time
- aclitem access control list item
- bool boolean
- box 2-dimensional rectangle
- bpchar blank-padded characters
- bytea variable length array of bytes
- char character
- char2 array of 2 characters
- char4 array of 4 characters
- char8 array of 8 characters
- char16 array of 16 characters
- cid command identifier type
- date ANSI SQL date type
- filename large object filename
- int alias for int4
- integer alias for int4
- int2 two-byte signed integer
- int28 array of 8 int2
- int4 four-byte signed integer
- float alias for float4
- float4 single-precision floating-point number
- float8 double-precision floating-point number
- lseg 2-dimensional line segment
- name a multi-character type for storing system identifiers
- oid object identifier type
- oid8 array of 8 oid
- oidchar16 oid and char16 composed
- oidint2 oid and int2 composed
- oidint4 oid and int4 composed
- path variable-length array of lseg
- point 2-dimensional geometric point
- polygon 2-dimensional polygon
- real alias for float4
- regproc registered procedure
- reltime relative date and time
- smgr storage manager
- smallint alias for int2
- text variable length array of characters
- tid tuple identifier type
- time ANSI SQL time type
- tinterval time interval
- varchar variable-length characters
- xid transaction identifier type
-
-.fi
-.in
-.PP
-As a rule, the built-in types are all either (1) internal types, in
-which case the user should not worry about their external format, or
-(2) have obvious formats. The exceptions to this rule are the three
-time types.
-.SH "Syntax of date and time types"
-.SH "ABSOLUTE TIME"
-Absolute time is specified using the following syntax:
-.nf
-Month Day [ Hour : Minute : Second ] Year [ Timezone ]
-.sp
-where
- Month is Jan, Feb, ..., Dec
- Day is 1, 2, ..., 31
- Hour is 01, 02, ..., 24
- Minute is 00, 01, ..., 59
- Second is 00, 01, ..., 59
- Year is 1901, 1902, ..., 2038
-.fi
-Valid dates are from Dec 13 20:45:53 1901 GMT to Jan 19 03:14:04
-2038 GMT. As of Version 3.0, times are no longer read and written
-using Greenwich Mean Time; the input and output routines default to
-the local time zone.
-.PP
-The special absolute time values \*(lqcurrent\*(rq,
-\*(lqinfinity\*(rq and \*(lq-infinity\*(rq are also provided.
-\*(lqinfinity\*(rq specifies a time later than any valid time, and
-\*(lq-infinity\*(rq specifies a time earlier than any valid time.
-\*(lqcurrent\*(rq indicates that the current time should be
-substituted whenever this value appears in a computation.
-.PP
-The strings \*(lqnow\*(rq and \*(lqepoch\*(rq can be used to specify
-time values. \*(lqnow\*(rq means the current time, and differs from
-\*(lqcurrent\*(rq in that the current time is immediately substituted
-for it. \*(lqepoch\*(rq means Jan 1 00:00:00 1970 GMT.
-.SH "RELATIVE TIME"
-Relative time is specified with the following syntax:
-.nf
-@ Quantity Unit [Direction]
-.sp
-where
- Quantity is `1', `2', ...
- Unit is ``second'', ``minute'', ``hour'', ``day'', ``week'',
- ``month'' (30-days), or ``year'' (365-days),
- or PLURAL of these units.
- Direction is ``ago''
-.fi
-.PP
-.RB ( Note :
-Valid relative times are less than or equal to 68 years.)
-In addition, the special relative time \*(lqUndefined RelTime\*(rq is
-provided.
-.SH "TIME RANGES"
-Time ranges are specified as:
-.nf
-[ 'abstime' 'abstime']
-.fi
-where
-.IR abstime
-is a time in the absolute time format. Special abstime values such as
-\*(lqcurrent\*(rq, \*(lqinfinity\*(rq and \*(lq-infinity\*(rq can be used.
-.SH "Built-in operators and functions"
-.SH OPERATORS
-Postgres provides a large number of built-in operators on system types.
-These operators are declared in the system catalog
-\*(lqpg_operator\*(rq. Every entry in \*(lqpg_operator\*(rq includes
-the object ID of the procedure that implements the operator.
-.PP
-Users may invoke operators using the operator name, as in
-.nf
-select * from emp where salary < 40000;
-.fi
-Alternatively, users may call the functions that implement the
-operators directly. In this case, the query above would be expressed
-as
-.nf
-select * from emp where int4lt(salary, 40000);
-.fi
-The rest of this section provides a list of the built-in operators and
-the functions that implement them. Binary operators are listed first,
-followed by unary operators.
-.SH "BINARY OPERATORS"
-This list was generated from the Postgres system catalogs with the
-query:
-
-.nf
-SELECT
- t0.typname AS result,
- t1.typname AS left_type,
- t2.typname AS right_type,
- o.oprname AS operatr,
- p.proname AS func_name
-FROM pg_proc p, pg_type t0,
- pg_type t1, pg_type t2,
- pg_operator o
-WHERE p.prorettype = t0.oid AND
- RegprocToOid(o.oprcode) = p.oid AND
- p.pronargs = 2 AND
- o.oprleft = t1.oid AND
- o.oprright = t2.oid
-ORDER BY result, left_type, right_type, operatr;
-.fi
-
-These operations are cast in terms of SQL types and so are
-.BR not
-directly usable as C function prototypes.
-
-.nf
-Operators:
-
-general
- <\(eq less or equal
- <> inequality
- < less than
- <\(eq greater or equal
- >\(eq greater or equal
- > greater than
- \(eq equality
- ~ A matches regular expression B, case-sensitive
- !~ A does not match regular expression B, case-sensitive
- ~* A matches regular expression B, case-insensitive.
- !~* A does not match regular expression B, case-insensitive
- ~~ A matches LIKE expression B, case-sensitive
- !~~ A does not match LIKE expression B, case-sensitive
-
- + addition
- \(mi subtraction
- * multiplication
- / division
- % modulus
- @ absolute value
-
-float8
- ^ exponentiation
- % truncate to integer
- |/ square root
- ||/ cube root
- : exponential function
- ; natural logarithm
-
-point
- !< A is left of B
- !> A is right of B
- !^ A is above B
- !| A is below B
- \(eq|\(eq equality
- ===> point inside box
- ===` point on path
- <===> distance between points
-
-box
- && boxes overlap
- &< box A overlaps box B, but does not extend to right of box B
- &> box A overlaps box B, but does not extend to left of box B
- << A is left of B
- \(eq area equal
- < area less than
- <\(eq area less or equal
- >\(eq area greater or equal
- > area greater than
- >> A is right of B
- @ A is contained in B
- ~\(eq box equality
- ~= A same as B
- ~ A contains B
- @@ center of box
-
-polygon
- && polygons overlap
- &< A overlaps B but does not extend to right of B
- &> A overlaps B but does not extend to left of B
- << A is left of B
- >> A is right of B
- @ A is contained by B
- ~\(eq equality
- ~= A same as B
- ~ A contains B
-
-tinterval
- #<\(eq interval length less or equal reltime
- #<> interval length not equal to reltime.
- #< interval length less than reltime
- #\(eq interval length equal to reltime
- #>\(eq interval length greater or equal reltime
- #> interval length greater than reltime
- && intervals overlap
- << A contains B
- \(eq equality
- <> interval bounded by two abstimes
- <?> abstime in tinterval
- | start of interval
- <#> convert to interval
-
-result |left_type |right_type|operatr|func_name
----------+----------+----------+-------+---------------
-_aclitem |_aclitem |aclitem |+ |aclinsert
-_aclitem |_aclitem |aclitem |- |aclremove
-abstime |abstime |reltime |+ |timepl
-abstime |abstime |reltime |- |timemi
-bool |_abstime |_abstime |= |array_eq
-bool |_aclitem |_aclitem |= |array_eq
-bool |_aclitem |aclitem |~ |aclcontains
-bool |_bool |_bool |= |array_eq
-bool |_box |_box |= |array_eq
-bool |_bytea |_bytea |= |array_eq
-bool |_char |_char |= |array_eq
-bool |_char16 |_char16 |= |array_eq
-bool |_cid |_cid |= |array_eq
-bool |_filename |_filename |= |array_eq
-bool |_float4 |_float4 |= |array_eq
-bool |_float8 |_float8 |= |array_eq
-bool |_int2 |_int2 |= |array_eq
-bool |_int28 |_int28 |= |array_eq
-bool |_int4 |_int4 |= |array_eq
-bool |_lseg |_lseg |= |array_eq
-bool |_name |_name |= |array_eq
-bool |_oid |_oid |= |array_eq
-bool |_oid8 |_oid8 |= |array_eq
-bool |_path |_path |= |array_eq
-bool |_point |_point |= |array_eq
-bool |_polygon |_polygon |= |array_eq
-bool |_ref |_ref |= |array_eq
-bool |_regproc |_regproc |= |array_eq
-bool |_reltime |_reltime |= |array_eq
-bool |_stub |_stub |= |array_eq
-bool |_text |_text |= |array_eq
-bool |_tid |_tid |= |array_eq
-bool |_tinterval|_tinterval|= |array_eq
-bool |_xid |_xid |= |array_eq
-bool |abstime |abstime |< |abstimelt
-bool |abstime |abstime |<= |abstimele
-bool |abstime |abstime |<> |abstimene
-bool |abstime |abstime |= |abstimeeq
-bool |abstime |abstime |> |abstimegt
-bool |abstime |abstime |>= |abstimege
-bool |abstime |tinterval |<?> |ininterval
-bool |bool |bool |<> |boolne
-bool |bool |bool |= |booleq
-bool |box |box |&& |box_overlap
-bool |box |box |&< |box_overleft
-bool |box |box |&> |box_overright
-bool |box |box |< |box_lt
-bool |box |box |<< |box_left
-bool |box |box |<= |box_le
-bool |box |box |= |box_eq
-bool |box |box |> |box_gt
-bool |box |box |>= |box_ge
-bool |box |box |>> |box_right
-bool |box |box |@ |box_contained
-bool |box |box |~ |box_contain
-bool |box |box |~= |box_same
-bool |bpchar |bpchar |< |bpcharlt
-bool |bpchar |bpchar |<= |bpcharle
-bool |bpchar |bpchar |<> |bpcharne
-bool |bpchar |bpchar |= |bpchareq
-bool |bpchar |bpchar |> |bpchargt
-bool |bpchar |bpchar |>= |bpcharge
-bool |bpchar |text |!~ |textregexne
-bool |bpchar |text |!~* |texticregexne
-bool |bpchar |text |!~~ |textnlike
-bool |bpchar |text |~ |textregexeq
-bool |bpchar |text |~* |texticregexeq
-bool |bpchar |text |~~ |textlike
-bool |char |char |< |charlt
-bool |char |char |<= |charle
-bool |char |char |<> |charne
-bool |char |char |= |chareq
-bool |char |char |> |chargt
-bool |char |char |>= |charge
-bool |char16 |char16 |< |char16lt
-bool |char16 |char16 |<= |char16le
-bool |char16 |char16 |<> |char16ne
-bool |char16 |char16 |= |char16eq
-bool |char16 |char16 |> |char16gt
-bool |char16 |char16 |>= |char16ge
-bool |char16 |text |!~ |char16regexne
-bool |char16 |text |!~* |char16icregexne
-bool |char16 |text |!~~ |char16nlike
-bool |char16 |text |!~~ |char16nlike
-bool |char16 |text |~ |char16regexeq
-bool |char16 |text |~* |char16icregexeq
-bool |char16 |text |~~ |char16like
-bool |char16 |text |~~ |char16like
-bool |char2 |char2 |< |char2lt
-bool |char2 |char2 |<= |char2le
-bool |char2 |char2 |<> |char2ne
-bool |char2 |char2 |= |char2eq
-bool |char2 |char2 |> |char2gt
-bool |char2 |char2 |>= |char2ge
-bool |char2 |text |!~ |char2regexne
-bool |char2 |text |!~* |char2icregexne
-bool |char2 |text |!~~ |char2nlike
-bool |char2 |text |~ |char2regexeq
-bool |char2 |text |~* |char2icregexeq
-bool |char2 |text |~~ |char2like
-bool |char4 |char4 |< |char4lt
-bool |char4 |char4 |<= |char4le
-bool |char4 |char4 |<> |char4ne
-bool |char4 |char4 |= |char4eq
-bool |char4 |char4 |> |char4gt
-bool |char4 |char4 |>= |char4ge
-bool |char4 |text |!~ |char4regexne
-bool |char4 |text |!~* |char4icregexne
-bool |char4 |text |!~~ |char4nlike
-bool |char4 |text |~ |char4regexeq
-bool |char4 |text |~* |char4icregexeq
-bool |char4 |text |~~ |char4like
-bool |char8 |char8 |< |char8lt
-bool |char8 |char8 |<= |char8le
-bool |char8 |char8 |<> |char8ne
-bool |char8 |char8 |= |char8eq
-bool |char8 |char8 |> |char8gt
-bool |char8 |char8 |>= |char8ge
-bool |char8 |text |!~ |char8regexne
-bool |char8 |text |!~* |char8icregexne
-bool |char8 |text |!~~ |char8nlike
-bool |char8 |text |~ |char8regexeq
-bool |char8 |text |~* |char8icregexeq
-bool |char8 |text |~~ |char8like
-bool |date |date |< |date_lt
-bool |date |date |<= |date_le
-bool |date |date |<> |date_ne
-bool |date |date |= |date_eq
-bool |date |date |> |date_gt
-bool |date |date |>= |date_ge
-bool |float4 |float4 |< |float4lt
-bool |float4 |float4 |<= |float4le
-bool |float4 |float4 |<> |float4ne
-bool |float4 |float4 |= |float4eq
-bool |float4 |float4 |> |float4gt
-bool |float4 |float4 |>= |float4ge
-bool |float4 |float8 |< |float48lt
-bool |float4 |float8 |<= |float48le
-bool |float4 |float8 |<> |float48ne
-bool |float4 |float8 |= |float48eq
-bool |float4 |float8 |> |float48gt
-bool |float4 |float8 |>= |float48ge
-bool |float8 |float4 |< |float84lt
-bool |float8 |float4 |<= |float84le
-bool |float8 |float4 |<> |float84ne
-bool |float8 |float4 |= |float84eq
-bool |float8 |float4 |> |float84gt
-bool |float8 |float4 |>= |float84ge
-bool |float8 |float8 |< |float8lt
-bool |float8 |float8 |<= |float8le
-bool |float8 |float8 |<> |float8ne
-bool |float8 |float8 |= |float8eq
-bool |float8 |float8 |> |float8gt
-bool |float8 |float8 |>= |float8ge
-bool |int2 |int2 |< |int2lt
-bool |int2 |int2 |<= |int2le
-bool |int2 |int2 |<> |int2ne
-bool |int2 |int2 |= |int2eq
-bool |int2 |int2 |> |int2gt
-bool |int2 |int2 |>= |int2ge
-bool |int4 |int4 |< |int4lt
-bool |int4 |int4 |<= |int4le
-bool |int4 |int4 |<> |int4ne
-bool |int4 |int4 |= |int4eq
-bool |int4 |int4 |> |int4gt
-bool |int4 |int4 |>= |int4ge
-bool |int4 |name |!!= |int4notin
-bool |int4 |oid |= |int4eqoid
-bool |name |name |< |namelt
-bool |name |name |<= |namele
-bool |name |name |<> |namene
-bool |name |name |= |nameeq
-bool |name |name |> |namegt
-bool |name |name |>= |namege
-bool |name |text |!~ |nameregexne
-bool |name |text |!~* |nameicregexne
-bool |name |text |!~~ |namenlike
-bool |name |text |~ |nameregexeq
-bool |name |text |~* |nameicregexeq
-bool |name |text |~~ |namelike
-bool |oid |int4 |= |oideqint4
-bool |oid |name |!!= |oidnotin
-bool |oid |oid |< |int4lt
-bool |oid |oid |<= |int4le
-bool |oid |oid |<> |oidne
-bool |oid |oid |= |oideq
-bool |oid |oid |> |int4gt
-bool |oid |oid |>= |int4ge
-bool |oidint2 |oidint2 |< |oidint2lt
-bool |oidint2 |oidint2 |<= |oidint2le
-bool |oidint2 |oidint2 |<> |oidint2ne
-bool |oidint2 |oidint2 |= |oidint2eq
-bool |oidint2 |oidint2 |> |oidint2gt
-bool |oidint2 |oidint2 |>= |oidint2ge
-bool |oidint4 |oidint4 |< |oidint4lt
-bool |oidint4 |oidint4 |<= |oidint4le
-bool |oidint4 |oidint4 |<> |oidint4ne
-bool |oidint4 |oidint4 |= |oidint4eq
-bool |oidint4 |oidint4 |> |oidint4gt
-bool |oidint4 |oidint4 |>= |oidint4ge
-bool |oidname |oidname |< |oidnamelt
-bool |oidname |oidname |<= |oidnamele
-bool |oidname |oidname |<> |oidnamene
-bool |oidname |oidname |= |oidnameeq
-bool |oidname |oidname |> |oidnamegt
-bool |oidname |oidname |>= |oidnamege
-bool |point |box |===> |on_pb
-bool |point |path |===` |on_ppath
-bool |point |point |!< |point_left
-bool |point |point |!> |point_right
-bool |point |point |!^ |point_above
-bool |point |point |!\| |point_below
-bool |point |point |=\|= |point_eq
-bool |polygon |polygon |&& |poly_overlap
-bool |polygon |polygon |&< |poly_overleft
-bool |polygon |polygon |&> |poly_overright
-bool |polygon |polygon |<< |poly_left
-bool |polygon |polygon |>> |poly_right
-bool |polygon |polygon |@ |poly_contained
-bool |polygon |polygon |~ |poly_contain
-bool |polygon |polygon |~= |poly_same
-bool |reltime |reltime |< |reltimelt
-bool |reltime |reltime |<= |reltimele
-bool |reltime |reltime |<> |reltimene
-bool |reltime |reltime |= |reltimeeq
-bool |reltime |reltime |> |reltimegt
-bool |reltime |reltime |>= |reltimege
-bool |text |text |!~ |textregexne
-bool |text |text |!~* |texticregexne
-bool |text |text |!~~ |textnlike
-bool |text |text |< |text_lt
-bool |text |text |<= |text_le
-bool |text |text |<> |textne
-bool |text |text |= |texteq
-bool |text |text |> |text_gt
-bool |text |text |>= |text_ge
-bool |text |text |~ |textregexeq
-bool |text |text |~* |texticregexeq
-bool |text |text |~~ |textlike
-bool |time |time |< |time_lt
-bool |time |time |<= |time_le
-bool |time |time |<> |time_ne
-bool |time |time |= |time_eq
-bool |time |time |> |time_gt
-bool |time |time |>= |time_ge
-bool |tinterval |reltime |#< |intervallenlt
-bool |tinterval |reltime |#<= |intervallenle
-bool |tinterval |reltime |#<> |intervallenne
-bool |tinterval |reltime |#= |intervalleneq
-bool |tinterval |reltime |#> |intervallengt
-bool |tinterval |reltime |#>= |intervallenge
-bool |tinterval |tinterval |&& |intervalov
-bool |tinterval |tinterval |<< |intervalct
-bool |tinterval |tinterval |= |intervaleq
-bool |varchar |text |!~ |textregexne
-bool |varchar |text |!~* |texticregexne
-bool |varchar |text |!~~ |textnlike
-bool |varchar |text |~ |textregexeq
-bool |varchar |text |~* |texticregexeq
-bool |varchar |text |~~ |textlike
-bool |varchar |varchar |< |varcharlt
-bool |varchar |varchar |<= |varcharle
-bool |varchar |varchar |<> |varcharne
-bool |varchar |varchar |= |varchareq
-bool |varchar |varchar |> |varchargt
-bool |varchar |varchar |>= |varcharge
-char |char |char |* |charmul
-char |char |char |+ |charpl
-char |char |char |- |charmi
-char |char |char |/ |chardiv
-float4 |float4 |float4 |* |float4mul
-float4 |float4 |float4 |+ |float4pl
-float4 |float4 |float4 |- |float4mi
-float4 |float4 |float4 |/ |float4div
-float8 |float4 |float8 |* |float48mul
-float8 |float4 |float8 |+ |float48pl
-float8 |float4 |float8 |- |float48mi
-float8 |float4 |float8 |/ |float48div
-float8 |float8 |float4 |* |float84mul
-float8 |float8 |float4 |+ |float84pl
-float8 |float8 |float4 |- |float84mi
-float8 |float8 |float4 |/ |float84div
-float8 |float8 |float8 |* |float8mul
-float8 |float8 |float8 |+ |float8pl
-float8 |float8 |float8 |- |float8mi
-float8 |float8 |float8 |/ |float8div
-float8 |float8 |float8 |^ |dpow
-int2 |int2 |int2 |% |int2mod
-int2 |int2 |int2 |* |int2mul
-int2 |int2 |int2 |+ |int2pl
-int2 |int2 |int2 |- |int2mi
-int2 |int2 |int2 |/ |int2div
-int4 |int2 |int4 |% |int24mod
-int4 |int2 |int4 |* |int24mul
-int4 |int2 |int4 |+ |int24pl
-int4 |int2 |int4 |- |int24mi
-int4 |int2 |int4 |/ |int24div
-int4 |int2 |int4 |< |int24lt
-int4 |int2 |int4 |<= |int24le
-int4 |int2 |int4 |<> |int24ne
-int4 |int2 |int4 |= |int24eq
-int4 |int2 |int4 |> |int24gt
-int4 |int2 |int4 |>= |int24ge
-int4 |int4 |int2 |% |int42mod
-int4 |int4 |int2 |* |int42mul
-int4 |int4 |int2 |+ |int42pl
-int4 |int4 |int2 |- |int42mi
-int4 |int4 |int2 |/ |int42div
-int4 |int4 |int2 |< |int42lt
-int4 |int4 |int2 |<= |int42le
-int4 |int4 |int2 |<> |int42ne
-int4 |int4 |int2 |= |int42eq
-int4 |int4 |int2 |> |int42gt
-int4 |int4 |int2 |>= |int42ge
-int4 |int4 |int4 |% |int4mod
-int4 |int4 |int4 |* |int4mul
-int4 |int4 |int4 |+ |int4pl
-int4 |int4 |int4 |- |int4mi
-int4 |int4 |int4 |/ |int4div
-int4 |point |point |<===> |pointdist
-tinterval|abstime |abstime |<#> |mktinterval
-
-
-.fi
-.SH "LEFT UNARY OPERATORS"
-The table below gives the left unary operators that are
-registered in the system catalogs.
-
-This list was generated from the Postgres system catalogs with the query:
-
-.nf
-SELECT o.oprname AS left_unary,
- right.typname AS operand,
- result.typname AS return_type
-FROM pg_operator o, pg_type right, pg_type result
-WHERE o.oprkind = 'l' AND -- left unary
- o.oprright = right.oid AND
- o.oprresult = result.oid
-ORDER BY operand;
-
-left_unary|operand |return_type
-----------+---------+-----------
-@@ |box |point
-@ |float4 |float4
-- |float4 |float4
-; |float8 |float8
-: |float8 |float8
-% |float8 |float8
-\|\|/ |float8 |float8
-\|/ |float8 |float8
-@ |float8 |float8
-- |float8 |float8
-- |int2 |int2
-- |int4 |int4
-!! |int4 |int4
-\| |tinterval|abstime
-
-.fi
-.in
-.SH "RIGHT UNARY OPERATORS"
-The table below gives the right unary operators that are
-registered in the system catalogs.
-
-This list was generated from the Postgres system catalogs with the query:
-
-.nf
-SELECT o.oprname AS right_unary,
- left.typname AS operand,
- result.typname AS return_type
-FROM pg_operator o, pg_type left, pg_type result
-WHERE o.oprkind = 'r' AND -- right unary
- o.oprleft = left.oid AND
- o.oprresult = result.oid
-ORDER BY operand;
-
-right_unary|operand|return_type
------------+-------+-----------
-% |float8 |float8
-! |int4 |int4
-
-.fi
-.in
-.SH "AGGREGATE FUNCTIONS"
-The table below gives the aggregate functions that are
-registered in the system catalogs.
-
-This list was generated from the Postgres system catalogs with the query:
-
-.nf
-SELECT a.aggname, t.typname
-FROM pg_aggregate a, pg_type t
-WHERE a.aggbasetype = t.oid
-ORDER BY aggname, typname;
-
-aggname|typname
--------+-------
-avg |float4
-avg |float8
-avg |int2
-avg |int4
-max |float4
-max |float8
-max |int2
-max |int4
-min |float4
-min |float8
-min |int2
-min |int4
-sum |float4
-sum |float8
-sum |int2
-sum |int4
-
-\fBcount\fR is also available.
-
-.fi
-.in
-.SH "SEE ALSO"
-For examples on specifying literals of built-in types, see
-.IR SQL(l).
-.SH BUGS
-.PP
-Although most of the input and output functions correponding to the
-base types (e.g., integers and floating point numbers) do some
-error-checking, none of them are particularly rigorous about it. More
-importantly, almost none of the operators and functions (e.g.,
-addition and multiplication) perform any error-checking at all.
-Consequently, many of the numeric operations will (for example)
-silently underflow or overflow.
-.PP
-Some of the input and output functions are not invertible. That is,
-the result of an output function may lose precision when compared to
-the original input.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/catalogs.3,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
-.TH "SYSTEM CATALOGS" INTRO 03/13/94 Postgres95 Postgres95
-.SH "Section 7 \(em System Catalogs"
-.de LS
-.PP
-.if n .ta 5 +13 +13
-.if t .ta 0.5i +1.3i +1.3i
-.in 0
-.nf
-..
-.de LE
-.fi
-.in
-..
-.SH "DESCRIPTION"
-In this
-section we list each of the attributes of the system catalogs and
-define their meanings.
-.SH "CLASS/TYPE SYSTEM CATALOGS"
-These catalogs form the core of the extensibility system:
-.LS
- \fBname\fP \fBshared/local\fP \fBdescription\fP
- pg_aggregate local aggregate functions
- pg_am local access methods
- pg_amop local operators usable with specific access methods
- pg_amproc local procedures used with specific access methods
- pg_attribute local class attributes
- pg_class local classes
- pg_index local secondary indices
- pg_inherits local class inheritance hierarchy
- pg_language local procedure implementation languages
- pg_opclass local operator classes
- pg_operator local query language operators
- pg_proc local procedures (functions)
- pg_type local data types
-.LE
-.SH "ENTITIES"
-These catalogs deal with identification of entities known throughout
-the site:
-.LS
- \fBname\fP \fBshared/local\fP \fBdescription\fP
- pg_database shared current databases
- pg_group shared user groups
- pg_user shared valid users
-.LE
-.SH "RULE SYSTEM CATALOGS"
-.LS
- \fBname\fP \fBshared/local\fP \fBdescription\fP
- pg_listener local processes waiting on alerters
- pg_prs2plans local instance system procedures
- pg_prs2rule local instance system rules
- pg_prs2stub local instance system ``stubs''
- pg_rewrite local rewrite system information
-.LE
-.SH "LARGE OBJECT CATALOGS"
-.PP
-These catalogs are specific to the Inversion file system and large
-objects in general:
-.LS
- \fBname\fP \fBshared/local\fP \fBdescription\fP
- pg_lobj local description of a large object
- pg_naming local Inversion name space mapping
- pg_platter local jukebox platter inventory
- pg_plmap local jukebox platter extent map
-.LE
-.SH "INTERNAL CATALOGS"
-.PP
-These catalogs are internal classes that are not stored as normal
-heaps and cannot be accessed through normal means (attempting to do so
-causes an error).
-.LS
- \fBname\fP \fBshared/local\fP \fBdescription\fP
- pg_log shared transaction commit/abort log
- pg_magic shared magic constant
- pg_time shared commit/abort times
- pg_variable shared special variable values
-.LE
-.PP
-There are several other classes defined with \*(lqpg_\*(rq names.
-Aside from those that end in \*(lqind\*(rq (secondary indices), these
-are all obsolete or otherwise deprecated.
-.SH "CLASS/TYPE SYSTEM CATALOGS"
-.PP
-The following catalogs relate to the class/type system.
-.nf M
-/*
- * aggregates
- *
- * see DEFINE AGGREGATE for an explanation of transition functions
- */
-pg_aggregate
- NameData aggname /* aggregate name (e.g., "count") */
- oid aggowner /* usesysid of creator */
- regproc aggtransfn1 /* first transition function */
- regproc aggtransfn2 /* second transition function */
- regproc aggfinalfn /* final function */
- oid aggbasetype /* type of data on which aggregate
- operates */
- oid aggtranstype1 /* type returned by aggtransfn1 */
- oid aggtranstype2 /* type returned by aggtransfn2 */
- oid aggfinaltype /* type returned by aggfinalfn */
- text agginitval1 /* external format of initial
- (starting) value of aggtransfn1 */
- text agginitval2 /* external format of initial
- (starting) value of aggtransfn2 */
-.fi
-.nf M
-pg_am
- NameData amname /* access method name */
- oid amowner /* usesysid of creator */
- char amkind /* - deprecated */
- /* originally:
- h=hashed
- o=ordered
- s=special */
- int2 amstrategies /* total NUMBER of strategies by which
- we can traverse/search this AM */
- int2 amsupport /* total NUMBER of support functions
- that this AM uses */
- regproc amgettuple /* "next valid tuple" function */
- regproc aminsert /* "insert this tuple" function */
- regproc amdelete /* "delete this tuple" function */
- regproc amgetattr /* - deprecated */
- regproc amsetlock /* - deprecated */
- regproc amsettid /* - deprecated */
- regproc amfreetuple /* - deprecated */
- regproc ambeginscan /* "start new scan" function */
- regproc amrescan /* "restart this scan" function */
- regproc amendscan /* "end this scan" function */
- regproc ammarkpos /* "mark current scan position"
- function */
- regproc amrestrpos /* "restore marked scan position"
- function */
- regproc amopen /* - deprecated */
- regproc amclose /* - deprecated */
- regproc ambuild /* "build new index" function */
- regproc amcreate /* - deprecated */
- regproc amdestroy /* - deprecated */
-.fi
-.nf M
-pg_amop
- oid amopid /* access method with which this
- operator be used */
- oid amopclaid /* operator class with which this
- operator can be used */
- oid amopopr /* the operator */
- int2 amopstrategy /* traversal/search strategy number
- to which this operator applies */
- regproc amopselect /* function to calculate the operator
- selectivity */
- regproc amopnpages /* function to calculate the number of
- pages that will be examined */
-.fi
-.nf M
-pg_amproc
- oid amid /* access method with which this
- procedure is associated */
- oid amopclaid /* operator class with which this
- operator can be used */
- oid amproc /* the procedure */
- int2 amprocnum /* support function number to which
- this operator applies */
-.fi
-.nf M
-pg_class
- NameData relname /* class name */
- oid relowner /* usesysid of owner */
- oid relam /* access method */
- int4 relpages /* # of 8KB pages */
- int4 reltuples /* # of instances */
- abstime relexpires /* time after which instances are
- deleted from non-archival storage */
- reltime relpreserved /* timespan after which instances are
- deleted from non-archival storage */
- bool relhasindex /* does the class have a secondary
- index? */
- bool relisshared /* is the class shared or local? */
- char relkind /* type of relation:
- i=index
- r=relation (heap)
- s=special
- u=uncatalogued (temporary) */
- char relarch /* archive mode:
- h=heavy
- l=light
- n=none */
- int2 relnatts /* current # of non-system
- attributes */
- int2 relsmgr /* storage manager:
- 0=magnetic disk
- 1=sony WORM jukebox
- 2=main memory */
- int28 relkey /* - unused */
- oid8 relkeyop /* - unused */
- aclitem relacl[1] /* access control lists */
-.fi
-.nf M
-pg_attribute
- oid attrelid /* class containing this attribute */
- NameData attname /* attribute name */
- oid atttypid /* attribute type */
- oid attdefrel /* - deprecated */
- int4 attnvals /* - deprecated */
- oid atttyparg /* - deprecated */
- int2 attlen /* attribute length, in bytes
- -1=variable */
- int2 attnum /* attribute number
- >0=user attribute
- <0=system attribute */
- int2 attbound /* - deprecated */
- bool attbyval /* type passed by value? */
- bool attcanindex /* - deprecated */
- oid attproc /* - deprecated */
- int4 attnelems /* # of array dimensions */
- int4 attcacheoff /* cached offset into tuple */
- bool attisset /* is attribute set-valued? */
-.fi
-.nf M
-pg_inherits
- oid inhrel /* child class */
- oid inhparent /* parent class */
- int4 inhseqno /* - deprecated */
-.fi
-.nf M
- oid indexrelid /* oid of secondary index class */
- oid indrelid /* oid of indexed heap class */
- oid indproc /* function to compute index key from
- attribute(s) in heap
- 0=not a functional index */
- int28 indkey /* attribute numbers of key
- attribute(s) */
- oid8 indclass /* opclass of each key */
- bool indisclustered /* is the index clustered?
- - unused */
- bool indisarchived /* is the index archival?
- - unused */
- text indpred /* query plan for partial index
- predicate */
-.fi
-.nf M
-pg_type
- NameData typname /* type name */
- oid typowner /* usesysid of owner */
- int2 typlen /* length in internal form
- -1=variable-length */
- int2 typprtlen /* length in external form */
- bool typbyval /* type passed by value? */
- char typtype /* kind of type:
- c=catalog (composite)
- b=base */
- bool typisdefined /* defined or still a shell? */
- char typdelim /* delimiter for array external form */
- oid typrelid /* class (if composite) */
- oid typelem /* type of each array element */
- regproc typinput /* external-internal conversion
- function */
- regproc typoutput /* internal-external conversion
- function */
- regproc typreceive /* client-server conversion function */
- regproc typsend /* server-client conversion function */
- text typdefault /* default value */
-.fi
-.nf M
-pg_operator
- NameData oprname /* operator name */
- oid oprowner /* usesysid of owner */
- int2 oprprec /* - deprecated */
- char oprkind /* kind of operator:
- b=binary
- l=left unary
- r=right unary */
- bool oprisleft /* is operator left/right associative? */
- bool oprcanhash /* is operator usable for hashjoin? */
- oid oprleft /* left operand type */
- oid oprright /* right operand type */
- oid oprresult /* result type */
- oid oprcom /* commutator operator */
- oid oprnegate /* negator operator */
- oid oprlsortop /* sort operator for left operand */
- oid oprrsortop /* sort operator for right operand */
- regproc oprcode /* function implementing this operator */
- regproc oprrest /* function to calculate operator
- restriction selectivity */
- regproc oprjoin /* function to calculate operator
- join selectivity */
-.fi
-.nf M
-pg_opclass
- NameData opcname /* operator class name */
-.fi
-.nf M
-pg_proc
- NameData proname /* function name */
- oid proowner /* usesysid of owner */
- oid prolang /* function implementation language */
- bool proisinh /* - deprecated */
- bool proistrusted /* run in server or untrusted function
- process? */
- bool proiscachable /* can the function return values be
- cached? */
- int2 pronargs /* # of arguments */
- bool proretset /* does the function return a set?
- - unused */
- oid prorettype /* return type */
- oid8 proargtypes /* argument types */
- int4 probyte_pct /* % of argument size (in bytes) that
- needs to be examined in order to
- compute the function */
- int4 properbyte_cpu /* sensitivity of the function's
- running time to the size of its
- inputs */
- int4 propercall_cpu /* overhead of the function's
- invocation (regardless of input
- size) */
- int4 prooutin_ratio /* size of the function's output as a
- percentage of the size of the input */
- text prosrc /* function definition (postquel only) */
- bytea probin /* path to object file (C only) */
-.fi
-.nf M
-pg_language
- NameData lanname /* language name */
- text lancompiler /* - deprecated */
-.fi
-.SH "ENTITIES"
-.nf M
-pg_database
- NameData datname /* database name */
- oid datdba /* usesysid of database administrator */
- text datpath /* directory of database under
- $PGDATA */
-.fi
-.nf M
-pg_group
- NameData groname /* group name */
- int2 grosysid /* group's UNIX group id */
- int2 grolist[1] /* list of usesysids of group members */
-.fi
-.nf M
-pg_user
- NameData usename /* user's name */
- int2 usesysid /* user's UNIX user id */
- bool usecreatedb /* can user create databases? */
- bool usetrace /* can user set trace flags? */
- bool usesuper /* can user be POSTGRES superuser? */
- bool usecatupd /* can user update catalogs? */
-.fi
-.SH "RULE SYSTEM CATALOGS"
-.nf M
-pg_listener
- NameData relname /* class for which asynchronous
- notification is desired */
- int4 listenerpid /* process id of server corresponding
- to a frontend program waiting for
- asynchronous notification */
- int4 notification /* whether an event notification for
- this process id still pending */
-
-.fi
-.nf M
-pg_prs2rule
- NameData prs2name /* rule name */
- char prs2eventtype /* rule event type:
- R=retrieve
- U=update (replace)
- A=append
- D=delete */
- oid prs2eventrel /* class to which event applies */
- int2 prs2eventattr /* attribute to which event applies */
- float8 necessary /* - deprecated */
- float8 sufficient /* - deprecated */
- text prs2text /* text of original rule definition */
-.fi
-.nf M
-pg_prs2plans
- oid prs2ruleid /* prs2rule instance for which this
- plan is used */
- int2 prs2planno /* plan number (one rule may invoke
- multiple plans) */
- text prs2code /* external representation of the plan */
-.fi
-.nf M
-pg_prs2stub
- oid prs2relid /* class to which this rule applies */
- bool prs2islast /* is this the last stub fragment? */
- int4 prs2no /* stub fragment number */
- stub prs2stub /* stub fragment */
-.fi
-.nf M
-pg_rewrite
- NameData rulename /* rule name */
- char ev_type /* event type:
- RETRIEVE, REPLACE, APPEND, DELETE
- codes are parser-dependent (!?) */
- oid ev_class /* class to which this rule applies */
- int2 ev_attr /* attribute to which this rule applies */
- bool is_instead /* is this an "instead" rule? */
- text ev_qual /* qualification with which to modify
- (rewrite) the plan that triggered this
- rule */
- text action /* parse tree of action */
-.fi
-.SH "LARGE OBJECT CATALOGS"
-.nf M
-pg_lobj
- oid ourid /* 'ourid' from pg_naming that
- identifies this object in the
- Inversion file system namespace */
- int4 objtype /* storage type code:
- 0=Inversion
- 1=Unix
- 2=External
- 3=Jaquith */
- bytea object_descripto/* opaque object-handle structure */
-.fi
-.nf M
-pg_naming
- NameData filename /* filename component */
- oid ourid /* random oid used to identify this
- instance in other instances (can't
- use the actual oid for obscure
- reasons */
- oid parentid /* pg_naming instance of parent
- Inversion file system directory */
-.fi
-.nf M
-pg_platter
- NameData plname /* platter name */
- int4 plstart /* the highest OCCUPIED extent */
-.fi
-.nf M
-pg_plmap
- oid plid /* platter (in pg_platter) on which
- this extent (of blocks) resides */
- oid pldbid /* database of the class to which this
- extent (of blocks) belongs */
- oid plrelid /* class to which this extend (of
- blocks) belongs */
- int4 plblkno /* starting block number within the
- class */
- int4 ploffset /* offset within the platter at which
- this extent begins */
- int4 plextentsz /* length of this extent */
-.fi
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/cleardbdir.1,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
-.TH CLEARDBDIR UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-cleardbdir \(em completely destroys all database files
-.SH SYNOPSIS
-.BR "cleardbdir"
-.SH DESCRIPTION
-.IR cleardbdir
-destroys all the database files. It is used only by the
-Postgres super-user
-before re-initializing the entire installation for a particular site. Normal
-database users should never use this command.
-.PP
-The
-Postgres super-user
-should ensure the
-.IR postmaster
-process is not running before running cleardbdir.
-.SH "SEE ALSO"
-initdb(1)
-
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/close.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
-.TH CLOSE SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-close \(em close a cursor
-.SH SYNOPSIS
-.nf
-\fBclose\fP [cursor_name]
-.fi
-.SH DESCRIPTION
-.BR Close
-frees the resources associated with a cursor,
-.IR cursor_name.
-After this cursor is closed, no subsequent operations are allowed on
-it. A cursor should be closed when it is no longer needed. If
-.IR cursor_name.
-is not specified, then the blank cursor is closed.
-.SH EXAMPLE
-.nf
-/*
- * close the cursor FOO
- */
-close FOO
-.fi
-.SH "SEE ALSO"
-fetch(l),
-select(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/cluster.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
-.TH CLUSTER SQL 01/23/93 Postgres95 Postgres95
-.SH NAME
-cluster \(em give storage clustering advice to Postgres
-.SH SYNOPSIS
-.nf
-\fBcluster\fR indexname \fBon\fR attname
-.fi
-.SH DESCRIPTION
-This command instructs Postgres to cluster the class specified by
-.IR classname
-approximately based on the index specified by
-.IR indexname.
-The index must already have been defined on
-.IR classname.
-.PP
-When a class is clustered, it is physically reordered based on the index
-information. The clustering is static. In other words, if the class is
-updated, it may become unclustered. No attempt is made to keep new
-instances or updated tuples clustered. If desired, the user can
-recluster manually by issuing the command again.
-.SH EXAMPLE
-.nf
-/*
- * cluster employees in based on its salary attribute
- */
-create index emp_ind on emp using btree (salary int4_ops);
-
-cluster emp_ind on emp
-.fi
-
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/commit.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
-.TH COMMIT SQL 01/23/93 Postgres95 Postgres95
-.SH NAME
-commit \(em commit the current transaction
-.SH SYNOPSIS
-.nf
-\fBcommit [transaction|work]\fR
-.fi
-.SH DESCRIPTION
-This commands commits the current transaction. All changes made by
-the transaction become visible to others and are guaranteed to be
-durable if a crash occurs.
-.IR "commit"
-is functionally equivalent to the
-.IR "end"
-command
-.SH "SEE ALSO"
-abort(l),
-begin(l),
-end(l),
-rollback(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/copy.l,v 1.4 1996/10/30 06:19:53 scrappy Exp $
-.TH COPY SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-copy \(em copy data to or from a class from or to a Unix file.
-.SH SYNOPSIS
-.nf
-\fBcopy\fP [\fBbinary\fP] classname [\fBwith oids\fP]
- \fBto\fP|\fBfrom '\fPfilename\fB'\fP|\fBstdin\fR|\fBstdout\fR
- [\fBusing delimiters '\fPdelim\fB'\fP]
-.fi
-.SH DESCRIPTION
-.BR Copy
-moves data between Postgres classes and standard Unix files. The
-keyword
-.BR binary
-changes the behavior of field formatting, as described below.
-.IR Classname
-is the name of an existing class.
-The keyword
-.BR "with oids"
-copies the internal unique object id (OID) for each row.
-.IR Classname
-is the name of an existing class.
-.IR Filename
-is the absolute Unix pathname of the file. In place of a filename, the
-keywords
-.BR "stdin" " and " "stdout"
-can be used so that input to
-.BR copy
-can be written by a Libpq application and output from the
-.BR copy
-command can be read by a Libpq application.
-.PP
-The
-.BR binary
-keyword will force all data to be stored/read as binary objects rather
-than as ASCII text. It is somewhat faster than the normal
-.BR copy
-command, but is not generally portable, and the files generated are
-somewhat larger, although this factor is highly dependent on the data
-itself.
-When copying in, the
-.BR "with oids"
-keyword should only be used on an empty database because
-the loaded oids could conflict with existing oids.
-By default, a ASCII
-.BR copy
-uses a tab (\\t) character as a delimiter. The delimiter may also be changed
-to any other single-character with the use of
-.BR "using delimiters" .
-Characters in data fields which happen to match the delimiter character
-will be quoted.
-.PP
-You must have read access on any class whose values are read by the
-.BR copy
-command, and either write or append access to a class to which values
-are being appended by the
-.BR copy
-command.
-.SH FORMAT OF OUTPUT FILES
-.SS "ASCII COPY FORMAT"
-When
-.BR copy
-is used without the
-.BR binary
-keyword, the file generated will have each instance on a line, with
-each attribute separated by the delimiter character. Embedded delimiter
-characters will be preceeded 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
-.BR copy
-itself.
-.PP
-The actual format for each instance is
-.nf
-<attr1><tab><attr2><tab>...<tab><attrn><newline>
-.fi
-The oid is placed on the beginning of the line if specified.
-.PP
-If
-.BR copy
-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 line by themselves, when it is done. Similarly, if
-.BR copy
-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,
-.BR copy
-will terminate (followed by the backend itself) if a true EOF is
-encountered.
-.PP
-The backslash character has special meaning.
-.BR 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 Postgres95, you will need to
-convert backslash characters (\\) to double-backslashes (\\\\) so
-they are loaded properly.
-.SS "BINARY COPY FORMAT"
-In the case of
-.BR "copy binary" ,
-the first four bytes in the file will be the number of instances in
-the file. If this number is
-.IR zero,
-the
-.BR "copy binary"
-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.
-.PP
-The format for each instance in the file is as follows. Note that
-this format must be followed
-.BR EXACTLY .
-Unsigned four-byte integer quantities are called uint32 in the below
-description.
-.nf
-The first value is:
- uint32 number of tuples
-then for each tuple:
- uint32 total length of data segment
- uint32 oid (if specified)
- uint32 number of null attributes
- [uint32 attribute number of first null attribute
- ...
- uint32 attribute number of nth null attribute],
- <data segment>
-.fi
-.bp
-.SS "ALIGNMENT OF BINARY DATA"
-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.
-.SH "SEE ALSO"
-insert(l), create table(l), vacuum(l), libpq.
-.SH BUGS
-Files used as arguments to the
-.BR copy
-command must reside on or be accessible to the the database server
-machine by being either on local disks or a networked file system.
-.PP
-.BR Copy
-stops operation at the first error. This should not lead to problems
-in the event of a
-.BR "copy from" ,
-but the target relation will, of course, be partially modified in a
-.BR "copy to" .
-The
-.IR vacuum (l)
-query should be used to clean up after a failed
-.BR "copy" .
-.PP
-Because Postgres operates out of a different directory than the user's
-working directory at the time Postgres is invoked, the result of copying
-to a file \*(lqfoo\*(rq (without additional path information) may
-yield unexpected results for the naive user. In this case,
-\*(lqfoo\*(rq will wind up in
-.SM $PGDATA\c
-/foo. In general, the full pathname should be used when specifying
-files to be copied.
-.PP
-.BR Copy
-has virtually no error checking, and a malformed input file will
-likely cause the backend to crash. You should avoid using
-.BR copy
-for input whenever possible.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_aggregate.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
-.TH "CREATE AGGREGATE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create aggregate \(em define a new aggregate
-.SH SYNOPSIS
-.nf
-\fBcreate aggregate\fR agg-name [\fBas\fR]
- \fB(\fP[\fBsfunc1\fR \fB=\fR state-transition-function-1
- ,\fP \fBbasetype\fR \fB=\fR data-type
- ,\fP \fBstype1\fR \fB=\fR sfunc1-return-type]
- [\fB,\fP \fBsfunc2\fR \fB=\fR state-transition-function-2
- ,\fP \fBstype2\fR \fB=\fR sfunc2-return-type]
- [\fB,\fP \fBfinalfunc\fR \fB=\fR final-function]
- [\fB,\fP \fBinitcond1\fR \fB=\fR initial-condition-1]
- [\fB,\fP \fBinitcond2\fR \fB=\fR initial-condition-2]\fB)\fR
-.fi
-.SH DESCRIPTION
-An aggregate function can use up to three functions, two
-.IR "state transition"
-functions, X1 and X2:
-.nf
-X1( internal-state1, next-data_item ) ---> next-internal-state1
-X2( internal-state2 ) ---> next-internal-state2
-.fi
-and a
-.BR "final calculation"
-function, F:
-.nf
-F(internal-state1, internal-state2) ---> aggregate-value
-.fi
-These functions are required to have the following properties:
-.IP
-The arguments to state-transition-function-1 must be
-.BR ( stype1 , basetype ) ,
-and its return value must be stype1.
-.IP
-The argument and return value of state-transition-function-2 must be
-.BR stype2 .
-.IP
-The arguments to the final-calculation-function must be
-.BR ( stype1 , stype2 ) ,
-and its return value must be a POSTGRES base type (not
-necessarily the same as basetype.
-.IP
-The final-calculation-function should be specified if and only if both
-state-transition functions are specified.
-.PP
-Note that it is possible to specify aggregate functions that have
-varying combinations of state and final functions. For example, the
-\*(lqcount\*(rq aggregate requires
-.BR sfunc2
-(an incrementing function) but not
-.BR sfunc1 " or " finalfunc ,
-whereas the \*(lqsum\*(rq aggregate requires
-.BR sfunc1
-(an addition function) but not
-.BR sfunc2 " or " finalfunc
-and the \*(lqaverage\*(rq aggregate requires both of the above state
-functions as well as a
-.BR finalfunc
-(a division function) to produce its answer. In any case, at least
-one state function must be defined, and any
-.BR sfunc2
-must have a corresponding
-.BR initcond2 .
-.PP
-Aggregates also require two initial conditions, one for each
-transition function. These are specified and stored in the database
-as fields of type
-.IR text .
-.SH EXAMPLE
-This
-.IR avg
-aggregate consists of two state transition functions, a addition
-function and a incrementing function. These modify the internal state
-of the aggregate through a running sum and and the number of values
-seen so far. It accepts a new employee salary, increments the count,
-and adds the new salary to produce the next state. The state
-transition functions must be passed correct initialization values.
-The final calculation then divides the sum by the count to produce the
-final answer.
-.nf
---
---Create an aggregate for int4 average
---
-create aggregate avg (sfunc1 = int4add, basetype = int4,
- stype1 = int4, sfunc2 = int4inc, stype2 = int4,
- finalfunc = int4div, initcond1 = "0", initcond2 = "0")
-.fi
-.SH "SEE ALSO"
-create function(l),
-remove aggregate(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_database.l,v 1.1 1996/10/03 15:49:34 momjian Exp $
-.TH "CREATE DATABASE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create database \(em create a new database
-.SH SYNOPSIS
-.nf
-\fBcreate database\fP dbname
-.fi
-.SH DESCRIPTION
-.BR "Create database"
-creates a new Postgres database. The creator becomes the administrator
-of the new database.
-.SH "SEE ALSO"
-createdb(1),
-drop database(l),
-destroydb(1),
-initdb(1).
-.SH BUGS
-This command should
-.BR NOT
-be executed interactively. The
-.IR createdb (1)
-script should be used instead.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_function.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
-.TH "CREATE FUNCTION" SQL 11/05/95 Postgres95 Postgres95
-.SH "NAME"
-create function \(em define a new function
-.SH "SYNOPSIS"
-.nf
-\fBcreate function\fP function_name \fB(\fP
- ([type1 {, type-n}])
- \fBreturns\fP type-r
- \fBas\fP {'/full/path/to/objectfile' | 'sql-queries'}
- \fBlanguage\fP {'c' \ 'sql' \ 'internal'}
-.fi
-.SH "DESCRIPTION"
-With this command, a Postgres user can register a function with Postgres.
-Subsequently, this user is treated as the owner of the function.
-.PP
-When defining a function with arguments, the input data types,
-.IR type-1 ,
-.IR type-2 ,
-\&...,
-.IR type-n ,
-and the return data type,
-.IR type-r
-must be specified, along with the language, which may be
-.IR "\*(lqc\*(rq"
-or
-.IR "\*(lqsql\*(rq" .
-or
-.IR "\*(lqinternal\*(rq" .
-(The
-.IR "arg is"
-clause may be left out if the function has no arguments, or
-alternatively the argument list may be left empty.)
-The input types may be base or complex types, or
-.IR opaque .
-.IR Opaque
-indicates that the function accepts arguments of an
-invalid type such as (char *).
-The output type may be specified as a base type, complex type,
-.IR "setof <type>",
-or
-.IR opaque .
-The
-.IR setof
-modifier indicates that the function will return a set of items,
-rather than a single item.
-The
-.IR as
-clause of the command is treated differently for C and SQL
-functions, as explained below.
-.SH "C FUNCTIONS"
-Functions written in C can be defined to Postgres, which will dynamically
-load them into its address space. The loading happens either using
-.IR load (l)
-or automatically the first time the function is necessary for
-execution. Repeated execution of a function will cause negligible
-additional overhead, as the function will remain in a main memory
-cache.
-.PP
-Internal functions are functions written in C which have been statically
-linked into the postgres backend process. The
-.BR as
-clause must still be specified when defining an internal function but
-the contents are ignored.
-.SH "Writing C Functions"
-The body of a C function following
-.BR as
-should be the
-.BR "FULL PATH"
-of the object code (.o file) for the function, bracketed by quotation
-marks. (Postgres will not compile a function automatically \(em it must
-be compiled before it is used in a
-.BR "define function"
-command.)
-.PP
-C functions with base type arguments can be written in a
-straightforward fashion. The C equivalents of built-in Postgres types
-are accessible in a C file if
-.nf
-\&.../src/backend/utils/builtins.h
-.fi
-is included as a header file. This can be achieved by having
-.nf
-\&#include <utils/builtins.h>
-.fi
-at the top of the C source file and by compiling all C files with the
-following include options:
-.nf
--I.../src/backend
--I.../src/backend/port/<portname>
--I.../src/backend/obj
-.fi
-before any \*(lq.c\*(rq programs in the
-.IR cc
-command line, e.g.:
-.nf
-cc -I.../src/backend \e
- -I.../src/backend/port/<portname> \e
- -I.../src/backend/obj \e
- -c progname.c
-.fi
-where \*(lq...\*(rq is the path to the installed Postgres source tree and
-\*(lq<portname>\*(rq is the name of the port for which the source tree
-has been built.
-.PP
-The convention for passing arguments to and from the user's C
-functions is to use pass-by-value for data types that are 32 bits (4
-bytes) or smaller, and pass-by-reference for data types that require
-more than 32 bits.
-.if t \{
-The following table gives the C type required for parameters in the C
-functions that will be loaded into Postgres. The \*(lqDefined In\*(rq
-column gives the actual header file (in the
-.nf
-\&.../src/backend
-.fi
-directory) that the equivalent C type is defined. However, if you
-include \*(lqutils/builtins.h\*(rq, these files will automatically be
-included.
-.SH "Equivalent C Types for Built-In Postgres Types"
-.PP
-.TS
-center;
-l l l
-l l l.
-\fBBuilt-In Type\fP \fBC Type\fP \fBDefined In\fP
-_
-abstime AbsoluteTime utils/nabstime.h
-bool bool include/c.h
-box (BOX *) utils/geo-decls.h
-bytea (bytea *) include/postgres.h
-char char N/A
-char16 Char16 or (char16 *) include/postgres.h
-cid CID include/postgres.h
-int2 int2 include/postgres.h
-int28 (int28 *) include/postgres.h
-int4 int4 include/postgres.h
-float4 float32 or (float4 *) include/c.h or include/postgres.h
-float8 float64 or (float8 *) include/c.h or include/postgres.h
-lseg (LSEG *) include/geo-decls.h
-name (Name) include/postgres.h
-oid oid include/postgres.h
-oid8 (oid8 *) include/postgres.h
-path (PATH *) utils/geo-decls.h
-point (POINT *) utils/geo-decls.h
-regproc regproc or REGPROC include/postgres.h
-reltime RelativeTime utils/nabstime.h
-text (text *) include/postgres.h
-tid ItemPointer storage/itemptr.h
-tinterval TimeInterval utils/nabstime.h
-uint2 uint16 include/c.h
-uint4 uint32 include/c.h
-xid (XID *) include/postgres.h
-.TE
-\}
-.PP
-Complex arguments to C functions are passed into the C function as a
-special C type, TUPLE, defined in
-.nf
-\&.../src/libpq/libpq-fe.h.
-.fi
-Given a variable
-.IR t
-of this type, the C function may extract attributes from the function
-using the function call:
-.nf
-GetAttributeByName(t, "fieldname", &isnull)
-.fi
-where
-.IR isnull
-is a pointer to a
-.IR bool ,
-which the function sets to
-.IR true
-if the field is null. The result of this function should be cast
-appropriately as shown in the examples below.
-.SH "Compiling Dynamically-Loaded C Functions"
-.PP
-Different operating systems require different procedures for compiling
-C source files so that Postgres can load them dynamically. This section
-discusses the required compiler and loader options on each system.
-.PP
-Under Linux ELF, object files can be generated by specifing the compiler
-flag -fpic.
-.PP
-Under Ultrix, all object files that Postgres is expected to load
-dynamically must be compiled using
-.IR /bin/cc
-with the \*(lq-G 0\*(rq option turned on. The object file name in the
-.IR as
-clause should end in \*(lq.o\*(rq.
-.PP
-Under HP-UX, DEC OSF/1, AIX and SunOS 4, all object files must be
-turned into
-.IR "shared libraries"
-using the operating system's native object file loader,
-.IR ld (1).
-.PP
-Under HP-UX, an object file must be compiled using the native HP-UX C
-compiler,
-.IR /bin/cc ,
-with both the \*(lq+z\*(rq and \*(lq+u\*(rq flags turned on. The
-first flag turns the object file into \*(lqposition-independent
-code\*(rq (PIC); the second flag removes some alignment restrictions
-that the PA-RISC architecture normally enforces. The object file must
-then be turned into a shared library using the HP-UX loader,
-.IR /bin/ld .
-The command lines to compile a C source file, \*(lqfoo.c\*(rq, look
-like:
-.nf
-cc <other flags> +z +u -c foo.c
-ld <other flags> -b -o foo.sl foo.o
-.fi
-The object file name in the
-.BR as
-clause should end in \*(lq.sl\*(rq.
-.PP
-An extra step is required under versions of HP-UX prior to 9.00. If
-the Postgres header file
-.nf
-include/c.h
-.fi
-is not included in the source file, then the following line must also
-be added at the top of every source file:
-.nf
-#pragma HP_ALIGN HPUX_NATURAL_S500
-.fi
-However, this line must not appear in programs compiled under HP-UX
-9.00 or later.
-.PP
-Under DEC OSF/1, an object file must be compiled and then turned
-into a shared library using the OSF/1 loader,
-.IR /bin/ld .
-In this case, the command lines look like:
-.nf
-cc <other flags> -c foo.c
-ld <other flags> -shared -expect_unresolved '*' -o foo.so foo.o
-.fi
-The object file name in the
-.BR as
-clause should end in \*(lq.so\*(rq.
-.PP
-Under SunOS 4, an object file must be compiled and then turned into a
-shared library using the SunOS 4 loader,
-.IR /bin/ld .
-The command lines look like:
-.nf
-cc <other flags> -PIC -c foo.c
-ld <other flags> -dc -dp -Bdynamic -o foo.so foo.o
-.fi
-The object file name in the
-.BR as
-clause should end in \*(lq.so\*(rq.
-.PP
-Under AIX, object files are compiled normally but building the shared
-library requires a couple of steps. First, create the object file:
-.nf
-cc <other flags> -c foo.c
-.fi
-You must then create a symbol \*(lqexports\*(rq file for the object
-file:
-.nf
-mkldexport foo.o `pwd` > foo.exp
-.fi
-Finally, you can create the shared library:
-.nf
-ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
- -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
- -lm -lc 2>/dev/null
-.fi
-You should look at the Postgres User's Manual for an explanation of this
-procedure.
-.SH "SQL FUNCTIONS"
-SQL functions execute an arbitrary list of SQL queries, returning
-the results of the last query in the list. SQL functions in general
-return sets. If their returntype is not specified as a
-.IR setof ,
-then an arbitrary element of the last query's result will be returned.
-.PP
-The body of a SQL function following
-.BR as
-should be a list of queries separated by whitespace characters and
-bracketed within quotation marks. Note that quotation marks used in
-the queries must be escaped, by preceding them with two backslashes
-(i.e. \e\e").
-.PP
-Arguments to the SQL function may be referenced in the queries using
-a $n syntax: $1 refers to the first argument, $2 to the second, and so
-on. If an argument is complex, then a \*(lqdot\*(rq notation may be
-used to access attributes of the argument (e.g. \*(lq$1.emp\*(rq), or
-to invoke functions via a nested-dot syntax.
-.SH "EXAMPLES: C Functions"
-The following command defines a C function, overpaid, of two basetype
-arguments.
-.nf
-create function overpaid (float8, int4) returns bool
- as '/usr/postgres/src/adt/overpaid.o'
- language 'c'
-.fi
-The C file "overpaid.c" might look something like:
-.nf
-#include <utils/builtins.h>
-
-bool overpaid(salary, age)
- float8 *salary;
- int4 age;
-{
- if (*salary > 200000.00)
- return(TRUE);
- if ((age < 30) & (*salary > 100000.00))
- return(TRUE);
- return(FALSE);
-}
-.fi
-The overpaid function can be used in a query, e.g:
-.nf
-select name from EMP where overpaid(salary, age)
-.fi
-One can also write this as a function of a single argument of type
-EMP:
-.nf
-create function overpaid_2 (EMP)
- returns bool
- as '/usr/postgres/src/adt/overpaid_2.o'
- language 'c'
-.fi
-The following query is now accepted:
-.nf
-select name from EMP where overpaid_2(EMP)
-.fi
-In this case, in the body of the overpaid_2 function, the fields in the EMP
-record must be extracted. The C file "overpaid_2.c" might look
-something like:
-.nf
-#include <utils/builtins.h>
-#include <libpq-fe.h>
-
-bool overpaid_2(t)
-TUPLE t;
-{
- float8 *salary;
- int4 age;
- bool salnull, agenull;
-
- salary = (float8 *)GetAttributeByName(t, "salary",
- &salnull);
- age = (int4)GetAttributeByName(t, "age", &agenull);
- if (!salnull && *salary > 200000.00)
- return(TRUE);
- if (!agenull && (age<30) && (*salary > 100000.00))
- return(TRUE);
- return(FALSE)
-}
-.fi
-.SH "EXAMPLES: SQL Functions"
-To illustrate a simple SQL function, consider the following,
-which might be used to debit a bank account:
-.nf
-create function TP1 (int4, float8) returns int4
- as 'update BANK set balance = BANK.balance - $2
- where BANK.acctountno = $1
- select(x = 1)'
- language 'sql'
-.fi
-A user could execute this function to debit account 17 by $100.00 as
-follows:
-.nf
-select (x = TP1( 17,100.0))
-.fi
-The following more interesting examples take a single argument of type
-EMP, and retrieve multiple results:
-.nf
-select function hobbies (EMP) returns set of HOBBIES
- as 'select (HOBBIES.all) from HOBBIES
- where $1.name = HOBBIES.person'
- language 'sql'
-.SH "SEE ALSO"
-.PP
-information(1), load(l), drop function(l).
-.SH "NOTES"
-.SH "Name Space Conflicts"
-More than one function may be defined with the same name, as long as
-the arguments they take are different. In other words, function names
-can be
-.IR overloaded .
-A function may also have the same name as an attribute. In the case
-that there is an ambiguity between a function on a complex type and
-an attribute of the complex type, the attribute will always be used.
-.SH "RESTRICTIONS"
-The name of the C function must be a legal C function name, and the
-name of the function in C code must be exactly the same as the name
-used in
-.BR "create function" .
-There is a subtle implication of this restriction: while the
-dynamic loading routines in most operating systems are more than
-happy to allow you to load any number of shared libraries that
-contain conflicting (identically-named) function names, they may
-in fact botch the load in interesting ways. For example, if you
-define a dynamically-loaded function that happens to have the
-same name as a function built into Postgres, the DEC OSF/1 dynamic
-loader causes Postgres to call the function within itself rather than
-allowing Postgres to call your function. Hence, if you want your
-function to be used on different architectures, we recommend that
-you do not overload C function names.
-.PP
-There is a clever trick to get around the problem just described.
-Since there is no problem overloading SQL functions, you can
-define a set of C functions with different names and then define
-a set of identically-named SQL function wrappers that take the
-appropriate argument types and call the matching C function.
-.PP
-.IR opaque
-cannot be given as an argument to a SQL function.
-.SH "BUGS"
-C functions cannot return a set of values.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_index.l,v 1.2 1996/09/19 20:07:15 scrappy Exp $
-.TH "CREATE INDEX" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create index \(em construct a secondary index
-.SH SYNOPSIS
-.nf
-\fBcreate\fR \fBindex\fR index-name
- \fBon\fR classname [\fBusing\fR am-name]
- \fB(\fR attname [type_class\fB] )\fR
-
-\fBcreate\fR \fBindex\fR index-name
- \fBon\fR classname [\fBusing\fR am-name]
- \fB(\fR funcname \fB(\fR attname\-1 { , attname\-i } \fB)\fR type_class \fB)\fR
-.fi
-.SH DESCRIPTION
-This command constructs an index called
-.IR index-name.
-.PP
-.IR Am-name
-is the name of the access method which is used for the index.
-The default access method is btree.
-.PP
-In the first syntax shown above, the key field for the index is
-specified as an attribute name and an associated
-.IR "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
-.IR int4_ops
-class; this operator class includes comparison functions for four-byte
-integers.
-The default operator class is the appropriate operator class for
-that field type.
-.PP
-In the second syntax shown above, an index can be defined on the
-result of a user-defined function
-.IR funcname
-applied to one or more attributes of a single class. These
-.IR "functional indices"
-are primarily useful in two situations. First, functional indices can
-be used to simulate multikey indices. That is, the user can define a
-new base type (a simple combination of, say, \*(lqoid\*(rq and
-\*(lqint2\*(rq) and the associated functions and operators on this new
-type such that the access method can use it. Once this has been done,
-the standard techniques for interfacing new types to access methods
-(described in the Postgres user manual) can be applied. Second,
-functional indices can be used to obtain fast access to data based on
-operators that would normally require some transformation to be
-applied to the base data. For example, say you have an attribute in
-class \*(lqmyclass\*(rq called \*(lqpt\*(rq that consists of a 2D
-point type. Now, suppose that you would like to index this attribute
-but you only have index operator classes for 2D polygon types. You
-can define an index on the point attribute using a function that you
-write (call it \*(lqpoint_to_polygon\*(rq) and your existing polygon
-operator class; after that, queries using existing polygon operators
-that reference \*(lqpoint_to_polygon(myclass.pt)\*(rq on one side will
-use the precomputed polygons stored in the functional index instead of
-computing a polygon for each and every instance in \*(lqmyclass\*(rq
-and then comparing it to the value on the other side of the operator.
-Obviously, the decision to build a functional index represents a
-tradeoff between space (for the index) and execution time.
-.PP
-Postgres provides btree, rtree and hash access methods for
-secondary indices. The btree access method is an implementation of
-the Lehman-Yao high-concurrency btrees. The rtree access method
-implements standard rtrees using Guttman's quadratic split algorithm.
-The hash access method is an implementation of Litwin's linear
-hashing. We mention the algorithms used solely to indicate that all
-of these access methods are fully dynamic and do not have to be
-optimized periodically (as is the case with, for example, static hash
-access methods).
-.PP
-This list was generated from the Postgres system catalogs with the query:
-
-.nf
-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;
-
-acc_name|ops_name |ops_comp
---------+-----------+--------
-btree |abstime_ops|<
-btree |abstime_ops|<=
-btree |abstime_ops|=
-btree |abstime_ops|>
-btree |abstime_ops|>=
-btree |bpchar_ops |<
-btree |bpchar_ops |<=
-btree |bpchar_ops |=
-btree |bpchar_ops |>
-btree |bpchar_ops |>=
-btree |char16_ops |<
-btree |char16_ops |<=
-btree |char16_ops |=
-btree |char16_ops |>
-btree |char16_ops |>=
-btree |char2_ops |<
-btree |char2_ops |<=
-btree |char2_ops |=
-btree |char2_ops |>
-btree |char2_ops |>=
-btree |char4_ops |<
-btree |char4_ops |<=
-btree |char4_ops |=
-btree |char4_ops |>
-btree |char4_ops |>=
-btree |char8_ops |<
-btree |char8_ops |<=
-btree |char8_ops |=
-btree |char8_ops |>
-btree |char8_ops |>=
-btree |char_ops |<
-btree |char_ops |<=
-btree |char_ops |=
-btree |char_ops |>
-btree |char_ops |>=
-btree |date_ops |<
-btree |date_ops |<=
-btree |date_ops |=
-btree |date_ops |>
-btree |date_ops |>=
-btree |float4_ops |<
-btree |float4_ops |<=
-btree |float4_ops |=
-btree |float4_ops |>
-btree |float4_ops |>=
-btree |float8_ops |<
-btree |float8_ops |<=
-btree |float8_ops |=
-btree |float8_ops |>
-btree |float8_ops |>=
-btree |int24_ops |<
-btree |int24_ops |<=
-btree |int24_ops |=
-btree |int24_ops |>
-btree |int24_ops |>=
-btree |int2_ops |<
-btree |int2_ops |<=
-btree |int2_ops |=
-btree |int2_ops |>
-btree |int2_ops |>=
-btree |int42_ops |<
-btree |int42_ops |<=
-btree |int42_ops |=
-btree |int42_ops |>
-btree |int42_ops |>=
-btree |int4_ops |<
-btree |int4_ops |<=
-btree |int4_ops |=
-btree |int4_ops |>
-btree |int4_ops |>=
-btree |name_ops |<
-btree |name_ops |<=
-btree |name_ops |=
-btree |name_ops |>
-btree |name_ops |>=
-btree |oid_ops |<
-btree |oid_ops |<=
-btree |oid_ops |=
-btree |oid_ops |>
-btree |oid_ops |>=
-btree |oidint2_ops|<
-btree |oidint2_ops|<=
-btree |oidint2_ops|=
-btree |oidint2_ops|>
-btree |oidint2_ops|>=
-btree |oidint4_ops|<
-btree |oidint4_ops|<=
-btree |oidint4_ops|=
-btree |oidint4_ops|>
-btree |oidint4_ops|>=
-btree |oidname_ops|<
-btree |oidname_ops|<=
-btree |oidname_ops|=
-btree |oidname_ops|>
-btree |oidname_ops|>=
-btree |text_ops |<
-btree |text_ops |<=
-btree |text_ops |=
-btree |text_ops |>
-btree |text_ops |>=
-btree |time_ops |<
-btree |time_ops |<=
-btree |time_ops |=
-btree |time_ops |>
-btree |time_ops |>=
-btree |varchar_ops|<
-btree |varchar_ops|<=
-btree |varchar_ops|=
-btree |varchar_ops|>
-btree |varchar_ops|>=
-hash |bpchar_ops |=
-hash |char16_ops |=
-hash |char2_ops |=
-hash |char4_ops |=
-hash |char8_ops |=
-hash |char_ops |=
-hash |date_ops |=
-hash |float4_ops |=
-hash |float8_ops |=
-hash |int2_ops |=
-hash |int4_ops |=
-hash |name_ops |=
-hash |oid_ops |=
-hash |text_ops |=
-hash |time_ops |=
-hash |varchar_ops|=
-rtree |bigbox_ops |&&
-rtree |bigbox_ops |&<
-rtree |bigbox_ops |&>
-rtree |bigbox_ops |<<
-rtree |bigbox_ops |>>
-rtree |bigbox_ops |@
-rtree |bigbox_ops |~
-rtree |bigbox_ops |~=
-rtree |box_ops |&&
-rtree |box_ops |&<
-rtree |box_ops |&>
-rtree |box_ops |<<
-rtree |box_ops |>>
-rtree |box_ops |@
-rtree |box_ops |~
-rtree |box_ops |~=
-rtree |poly_ops |&&
-rtree |poly_ops |&<
-rtree |poly_ops |&>
-rtree |poly_ops |<<
-rtree |poly_ops |>>
-rtree |poly_ops |@
-rtree |poly_ops |~
-rtree |poly_ops |~=
-
-.fi
-The
-.IR int24_ops
-operator class is useful for constructing indices on int2 data, and
-doing comparisons against int4 data in query qualifications.
-Similarly,
-.IR int42_ops
-support indices on int4 data that is to be compared against int2 data
-in queries.
-.PP
-The operator classes
-.IR oidint2_ops ,
-.IR oidint4_ops ,
-and
-.IR oidchar16_ops
-represent the use of
-.IR "functional indices"
-to simulate multi-key indices.
-.PP
-The Postgres query optimizer will consider using btree indices in a scan
-whenever an indexed attribute is involved in a comparison using one of:
-
-.nf
-< <= = >= >
-.fi
-
-Both box classes support indices on the \*(lqbox\*(rq datatype in
-Postgres. The difference between them is that
-.IR bigbox_ops
-scales box coordinates down, to avoid floating point exceptions from
-doing multiplication, addition, and subtraction on very large
-floating-point coordinates. If the field on which your rectangles lie
-is about 20,000 units square or larger, you should use
-.IR bigbox_ops .
-The
-.IR poly_ops
-operator class supports rtree indices on \*(lqpolygon\*(rq data.
-.PP
-The Postgres query optimizer will consider using an rtree index whenever
-an indexed attribute is involved in a comparison using one of:
-
-.nf
-<< &< &> >> @ ~= &&
-.fi
-
-The Postgres query optimizer will consider using a hash index whenever
-an indexed attribute is involved in a comparison using the \fB=\fR operator.
-.SH EXAMPLES
-.nf
---
---Create a btree index on the emp class using the age attribute.
---
-create index empindex on emp using btree (age int4_ops)
-.fi
-.nf
---
---Create a btree index on employee name.
---
-create index empname
- on emp using btree (name char16_ops)
-.fi
-.nf
---
---Create an rtree index on the bounding rectangle of cities.
---
-create index cityrect
- on city using rtree (boundbox box_ops)
-.fi
-.nf
---
---Create a rtree index on a point attribute such that we
---can efficiently use box operators on the result of the
---conversion function. Such a qualification might look
---like "where point2box(points.pointloc) = boxes.box".
---
-create index pointloc
- on points using rtree (point2box(location) box_ops)
-.nf
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_operator.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
-.TH "CREATE OPERATOR" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create operator \(em define a new user operator
-.SH SYNOPSIS
-.nf
-\fBcreate operator\fR operator_name
- \fB(\fR[ \fBleftarg\fR \fB=\fR type-1 ]
- [ \fB,\fR \fBrightarg\fR \fB=\fR type-2 ]
- , \fBprocedure =\fR func_name
- [\fB, commutator =\fR com_op ]
- [\fB, negator =\fR neg_op ]
- [\fB, restrict =\fR res_proc ]
- [\fB, hashes\fR]
- [\fB, join =\fR join_proc ]
- [\fB, sort =\fR sor_op1 {\fB,\fR sor_op2 } ]
- \fB)\fR
-.\" \fB"arg is ("
-.\" type [
-.\" \fB,
-.\" type ]
-.\" \fB)
-.fi
-.SH DESCRIPTION
-This command defines a new user operator,
-.IR "operator_name" .
-The user who defines an operator becomes its owner.
-.PP
-The
-.IR "operator_name"
-is a sequence of up to sixteen punctuation characters. The following
-characters are valid for single-character operator names:
-.nf
-~ ! @ # % ^ & ` ?
-.fi
-If the operator name is more than one character long, it may consist
-of any combination of the above characters or the following additional
-characters:
-.nf
-| $ : + - * / < > =
-.fi
-.PP
-At least one of
-.IR leftarg
-and
-.IR rightarg
-must be defined. For binary operators, both should be defined. For
-right unary operators, only
-.IR arg1
-should be defined, while for left unary operators only
-.IR arg2
-should be defined.
-.PP
-The name of the operator,
-.IR operator_name ,
-can be composed of symbols only. Also, the
-.IR func_name
-procedure must have been previously defined using
-.IR "create function" (l)
-and must have one or two arguments.
-.PP
-.\" that multiple instances of the
-.\" operator must be be evaluated
-.\" For example, consider the area-intersection operator,
-.\" .q A,
-.\" and the following expression:
-.\" .(l
-.\" MYBOXES2.description A \*(lq0,0,1,1\*(rq A MYBOXES.description
-.\" .)l
-.\" .in .5i
-.\" The associativity flag indicates that
-.\" .(l
-.\" (MYBOXES2.description A \*(lq0,0,1,1\*(rq) A MYBOXES.description
-.\" .)l
-.\" .in .5i
-.\" is the same as
-.\" .(l
-.\" MYBOXES2.description A (\*(lq0,0,1,1\*(rq A MYBOXES.description).
-.\" .)l
-The commutator operator is present so that Postgres can reverse the order
-of the operands if it wishes. For example, the operator
-area-less-than, >>>, would have a commutator operator,
-area-greater-than, <<<. Suppose that an operator, area-equal, ===,
-exists, as well as an area not equal, !==. Hence, the query optimizer
-could freely convert:
-.nf
-"0,0,1,1"::box >>> MYBOXES.description
-.fi
-to
-.nf
-MYBOXES.description <<< "0,0,1,1"::box
-.fi
-This allows the execution code to always use the latter representation
-and simplifies the query optimizer somewhat.
-.PP
-The negator operator allows the query optimizer to convert
-.nf
-not MYBOXES.description === "0,0,1,1"::box
-.fi
-to
-.nf
-MYBOXES.description !== "0,0,1,1"::box
-.fi
-If a commutator operator name is supplied, Postgres searches for it in
-the catalog. If it is found and it does not yet have a commutator
-itself, then the commutator's entry is updated to have the current
-(new) operator as its commutator. This applies to the negator, as
-well.
-.PP
-This is to allow the definition of two operators that are the
-commutators or the negators of each other. The first operator should
-be defined without a commutator or negator (as appropriate). When the
-second operator is defined, name the first as the commutator or
-negator. The first will be updated as a side effect.
-.PP
-The next two specifications are present to support the query optimizer
-in performing joins. Postgres can always evaluate a join (i.e.,
-processing a clause with two tuple variables separated by an operator
-that returns a boolean) by iterative substitution [WONG76]. In
-addition, Postgres is planning on implementing a hash-join algorithm
-along the lines of [SHAP86]; however, it must know whether this
-strategy is applicable. For example, a hash-join algorithm is usable
-for a clause of the form:
-.nf
-MYBOXES.description === MYBOXES2.description
-.fi
-but not for a clause of the form:
-.nf
-MYBOXES.description <<< MYBOXES2.description.
-.fi
-The
-.BR hashes
-flag gives the needed information to the query optimizer concerning
-whether a hash join strategy is usable for the operator in question.
-.PP
-Similarly, the two sort operators indicate to the query optimizer
-whether merge-sort is a usable join strategy and what operators should
-be used to sort the two operand classes. For the === clause above,
-the optimizer must sort both relations using the operator, <<<. On
-the other hand, merge-sort is not usable with the clause:
-.nf
-MYBOXES.description <<< MYBOXES2.description
-.fi
-If other join strategies are found to be practical, Postgres will change
-the optimizer and run-time system to use them and will require
-additional specification when an operator is defined. Fortunately,
-the research community invents new join strategies infrequently, and
-the added generality of user-defined join strategies was not felt to
-be worth the complexity involved.
-.PP
-The last two pieces of the specification are present so the query
-optimizer can estimate result sizes. If a clause of the form:
-.nf
-MYBOXES.description <<< "0,0,1,1"::box
-.fi
-is present in the qualification, then Postgres may have to estimate the
-fraction of the instances in MYBOXES that satisfy the clause. The
-function res_proc must be a registered function (meaning it is already
-defined using
-.IR "define function" (l))
-which accepts one argument of the correct data type and returns a
-floating point number. The query optimizer simply calls this
-function, passing the parameter
-.nf
-"0,0,1,1"
-.fi
-and multiplies the result by the relation size to get the desired
-expected number of instances.
-.PP
-Similarly, when the operands of the operator both contain instance
-variables, the query optimizer must estimate the size of the resulting
-join. The function join_proc will return another floating point
-number which will be multiplied by the cardinalities of the two
-classes involved to compute the desired expected result size.
-.PP
-The difference between the function
-.nf
-my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
-.fi
-and the operator
-.nf
-MYBOXES.description === "0,0,1,1"::box
-.fi
-is that Postgres attempts to optimize operators and can decide to use an
-index to restrict the search space when operators are involved.
-However, there is no attempt to optimize functions, and they are
-performed by brute force. Moreover, functions can have any number of
-arguments while operators are restricted to one or two.
-.SH EXAMPLE
-.nf
---
---The following command defines a new operator,
---area-equality, for the BOX data type.
---
-create operator === (
- leftarg = box,
- rightarg = box,
- procedure = area_equal_procedure,
- commutator = ===,
- negator = !==,
- restrict = area_restriction_procedure,
- hashes,
- join = area-join-procedure,
- sort = <<<, <<<)
-.\" arg is (box, box)
-.fi
-.SH "SEE ALSO"
-create function(l),
-drop operator(l).
-.SH BUGS
-Operator names cannot be composed of alphabetic characters in
-Postgres.
-.PP
-If an operator is defined before its commuting operator has been defined
-(a case specifically warned against above), a dummy operator with invalid
-fields will be placed in the system catalogs. This may interfere with
-the definition of later operators.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_rule.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
-.TH "CREATE RULE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create rule \(em define a new rule
-.SH SYNOPSIS
-.nf
-\fBcreate\fR \fBrule\fR rule_name
- \fBas\fR \fBon\fR event
- \fBto\fR object [\fBwhere\fR clause]
- \fBdo\fR [\fBinstead\fR]
- [action | nothing | \fB[\fPactions...\fB]\fP]
-.fi
-.SH DESCRIPTION
-.IR "The current rule system implementation is very brittle and is unstable. Users are discouraged from using rules at this time."
-.PP
-.BR "Create rule"
-is used to define a new rule.
-.PP
-Here,
-.IR event
-is one of
-.IR select ,
-.IR update ,
-.IR delete
-or
-.IR insert .
-.IR Object
-is either:
-.nf
-a class name
- \fIor\fR
-class.column
-.fi
-The
-.BR "from"
-clause, the
-.BR "where"
-clause, and the
-.IR action
-are respectively normal SQL
-.BR "from"
-clauses,
-.BR "where"
-clauses and collections of SQL commands with the following change:
-.IP
-.BR new
-or
-.BR current
-can appear instead of
-an instance variable whenever an instance
-variable is permissible in SQL.
-.PP
-The semantics of a rule is that at the time an individual instance is
-accessed, updated, inserted or deleted, there is a
-.BR current
-instance
-(for retrieves, updates and deletes) and a
-.BR new
-instance (for updates and appends). If the event specified in the
-.BR "on"
-clause and the condition specified in the
-.BR "where"
-clause are true for the current instance, then the
-.IR action
-part of the rule is executed. First, however, values from fields in
-the current instance and/or the new instance are substituted for:
-.nf
-current.attribute-name
-new.attribute-name
-.fi
-The
-.IR action
-part of the rule executes with same command and transaction identifier
-as the user command that caused activation.
-.PP
-A note of caution about SQL rules is in order. If the same class
-name or instance variable appears in the event,
-.BR where
-clause and the
-.IR action
-parts of a rule, they are all considered different tuple variables.
-More accurately,
-.BR new
-and
-.BR current
-are the only tuple variables that are shared between these clauses.
-For example, the following two rules have the same semantics:
-.nf
-on update to EMP.salary where EMP.name = "Joe"
- do update EMP ( ... ) where ...
-
-on update to EMP-1.salary where EMP-2.name = "Joe"
- do update EMP-3 ( ... ) where ...
-.fi
-Each rule can have the optional tag
-.BR "instead" .
-Without this tag
-.IR action
-will be performed in addition to the user command when the event in
-the condition part of the rule occurs. Alternately, the
-.IR action
-part will be done instead of the user command.
-In this later case, the action can be the keyword
-.BR nothing .
-.PP
-When choosing between the rewrite and instance rule systems for a
-particular rule application, remember that in the rewrite system
-.BR current
-refers to a relation and some qualifiers whereas in the instance
-system it refers to an instance (tuple).
-.PP
-It is very important to note that the
-.BR rewrite
-rule system will
-neither detect nor process circular
-rules. For example, though each of the following two rule
-definitions are accepted by Postgres, the
-.IR retrieve
-command will cause
-Postgres to
-.IR crash :
-.nf
---
---Example of a circular rewrite rule combination.
---
-create rule bad_rule_combination_1 is
- on select to EMP
- do instead select to TOYEMP
-
-create rule bad_rule_combination_2 is
- on select to TOYEMP
- do instead select to EMP
-
---
---This attempt to retrieve from EMP will cause Postgres to crash.
---
-select * from EMP
-.fi
-.PP
-You must have
-.IR "rule definition"
-access to a class in order to define a rule on it (see
-.IR "change acl" (l).
-.SH EXAMPLES
-.nf
---
---Make Sam get the same salary adjustment as Joe
---
-create rule example_1 is
- on update EMP.salary where current.name = "Joe"
- do update EMP (salary = new.salary)
- where EMP.name = "Sam"
-.fi
-At the time Joe receives a salary adjustment, the event will become
-true and Joe's current instance and proposed new instance are available
-to the execution routines. Hence, his new salary is substituted into the
-.IR action
-part of the rule which is subsequently executed. This propagates
-Joe's salary on to Sam.
-.nf
---
---Make Bill get Joe's salary when it is accessed
---
-create rule example_2 is
- on select to EMP.salary
- where current.name = "Bill"
- do instead
- select (EMP.salary) from EMP where EMP.name = "Joe"
-.fi
-.nf
---
---Deny Joe access to the salary of employees in the shoe
---department. (pg_username() returns the name of the current user)
---
-create rule example_3 is
- on select to EMP.salary
- where current.dept = "shoe"
- and pg_username() = "Joe"
- do instead nothing
-.fi
-.nf
---
---Create a view of the employees working in the toy department.
---
-create TOYEMP(name = char16, salary = int4)
-
-create rule example_4 is
- on select to TOYEMP
- do instead select (EMP.name, EMP.salary) from EMP
- where EMP.dept = "toy"
-.fi
-.nf
---
---All new employees must make 5,000 or less
---
-create rule example_5 is
- on insert to EMP where new.salary > 5000
- do update newset salary = 5000
-.fi
-.SH "SEE ALSO"
-drop rule(l),
-create view(l).
-.SH BUGS
-.PP
-.BR "instead"
-rules do not work properly.
-.PP
-The object in a SQL rule cannot be an array reference and cannot
-have parameters.
-.PP
-Aside from the \*(lqoid\*(rq field, system attributes cannot be
-referenced anywhere in a rule. Among other things, this means that
-functions of instances (e.g., \*(lqfoo(emp)\*(rq where \*(lqemp\*(rq
-is a class) cannot be called anywhere in a rule.
-.PP
-The rule system store the rule text and query plans as text
-attributes. This implies that creation of rules may fail if the
-rule plus its various internal representations exceed some value
-that is on the order of one page (8KB).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_table.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
-.TH "CREATE TABLE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create table \(em create a new class
-.SH SYNOPSIS
-.nf
-\fBcreate table \fR classname \fB(\fPattname-1 type-1 {\fB,\fP attname-i type-i}\fB)\fP
- [\fBinherits\fR \fB(\fR classname-1 {\fB,\fR classname-i} \fB)\fR]
- [\fBarchive\fR \fB=\fR archive_mode]
- [\fBstore\fR \fB=\fR \*(lqsmgr_name\*(rq]
- [\fBarch_store\fR \fB=\fR \*(lqsmgr_name\*(rq]
-.fi
-.SH DESCRIPTION
-.BR "Create table"
-will enter a new class into the current data base. The class will be
-\*(lqowned\*(rq by the user issuing the command. The name of the
-class is
-.IR classname
-and the attributes are as specified in the list of
-.IR attname s.
-The
-.IR i th
-attribute is created with the type specified by
-.IR type "-i."
-Each type may be a simple type, a complex type (set) or an array type.
-.PP
-Each array attribute stores arrays that must have the same number of
-dimensions but may have different sizes and array index bounds. An
-array of dimension
-.IR n
-is specified by appending
-.IR n
-pairs of square brackets:
-.nf
-att_name = type[][]..[]
-.fi
-.PP
-The optional
-.BR inherits
-clause specifies a collection of class names from which this class
-automatically inherits all fields. If any inherited field name
-appears more than once, Postgres reports an error. Postgres automatically
-allows the created class to inherit functions on classes above it in
-the inheritance hierarchy. Inheritance of functions is done according
-to the conventions of the Common Lisp Object System (CLOS).
-.PP
-Each new class
-.IR classname
-is automatically created as a type. Therefore, one or more instances
-from the class are automatically a type and can be used in
-.IR alter table(l)
-or other
-.BR "create table"
-statements. See
-.IR introduction (l)
-for a further discussion of this point.
-.PP
-The optional
-.BR store
-and
-.BR arch_store
-keywords may be used to specify a storage manager to use for the new
-class. The released version of Postgres supports only \*(lqmagnetic
-disk\*(rq as a storage manager name; the research system at UC Berkeley
-provides additional storage managers.
-.BR Store
-controls the location of current data,
-and
-.BR arch_store
-controls the location of historical data.
-.BR Arch_store
-may only be specified if
-.BR archive
-is also specified. If either
-.BR store
-or
-.BR arch_store
-is not declared, it defaults to \*(lqmagnetic disk\*(rq.
-.PP
-The new class is created as a heap with no initial data. A class can
-have no more than 1600 attributes (realistically, this is limited by the
-fact that tuple sizes must be less than 8192 bytes), but this limit
-may be configured lower at some sites. A class cannot have the same
-name as a system catalog class.
-.PP
-The
-.BR archive
-keyword specifies whether historical data is to be saved or discarded.
-.IR Arch_mode
-may be one of:
-.TP 10n
-.IR none
-No historical access is supported.
-.TP 10n
-.IR light
-Historical access is allowed and optimized for light update activity.
-.TP 10n
-.IR heavy
-Historical access is allowed and optimized for heavy update activity.
-.PP
-.IR Arch_mode
-defaults to \*(lqnone\*(rq. Once the archive status is set, there is
-no way to change it. For details of the optimization, see [STON87].
-.SH EXAMPLES
-.nf
---
--- Create class emp with attributes name, sal and bdate
---
-create table emp (name char16, salary float4, bdate abstime)
-.fi
-.nf
---
---Create class permemp with pension information that
---inherits all fields of emp
---
-create table permemp (plan char16) inherits (emp)
-.fi
-.nf
---
---Create class foo on magnetic disk and archive historical data
---
-create table foo (bar int4) archive = heavy
- store = "magnetic disk"
-.fi
-.nf
---
---Create class tictactoe to store noughts-and-crosses
---boards as a 2-dimensional array
---
-create table tictactoe (game int4, board = char[][])
-.fi
-.nf
---
---Create a class newemp with a set attribute "manager". A
---set (complex) attribute may be of the same type as the
---relation being defined (as here) or of a different complex
---type. The type must exist in the "pg_type" catalog or be
---the one currently being defined.
---
-create table newemp (name text, manager = newemp)
-.fi
-.SH "SEE ALSO"
-drop table(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_type.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
-.TH "CREATE TYPE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create type \(em define a new base data type
-.SH SYNOPSIS
-.nf
-\fBcreate type\fP typename \fB(\fR\fBinternallength\fR = (number | \fBvariable\fR),
- [ \fBexternallength\fR = (number | \fBvariable\fR)\fB,\fR ]
- \fBinput\fR = input_function,
- \fBoutput\fR = output_function
- [\fB,\fR \fBelement\fR = typename]
- [\fB,\fR \fBdelimiter\fR = <character>]
- [\fB,\fR \fBdefault\fR = "string" ]
- [\fB,\fR \fBsend\fR = send_function ]
- [\fB,\fR \fBreceive\fR = receive_function ]
- [\fB,\fR \fBpassedbyvalue\fR]\fB)\fR
-.fi
-.\" \fBcreate type\fP typename as sql_commands
-.SH DESCRIPTION
-.BR "Create type"
-allows the user to register a new user data type with Postgres for use in
-the current data base. The user who defines a type becomes its owner.
-.IR Typename
-is the name of the new type and must be unique within the types
-defined for this database.
-.PP
-.BR "Create type"
-requires the registration of two functions (using
-.IR "create function" (l))
-before defining the type. The representation of a new base type is
-determined by
-.IR input_function ,
-which converts the type's external representation to an internal
-representation usable by the operators and functions defined for the
-type. Naturally,
-.IR "output_function"
-performs the reverse transformation. Both the input and output
-functions must be declared to take one or two arguments of type
-\*(lqopaque\*(rq.
-.PP
-New base data types can be fixed length, in which case
-.BR "internallength"
-is a positive integer, or variable length, in which case Postgres assumes
-that the new type has the same format as the Postgres-supplied data type,
-\*(lqtext\*(rq. To indicate that a type is variable-length, set
-.BR "internallength"
-to
-.IR "variable" .
-The external representation is similarly specified using the
-.IR "externallength"
-keyword.
-.PP
-To indicate that a type is an array and to indicate that a type has
-array elements, indicate the type of the array element using the
-.BR "element"
-keyword. For example, to define an array of 4 byte integers
-(\*(lqint4\*(rq), specify
-.nf
-element = int4
-.fi
-.PP
-To indicate the delimiter to be used on arrays of this type,
-.BR "delimiter"
-can be set to a specific character. The default delimiter is the
-comma (\*(lq,\*(rq) character.
-.PP
-A
-.BR "default"
-value is optionally available in case a user wants some specific bit
-pattern to mean \*(lqdata not present.\*(rq
-.PP
-The optional functions
-.IR "send_function"
-and
-.IR "receive_function"
-are used when the application program requesting Postgres services
-resides on a different machine. In this case, the machine on which
-Postgres runs may use a different format for the data type than used on
-the remote machine. In this case it is appropriate to convert data
-items to a standard form when
-.BR send ing
-from the server to the client and converting from the standard format
-to the machine specific format when the server
-.BR receive s
-the data from the client. If these functions are not specified, then
-it is assumed that the internal format of the type is acceptable on
-all relevant machine architectures. For example, single characters do
-not have to be converted if passed from a Sun-4 to a DECstation, but
-many other types do.
-.PP
-The optional
-.BR "passedbyvalue"
-flag indicates that operators and functions which use this data type
-should be passed an argument by value rather than by reference. Note
-that only types whose internal representation is at most four bytes
-may be passed by value.
-.PP
-For new base types, a user can define operators, functions and
-aggregates using the appropriate facilities described in this section.
-.SH "ARRAY TYPES"
-Two generalized built-in functions,
-.BR array_in
-and
-.BR array_out,
-exist for quick creation of variable-length array types. These
-functions operate on arrays of any existing Postgres type.
-.SH "LARGE OBJECT TYPES"
-A \*(lqregular\*(rq Postgres type can only be 8192 bytes in length. If
-you need a larger type you must create a Large Object type. The
-interface for these types is discussed at length in Section 7, the
-large object interface. The length of all large object types
-is always
-.IR variable,
-meaning the
-.BR internallength
-for large objects is always -1.
-.SH EXAMPLES
-.nf
---
---This command creates the box data type and then uses the
---type in a class definition
---
-create type box (internallength = 8,
- input = my_procedure_1, output = my_procedure_2)
-
-create table MYBOXES (id = int4, description = box)
-.fi
-.nf
---
---This command creates a variable length array type with
---integer elements.
---
-create type int4array
- (input = array_in, output = array_out,
- internallength = variable, element = int4)
-
-create table MYARRAYS (id = int4, numbers = int4array)
-.fi
-.nf
---
---This command creates a large object type and uses it in
---a class definition.
---
-create type bigobj
- (input = lo_filein, output = lo_fileout,
- internallength = variable)
-
-create table BIG_OBJS (id = int4, obj = bigobj)
-.fi
-.SH "RESTRICTIONS"
-Type names cannot begin with the underscore character (\*(lq_\*(rq)
-and can only be 15 characters long. This is because Postgres silently
-creates an array type for each base type with a name consisting of the
-base type's name prepended with an underscore.
-.SH "SEE ALSO"
-create function(l),
-create operator(l),
-drop type(l),
-introduction(large objects).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_version.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
-.TH "CREATE VERSION" SQL 01/23/93 Postgres95 Postgres95
-.SH NAME
-create version \(em construct a version class
-.SH SYNOPSIS
-.nf
-\fBcreate version\fP classname1 \fBfrom\fP classname2 [\fB[\fPabstime\fB]\fP]
-.fi
-.SH DESCRIPTION
-.IR "Currently, the versioning facility is not working."
-.PP
-This command creates a version class
-.IR classname1
-which is related
-to its parent class,
-.IR classname2 .
-Initially,
-.IR classname1
-has the same contents as
-.IR classname2.
-As updates to
-.IR classname1
-occur, however,
-the content of
-.IR classname1
-diverges from
-.IR classname2.
-On the other hand, any updates to
-.IR classname2
-show transparently through to
-.IR classname1 ,
-unless the instance in question has already been updated in
-.IR classname1 .
-.PP
-If the optional
-.IR abstime
-clause is specified, then the version is constructed relative to a
-.BR snapshot
-of
-.IR classname2
-as of the time specified.
-.PP
-Postgres uses the query rewrite rule system to ensure that
-.IR classname1
-is differentially encoded relative to
-.IR classname2.
-Moreover,
-.IR classname1
-is automatically constructed to have the same indexes as
-.IR classname2 .
-It is legal to cascade versions arbitrarily, so a tree of versions can
-ultimately result. The algorithms that control versions are explained
-in [ONG90].
-.SH EXAMPLE
-.nf
---
---create a version foobar from a snapshot of
---barfoo as of January 17, 1990
---
-create version foobar from barfoo [ "Jan 17 1990" ]
-.fi
-.SH "SEE ALSO"
-create view(l), merge(l).
-.SH "BUGS"
-Snapshots (i.e., the optional
-.IR abstime
-clause) are not implemented in Postgres.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_view.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
-.TH "CREATE VIEW" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-create view \(em construct a virtual class
-.SH SYNOPSIS
-.nf
-\fBcreate view\fR view_name \fBas\fR
- \fBselect\fR expression1 [\fBas\fR attr_name1]
- {, expression_i [\fBas\fR attr_namei]}
- [\fBfrom\fR from.last]
- [\fBwhere\fR qual]
-.fi
-.SH DESCRIPTION
-.BR "create view"
-will define a view of a class. This view is not physically
-materialized; instead the rule system is used to support view
-processing as in [STON90]. Specifically, a query rewrite retrieve
-rule is automatically generated to support retrieve operations on
-views. Then, the user can add as many update rules as desired to
-specify the processing of update operations to views. See [STON90]
-for a detailed discussion of this point.
-.SH EXAMPLE
-.nf
---
---create a view consisting of toy department employees
---
-create view toyemp as
- select e.name
- from emp e
- where e.dept = 'toy'
-.fi
-.nf
---
---Specify deletion semantics for toyemp
---
-create rule example1 as
- on delete to toyemp
- do instead delete emp
- where emp.oid = current.oid
-.fi
-.SH "SEE ALSO"
-create table(l),
-create rule(l),
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/createdb.1,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
-.TH CREATEDB UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-createdb \(em create a database
-.SH SYNOPSIS
-.BR createdb
-[\c
-.BR -a
-system]
-[\c
-.BR -h
-host]
-[\c
-.BR -p
-port]
-[dbname]
-.SH DESCRIPTION
-.IR Createdb
-creates a new database. The person who executes this command becomes
-the database administrator, or DBA, for this database and is the only
-person, other than the Postgres super-user, who can destroy it.
-.PP
-.IR Createdb
-is a shell script that invokes
-.IR psql .
-Hence, a
-.IR postmaster
-process must be running on the database server host before
-.IR createdb
-is executed. In addition, the
-.SM PGOPTION
-and
-.SM PGREALM
-environment variables will be passed on to
-.IR psql
-and processed as described in
-.IR psql (1).
-.PP
-The optional argument
-.IR dbname
-specifies the name of the database to be created. The name must be
-unique among all Postgres databases.
-.IR Dbname
-defaults to the value of the
-.SM USER
-environment variable.
-.PP
-.IR Createdb
-understands the following command-line options:
-.TP 5n
-.BR "-a" " system"
-Specifies an authentication system
-.IR "system"
-(see
-.IR introduction (1))
-to use in connecting to the
-.IR postmaster
-process. The default is site-specific.
-.TP
-.BR "-h" " host"
-Specifies the hostname of the machine on which the
-.IR postmaster
-is running. Defaults to the name of the local host, or the value of
-the
-.SM PGHOST
-environment variable (if set).
-.TP
-.BR "-p" " port"
-Specifies the Internet TCP port on which the
-.IR postmaster
-is listening for connections. Defaults to 5432, or the value of the
-.SM PGPORT
-environment variable (if set).
-.SH EXAMPLES
-.nf
-# create 5432 demo database
-createdb demo
-.fi
-.nf
-# create the demo database using the postmaster on host eden,
-# port using the Kerberos authentication system.
-createdb -a kerberos -p 5432 -h eden demo
-.fi
-.SH FILES
-.TP 5n
-\&$PGDATA/base/\fIdbname\fP
-The location of the files corresponding to the database
-.IR dbname .
-.SH "SEE ALSO"
-createdb(l),
-destroydb(1),
-initdb(1),
-psql(1),
-postmaster(1).
-.SH DIAGNOSTICS
-.TP 5n
-.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
-.IR Createdb
-could not attach to the
-.IR postmaster
-process on the specified host and port. If you see this message,
-ensure that the
-.IR postmaster
-is running on the proper host and that you have specified the proper
-port. If your site uses an authentication system, ensure that you
-have obtained the required authentication credentials.
-.TP
-.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
-You do not have a valid entry in the relation \*(lqpg_user\*(rq and
-cannot do anything with Postgres at all; contact your Postgres site
-administrator.
-.TP
-.BI "user \*(lq" "username" "\*(rq is not allowed to create/destroy databases"
-You do not have permission to create new databases; contact your Postgres
-site administrator.
-.TP
-.IB "dbname" " already exists"
-The database already exists.
-.TP
-.BI "database creation failed on" " dbname"
-An internal error occurred in
-.IR psql
-or the backend server. Ensure that your Postgres site administrator has
-properly installed Postgres and initialized the site with
-.IR initdb .
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/createuser.1,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
-.TH CREATEUSER UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-createuser \(em create a Postgres user
-.SH SYNOPSIS
-.BR createuser
-[\c
-.BR -a
-system]
-[\c
-.BR -h
-host]
-[\c
-.BR -p
-port]
-[username]
-.SH DESCRIPTION
-.IR Createuser
-creates a new Postgres user. Only users with \*(lqusesuper\*(rq set in
-the \*(lqpg_user\*(rq class can create new Postgres users. As shipped,
-the user \*(lqpostgres\*(rq can create users.
-.PP
-.IR Createuser
-is a shell script that invokes
-.IR psql .
-Hence, a
-.IR postmaster
-process must be running on the database server host before
-.IR createuser
-is executed. In addition, the
-.SM PGOPTION
-and
-.SM PGREALM
-environment
-variables will be passed on to
-.IR psql
-and processed as described in
-.IR psql (1).
-.PP
-The optional argument
-.IR username
-specifies the name of the Postgres user to be created. (The invoker will
-be prompted for a name if none is specified on the command line.)
-This name must be unique among all Postgres users.
-.PP
-.IR Createuser
-understands the following command-line options:
-.TP 5n
-.BR "-a" " system"
-Specifies an authentication system
-.IR "system"
-(see
-.IR introduction (1))
-to use in connecting to the
-.IR postmaster
-process. The default is site-specific.
-.TP
-.BR "-h" " host"
-Specifies the hostname of the machine on which the
-.IR postmaster
-is running. Defaults to the name of the local host, or the value of
-the
-.SM PGHOST
-environment variable (if set).
-.TP
-.BR "-p" " port"
-Specifies the Internet TCP port on which the
-.IR postmaster
-is listening for connections. Defaults to 5432, or the value of the
-.SM PGPORT
-environment variable (if set).
-.SH "INTERACTIVE QUESTIONS"
-Once invoked with the above options,
-.IR createuser
-will ask a series of questions. The new users's login name (if not
-given on the command line) and user-id must be specified. (Note that
-the Postgres user-id must be the same as the user's Unix user-id.) In
-addition, you must describe the security capabilities of the new user.
-Specifically, you will be asked whether the new user should be able to
-act as Postgres super-user, create new databases and update the system
-catalogs manually.
-.SH "SEE ALSO"
-destroyuser(1),
-psql(1),
-postmaster(1).
-.SH DIAGNOSTICS
-.TP 5n
-.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
-.IR Createuser
-could not attach to the
-.IR postmaster
-process on the specified host and port. If you see this message,
-ensure that the
-.IR postmaster
-is running on the proper host and that you have specified the proper
-port. If your site uses an authentication system, ensure that you
-have obtained the required authentication credentials.
-.TP
-.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
-You do not have a valid entry in the relation \*(lqpg_user\*(rq and
-cannot do anything with Postgres at all; contact your Postgres site
-administrator.
-.TP
-.IB "username" " cannot create users."
-You do not have permission to create new users; contact your Postgres
-site administrator.
-.TP
-.BI "user \*(lq" "username" "\*(rq already exists"
-The user to be added already has an entry in the \*(lqpg_user\*(rq
-class.
-.TP
-.BR "database access failed"
-An internal error occurred in
-.IR psql
-or the backend server. Ensure that your Postgres site administrator has
-properly installed Postgres and initialized the site with
-.IR initdb .
-.SH BUGS
-Postgres user-ids and user names should not have anything to do with the
-constraints of Unix.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/delete.l,v 1.2 1996/09/23 08:39:53 scrappy Exp $
-.TH DELETE SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-delete \(em delete instances from a class
-.SH SYNOPSIS
-.nf
-\fBdelete\fR \fBfrom\fR class_name [ \fBwhere\fR qual ]
-.fi
-.SH DESCRIPTION
-.BR Delete
-removes instances which satisfy the qualification,
-.IR qual
-from the specified class.
-If the qualification is absent, the effect is to delete all instances
-in the class. The result is a valid, but empty class.
-.PP
-You must have write access to the class in order to modify it, as well
-as read access to any class whose values are read in the qualification
-(see
-.IR "change acl" (l).
-.SH EXAMPLE
-.nf
---
---Remove all employees who make over $30,000
---
-delete from emp where emp.sal > 30000
-.fi
-.nf
---
---Clear the hobbies class
---
-delete from hobbies
-.fi
-.SH "SEE ALSO"
-drop(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroydb.1,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH DESTROYDB UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-destroydb \(em destroy an existing database
-.SH SYNOPSIS
-.BR destroydb
-[\c
-.BR -a
-system]
-[\c
-.BR -h
-host]
-[\c
-.BR -p
-port]
-[dbname]
-.SH DESCRIPTION
-.IR Destroydb
-destroys an existing database. To execute this command, the user must
-be the database administrator, or DBA, for this database.
-The program runs silently; no confirmation message will be displayed.
-After the database is destroyed, a Unix shell prompt will reappear.
-.PP
-.IR Destroydb
-is a shell script that invokes
-.IR psql .
-Hence, a
-.IR postmaster
-process must be running on the database server host before
-.IR destroydb
-is executed. In addition, the
-.SM PGOPTION
-and
-.SM PGREALM
-environment
-variables will be passed on to
-.IR psql
-and processed as described in
-.IR psql (1).
-.PP
-The optional argument
-.IR dbname
-specifies the name of the database to be destroyed. All references to
-the database are removed, including the directory containing this
-database and its associated files.
-.IR Dbname
-defaults to the value of the
-.SM USER
-environment variable.
-.PP
-.IR Destroydb
-understands the following command-line options:
-.TP 5n
-.BR "-a" " system"
-Specifies an authentication system
-.IR "system"
-(see
-.IR introduction (1))
-to use in connecting to the
-.IR postmaster
-process. The default is site-specific.
-.TP
-.BR "-h" " host"
-Specifies the hostname of the machine on which the
-.IR postmaster
-is running. Defaults to the name of the local host, or the value of
-the
-.SM PGHOST
-environment variable (if set).
-.TP
-.BR "-p" " port"
-Specifies the Internet TCP port on which the
-.IR postmaster
-is listening for connections. Defaults to 5432, or the value of the
-.SM PGPORT
-environment variable (if set).
-.SH EXAMPLES
-.nf
-# destroy the demo database
-destroydb demo
-.fi
-.nf
-# destroy 5432 demo database using the postmaster on host eden,
-# port using the Kerberos authentication system.
-destroydb -a kerberos -p 5432 -h eden demo
-.fi
-.SH FILES
-.TP 5n
-\&$PGDATA/base/\fIdbname\fP
-The location of the files corresponding to the database
-.IR dbname .
-.SH "SEE ALSO"
-destroydb(l),
-createdb(1),
-initdb(1),
-psql(1).
-postmaster(1).
-.SH DIAGNOSTICS
-.TP 5n
-.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
-.IR Destroydb
-could not attach to the
-.IR postmaster
-process on the specified host and port. If you see this message,
-ensure that the
-.IR postmaster
-is running on the proper host and that you have specified the proper
-port. If your site uses an authentication system, ensure that you
-have obtained the required authentication credentials.
-.TP
-.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
-You do not have a valid entry in the relation \*(lqpg_user\*(rq and
-cannot do anything with Postgres at all; contact your Postgres site
-administrator.
-.TP
-.BI "user \*(lq" "username" "\*(rq is not allowed to create/destroy databases"
-You do not have permission to destroy databases; contact your Postgres
-site administrator.
-.TP
-.BR "database \*(lqdbname\*(rq does not exist"
-The database to be removed does not have an entry in the
-\*(lqpg_database\*(rq class.
-.TP
-.BI "database \*(lq" "dbname" "\*(rq is not owned by you"
-You are not DBA for the specified database.
-.TP
-.BI "database destroy failed on" " dbname"
-An internal error occurred in
-.IR psql
-or the backend server. Contact your Postgres site administrator to
-ensure that ensure that the files and database entries associated with
-the database are completely removed.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroydb.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH DESTROYDB SQL 01/23/93 Postgres95 Postgres95
-.SH NAME
-drop database \(em destroy an existing database
-.SH SYNOPSIS
-.nf
-\fBdrop database\fR dbname
-.fi
-.SH DESCRIPTION
-.BR "Drop database"
-removes the catalog entries for an existing database and deletes the
-directory containing the data. It can only be executed by the
-database administrator (see
-.IR createdb (l)
-for details).
-.SH "SEE ALSO"
-create database(l),
-destroydb(1).
-.SH BUGS
-This query should
-.BR NOT
-be executed interactively. The
-.IR destroydb (1)
-script should be used instead.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroyuser.1,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH DESTROYUSER UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-destroyuser \(em destroy a Postgres user and associated databases
-.SH SYNOPSIS
-.BR destroyuser
-[\c
-.BR -a
-system]
-[\c
-.BR -h
-host]
-[\c
-.BR -p
-port]
-[username]
-.SH DESCRIPTION
-.PP
-.IR Destroyuser
-destroys an existing Postgres user and the databases for which that user
-is database administrator. Only users with \*(lqusesuper\*(rq set in
-the \*(lqpg_user\*(rq class can destroy new Postgres users. As shipped,
-the user \*(lqpostgres\*(rq can destroy users.
-.PP
-.IR Destroyuser
-is a shell script that invokes
-.IR psql .
-Hence, a
-.IR postmaster
-process must be running on the database server host before
-.IR destroyuser
-is executed. In addition, the
-.SM PGOPTION
-and
-.SM PGREALM
-environment variables will be passed on to
-.IR psql
-and processed as described in
-.IR psql (1).
-.PP
-The optional argument
-.IR username
-specifies the name of the Postgres user to be destroyed. (The invoker will
-be prompted for a name if none is specified on the command line.)
-.PP
-.IR Destroyuser
-understands the following command-line options:
-.TP 5n
-.BR "-a" " system"
-Specifies an authentication system
-.IR "system"
-(see
-.IR introduction (1))
-to use in connecting to the
-.IR postmaster
-process. The default is site-specific.
-.TP
-.BR "-h" " host"
-Specifies the hostname of the machine on which the
-.IR postmaster
-is running. Defaults to the name of the local host, or the value of
-the
-.SM PGHOST
-environment variable (if set).
-.TP
-.BR "-p" " port"
-Specifies the Internet TCP port on which the
-.IR postmaster
-is listening for connections. Defaults to 5432, or the value of the
-.SM PGPORT
-environment variable (if set).
-.SH "INTERACTIVE QUESTIONS"
-.PP
-Once invoked with the above options,
-.IR destroyuser
-will warn you about the databases that will be destroyed in the
-process and permit you to abort the removal of the user if desired.
-.SH "SEE ALSO"
-createuser(1),
-psql(1),
-postmaster(1).
-.SH DIAGNOSTICS
-.TP 5n
-.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
-.IR Destroyuser
-could not attach to the
-.IR postmaster
-process on the specified host and port. If you see this message,
-ensure that the
-.IR postmaster
-is running on the proper host and that you have specified the proper
-port. If your site uses an authentication system, ensure that you
-have obtained the required authentication credentials.
-.TP
-.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
-You do not have a valid entry in the relation \*(lqpg_user\*(rq and
-cannot do anything with Postgres at all; contact your Postgres site
-administrator.
-.TP
-.IB "username" " cannot delete users."
-You do not have permission to delete users; contact your Postgres site
-administrator.
-.TP
-.BI "user \*(lq" "username" "\*(rq does not exist"
-The user to be removed does not have an entry in the \*(lqpg_user\*(rq
-class.
-.TP
-.BR "database access failed"
-.TP
-.BI "destroydb on" " dbname" " failed - exiting"
-.TP
-.BI "delete of user" " username" " was UNSUCCESSFUL"
-An internal error occurred in
-.IR psql
-or the backend server. Contact your Postgres site administrator to
-ensure that the files and database entries associated with the user
-and his/her associated databases are completely removed.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH "DROP TABLE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-drop table \(em destroy existing classes
-.SH SYNOPSIS
-.nf
-\fBdrop table\fR classname-1 { \fB,\fR classname-i }
-.fi
-.SH DESCRIPTION
-.BR "Drop Table"
-removes classes from the data base. Only its owner may destroy a
-class. A class may be emptied of instances, but not destroyed, by
-using
-.IR delete (l).
-.PP
-If a class being destroyed has secondary indices on it, then they will
-be removed first. The removal of just a secondary index will not
-affect the indexed class.
-.PP
-The destruction of classes is not reversable. Thus, a destroyed class
-will not be recovered if a transaction which destroys this class fails
-to commit. In addition, historical access to instances in a destroyed
-class is not possible.
-.SH EXAMPLE
-.nf
---
---Destroy the emp class
---
-drop table emp
-.fi
-.nf
---
---Destroy the emp and parts classes
---
-drop table emp, parts
-.fi
-.SH "SEE ALSO"
-delete(l),
-drop index(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_aggregate.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH "DROP AGGREGATE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-drop aggregate \(em remove the definition of an aggregate
-.SH SYNOPSIS
-.nf
-\fBdrop aggregate\fR aggname
-.fi
-.SH DESCRIPTION
-.BR "drop aggregate"
-will remove all reference to an existing aggregate definition. To
-execute this command the current user must be the the owner of the
-aggregate.
-.SH EXAMPLE
-.nf
---
---Remove the average aggregate
---
-drop aggregate avg
-.fi
-.SH "SEE ALSO"
-create aggregate(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_function.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH "DROP FUNCTION" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-drop function \(em remove a user-defined C function
-.SH SYNOPSIS
-.nf
-\fBdrop function \fRfunction_name ( \fP[ type-1 { \fB,\fP type-n } ] \fB)
-.fi
-.SH DESCRIPTION
-.BR "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.
-.SH EXAMPLE
-.nf
---
---this command removes the square root function
---
-drop function sqrt(int4)
-.fi
-.SH "SEE ALSO"
-create function(l).
-.SH BUGS
-No checks are made to ensure that types, operators or access methods
-that rely on the function have been removed first.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_index.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH "DROP INDEX" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-drop index \(em removes an index from Postgres
-.SH SYNOPSIS
-.nf
-\fBdrop index\fR index_name
-.fi
-.SH DESCRIPTION
-This command drops an existing index from the Postgres system. To
-execute this command you must be the owner of the index.
-.SH EXAMPLE
-.nf
---
---this command will remove the "emp_index" index
---
-drop index emp_index
-.fi
-.SH "SEE ALSO"
-create index(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_operator.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
-.TH "DROP OPERATOR" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-drop operator \(em remove an operator from the system
-.SH SYNOPSIS
-.nf
-\fBdrop operator\fR opr_desc
-.fi
-.SH DESCRIPTION
-This command drops an existing operator from the database. To execute
-this command you must be the owner of the operator.
-.PP
-.IR Opr_desc
-is the name of the operator to be removed followed by a parenthesized
-list of the operand types for the operator. The left or right type
-of a left or right unary operator, respectively, may be specified
-as
-.IR none .
-.PP
-It is the user's responsibility to remove any access methods, operator
-classes, etc. that rely on the deleted operator.
-.SH EXAMPLE
-.nf
---
---Remove power operator a^n for int4
---
-drop operator ^ (int4, int4)
-.fi
-.nf
---
---Remove left unary operator !a for booleans
---
-drop operator ! (none, bool)
-.fi
-.nf
---
---Remove right unary factorial operator a! for int4
---
-drop operator ! (int4, none)
-.fi
-.SH "SEE ALSO"
-create operator(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_rule.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
-.TH "DROP RULE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-drop rule \- removes a current rule from Postgres
-.SH SYNOPSIS
-.nf
-\fBdrop rule\fR rule_name
-.fi
-.SH DESCRIPTION
-This command drops the rule named rule_name from the specified Postgres
-rule system. Postgres will immediately cease enforcing it and will purge
-its definition from the system catalogs.
-.SH EXAMPLE
-.nf
---
---This example drops the rewrite rule example_1
---
-drop rule example_1
-.fi
-.SH "SEE ALSO"
-create rule(l),
-drop view(l).
-.SH BUGS
-Once a rule is dropped, access to historical information the rule has
-written may disappear.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_type.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
-.TH "DROP TYPE" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-drop type \(em remove a user-defined type from the system catalogs
-.SH SYNOPSIS
-.nf
-\fBdrop type\fR typename
-.fi
-.SH DESCRIPTION
-This command removes a user type from the system catalogs. Only the
-owner of a type can remove it.
-.PP
-It is the user's responsibility to remove any operators, functions,
-aggregates, access methods, subtypes, classes, etc. that use a
-deleted type.
-.SH EXAMPLE
-.nf
---
---remove the box type
---
-drop type box
-.fi
-.SH "SEE ALSO"
-introduction(l),
-create type(l),
-drop operator(l).
-.SH "BUGS"
-If a built-in type is removed, the behavior of the backend is unpredictable.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/end.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
-.TH END SQL 01/23/93 Postgres95 Postgres95
-.SH NAME
-end \(em commit the current transaction
-.SH SYNOPSIS
-.nf
-\fBend [transaction]\fR
-.fi
-.SH DESCRIPTION
-This commands commits the current transaction. All changes made by
-the transaction become visible to others and are guaranteed to be
-durable if a crash occurs.
-.SH "SEE ALSO"
-abort(l),
-begin(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/fetch.l,v 1.2 1996/10/03 15:49:53 momjian Exp $
-.TH FETCH SQL 01/23/93 Postgres95 Postgres95
-.SH NAME
-fetch \(em fetch instance(s) from a cursor
-.SH SYNOPSIS
-.nf
-\fBfetch\fR [ (\fBforward\fR | \fBbackward\fR) ] [ ( number | \fBall\fR) ] [\fBin\fR cursor_name]
-.fi
-.SH DESCRIPTION
-.BR Fetch
-allows a user to retrieve instances from a cursor named
-.IR cursor_name.
-The number of instances retrieved is specified by
-.IR number .
-If the number of instances remaining in the cursor is less than
-.IR number ,
-then only those available are fetched. Substituting the keyword
-.IR all
-in place of a number will cause all remaining instances in the cursor
-to be retrieved. Instances may be fetched in both
-.IR forward
-and
-.IR backward
-directions. The default direction is
-.IR forward .
-.PP
-Updating data in a cursor is not supported by Postgres, because mapping
-cursor updates back to base classes is impossible in general as with
-view updates. Consequently, users must issue explicit replace
-commands to update data.
-.PP
-Cursors may only be used inside of transaction blocks marked by
-.IR begin (l)
-and
-.IR end (l)
-because the data that they store spans multiple user queries.
-.SH EXAMPLE
-.nf
---
---set up and use a cursor
---
-begin
- declare mycursor cursor for
- select * from pg-user
-end
-.fi
-.nf
---
---Fetch all the instances available in the cursor FOO
---
-fetch all in FOO
-.fi
-.nf
---
---Fetch 5 instances backward in the cursor FOO
---
-fetch backward 5 in FOO
-.fi
-.SH "SEE ALSO"
-begin(l),
-end(l),
-close(l),
-move(l),
-select(l).
-.SH BUGS
-Currently, the smallest transaction in Postgres is a single SQL
-command. It should be possible for a single fetch to be a
-transaction.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/grant.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
-.TH GRANT SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-grant \(em grant access control to a user or group
-.SH SYNOPSIS
-.nf
-\fBgrant\fR <privilege[,privilege,...]>
- \fBon\fR <rel1>[,...<reln>]
- \fBto\fR [\fBpublic\fR | group <group> | <username>]
-
- \fBprivilege\fR is {\fBALL\fR | \fBSELECT\fR | \fBINSERT\fR | \fBUPDATE\fR | \fBDELETE\fR | \fBRULE\fR}
-.fi
-.SH DESCRIPTION
-.PP
-.B Grant
-allows you to give specified permissions to all users or
-a certain user or group.
-By default, a table grants read-only (\fBSELECT\fR) to all Postgres users.
-You must specifically revoke this privilege if this is not desired.
-.SH EXAMPLES
-.nf
---
---Example of a grant
---
-grant insert
- on mytab
- to public
-.fi
-.SH "SEE ALSO"
-revoke(l)
-
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/initdb.1,v 1.2 1996/10/03 00:25:53 momjian Exp $
-.TH INITDB UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-initdb \(em initalize the database templates and primary directories
-.SH SYNOPSIS
-.BR "initdb"
-[\c
-.BR "-d"
-]
-[\c
-.BR "-n"
-]
-[\c
-.BR "-r directory"
-]
-[\c
-.BR "-t"
-]
-[\c
-.BR "-u username"
-]
-[\c
-.BR "-v"
-]
-.SH DESCRIPTION
-.IR Initdb
-sets up the initial template databases and is normally executed as
-part of the installation process. The template database is created
-under the directory specified by the the environment variable
-.SM PGDATA,
-or to a default specified at compile-time. The template database
-is then
-.BR vacuum ed.
-.PP
-.IR Initdb
-is a shell script that invokes the backend server directly. Hence, it
-must be executed by the Postgres super-user.
-.PP
-.IR Initdb
-understands the following command-line options:
-.TP
-.BR "-d"
-Print debugging output from the backend server. This option generates
-a tremendous amount of information. This option also turns off the
-final vacuuming step.
-.TP
-.BR "-n"
-Run in \*(lqnoclean\*(rq mode. By default,
-.IR initdb
-cleans up (recursively unlinks) the data directory if any error
-occurs, which also removes any core files left by the backend server.
-This option inhibits any tidying-up.
-.TP
-.BR "-r directory"
-Use the specified data directory.
-.TP
-.BR "-t"
-Update template database only.
-.TP
-.BR "-u username"
-Run as the specified username.
-.TP
-.BR "-v"
-Produce verbose output, printing messages stating where the
-directories are being created, etc.
-.SH FILES
-.TP
-\&$PGDATA/base
-The location of global (shared) classes.
-.TP
-\&$PGDATA/base/template1
-The location of the template database.
-.TP
-\&$PGDATA/files/{global1,local1_template1}.bki
-Command files used to generate the global and template databases,
-generated and installed by the initial compilation process.
-.SH "SEE ALSO"
-createdb(1),
-vacuum(l),
-bki(files),
-template(files).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/insert.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
-.TH INSERT SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-insert \(em insert tuples to a relation
-.SH SYNOPSIS
-.nf
-\fBinsert\fR into classname
- [(att.expr-1,{att_expr.i})]
- {\fBvalues\fR (expression1 {,expression-i}) |
- \fBselect\fR expression1,{expression-i}
- [\fBfrom\fR from-list] [\fBwhere\fR qual]
-.fi
-.SH DESCRIPTION
-.BR Insert
-adds instances that satisfy the qualification,
-.IR qual ,
-to
-.IR classname .
-.IR Classname
-must be the name of an existing class. The target list specifies the
-values of the fields to be appended to
-.IR classname .
-That is, each
-.IR att_expr
-specifies a field (either an attribute name or an attribute name plus
-an array specification) to which the corresponding
-.IR expression
-should be assigned. The fields in the target list may be listed in
-any order. Fields of the result class which do not appear in the
-target list default to NULL. If the expression for each field is not
-of the correct data type, automatic type coercion will be attempted.
-.PP
-An array initialization may take exactly one of the following forms:
-.nf
---
--- Specify a lower and upper index for each dimension
---
-att_name[lIndex-1:uIndex-1]..[lIndex-i:uIndex-i] = array_str
-
---
---Specify only the upper index for each dimension
---(each lower index defaults to 1)
---
-att_name[uIndex-1]..[uIndex-i] = array_str
-
---
---Use the upper index bounds as specified within array_str
---(each lower index defaults to 1)
---
-att_name = array_str
-.fi
-where each
-.IR lIndex
-or
-.IR uIndex
-is an integer constant and
-.IR array_str
-is an array constant (see
-.IR introduction (l)).
-.PP
-
-If the user does not specify any array bounds (as in the third form)
-then Postgres will attempt to deduce the actual array bounds from the
-contents of
-.IR array_str .
-
-If the user does specify explicit array bounds (as in the first and
-second forms) then the array may be initialized partly or fully
-using a C-like syntax for array initialization.
-However, the uninitialized array elements will
-contain garbage.
-.PP
-You must have write or append access to a class in order to append to
-it, as well as read access on any class whose values are read in the
-target list or qualification (see
-.IR "change acl" (l)).
-.SH EXAMPLES
-.nf
---
---Make a new employee Jones work for Smith
---
-insert into emp
- select newemp.name, newemp.salary,
- "Smith", 1990-newemp.age
- from newemp
- where name = "Jones"
-.fi
-.nf
---
---Insert into newemp class to newemp
---
-insert into newemp
- select * from newemp1
-.fi
-.nf
---
---Create an empty 3x3 gameboard for noughts-and-crosses
---(all of these queries create the same board attribute)
---
-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,'{{,,},{,,},{,,}}')
-.fi
-.SH "SEE ALSO"
-create table(l),
-create type(l),
-update(l),
-select(l)
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/ipcclean.1,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
-.TH IPCCLEAN UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-ipcclean \(em clean up shared memory and semaphores from aborted backends
-.SH SYNOPSIS
-.BR "ipcclean"
-.SH DESCRIPTION
-.IR Ipcclean
-cleans up shared memory and semaphore space from aborted backends by
-deleting all instances owned by user \*(lqpostgres\*(rq. Only the DBA
-should execute this program as it can cause bizarre behavior (i.e.,
-crashes) if run during multi-user execution. This program should be
-executed if messages such as
-.BR "semget: No space left on device"
-are encountered when starting up the
-.IR postmaster
-or the backend server.
-.SH BUGS
-If this command is executed while a
-.IR postmaster
-is running, the shared memory and semaphores allocated by the
-.IR postmaster
-will be deleted. This will result in a general failure of the
-backends servers started by that
-.IR postmaster .
-.PP
-This script is a hack, but in the many years since it was written, no
-one has come up with an equally effective and portable solution.
-Suggestions are welcome.
-.PP
-The script makes assumption about the format of output of the
-.BR ipcs
-utility which may not be true across different operating systems.
-Therefore, it may not work on your particular OS.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /usr/local/devel/postgres/src/ref/RCS/large_objects.3pqsrc,v 1.12 1
-993/08/23 09:03:16 aoki Exp $
-.TH "LARGE OBJECTS" INTRO 03/18/94 Postgres95 Postgres95
-.SH DESCRIPTION
-.PP
-In Postgres, data values are stored in tuples and individual tuples
-cannot span data pages. Since the size of a data page is 8192 bytes,
-the upper limit on the size of a data value is relatively low. To
-support the storage of larger atomic values, Postgres provides a large
-object interface. This interface provides file-oriented access to
-user data that has been declared to be a large type.
-.PP
-This section describes the implementation and the
-programmatic and query language interfaces to Postgres large object data.
-.PP
-.SH "Historical Note"
-.SH "Historical Note"
-.PP
-Originally, postgres 4.2 supports three standard implementations of large
-objects: as files external to Postgres, as Unix files managed by Postgres, and as
-data stored within the Postgres database. It causes considerable confusion
-among users. As a result, we only support large objects as data stored
-within the Postgres database in Postgres. Even though is is slower to access,
-it provides stricter data integrity and time travel. For historical reasons,
-they are called Inversion large objects. (We will use Inversion and large
-objects interchangeably to mean the same thing in this section.)
-.SH "Inversion Large Objects"
-.SH "Inversion Large Objects"
-.PP
-The Inversion large
-object implementation breaks large objects up into \*(lqchunks\*(rq and
-stores the chunks in tuples in the database. A B-tree index
-guarantees fast searches for the correct chunk number when doing
-random access reads and writes.
-.SH "Large Object Interfaces"
-.SH "Large Object Interfaces"
-.PP
-The facilities Postgres provides to access large objects, both in
-the backend as part of user-defined functions or the front end
-as part of an application using the \*(LQ interface, are described
-below. (For users familiar with postgres 4.2, Postgres has a new set of
-functions providing a more coherent interface. The interface is the same
-for dynamically-loaded C functions as well as for \*(LQ.
-.PP
-The Postgres large object interface is modeled after the Unix file
-system interface, with analogues of
-.I open (2),
-.I read (2),
-.I write (2),
-.I lseek (2),
-etc. User functions call these routines to retrieve only the data of
-interest from a large object. For example, if a large object type
-called
-.I mugshot
-existed that stored photographs of faces, then a function called
-.I beard
-could be declared on
-.I mugshot
-data.
-.I Beard
-could look at the lower third of a photograph, and determine the color
-of the beard that appeared there, if any. The entire large object
-value need not be buffered, or even examined, by the
-.I beard
-function.
-.\"As mentioned above, Postgres supports functional indices on
-.\"large object data. In this example, the results of the
-.\".I beard
-.\"function could be stored in a B-tree index to provide fast searches
-.\"for people with red beards.
-.PP
-Large objects may be accessed from dynamically-loaded C functions
-or database client programs that link the Libpq library.
-Postgres provides a set of routines that
-support opening, reading, writing, closing, and seeking on large
-objects.
-.SH "Creating a Large Object"
-.SH "Creating a Large Object"
-.PP
-The routine
-.nf
-Oid lo_creat(PGconn *conn, int mode)
-.fi
-creates a new large object. The
-.I mode
-is a bitmask describing several different attributes of the new
-object. The symbolic constants listed here are defined in
-.nf
-/usr/local/postgres95/src/backend/libpq/libpq-fs.h
-.fi
-The access type (read, write, or both) is controlled by
-.SM OR
-ing together the bits
-.SM INV_READ
-and
-.SM INV_WRITE .
-If the large object should be archived \(em that is, if
-historical versions of it should be moved periodically to a special
-archive relation \(em then the
-.SM INV_ARCHIVE
-bit should be set. The low-order sixteen bits of
-.I mask
-are the storage manager number on which the large object should
-reside. For sites other than Berkeley, these bits should always be
-zero.
-.\"At Berkeley, storage manager zero is magnetic disk, storage
-.\"manager one is a Sony optical disk jukebox, and storage manager two is
-.\"main memory.
-.PP
-The commands below create an (Inversion) large object:
-.nf
-inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE);
-.fi
-.SH "Importing a Large Object"
-.SH "Importing a Large Object"
-To import a UNIX file as a large object, call
-.nf
-Oid
-lo_import(PGconn *conn, text *filename)
-.fi
-The
-.I filename
-argument specifies the UNIX pathname of the file to be imported as
-a large object.
-.SH "Exporting a Large Object"
-.SH "Exporting a Large Object"
-To export a large object into UNIX file, call
-.nf
-int
-lo_export(PGconn *conn, Oid lobjId, text *filename)
-.fi
-The
-.I lobjId
-argument specifies the Oid of the large object to export and
-the
-.I filename
-argument specifies the UNIX pathname of the file.
-.SH "Opening an Existing Large Object"
-.SH "Opening an Existing Large Object"
-.PP
-To open an existing large object, call
-.nf
-int
-lo_open(PGconn *conn, Oid lobjId, int mode, ...)
-.fi
-The
-.I lobjId
-argument specifies the Oid of the large object to open.
-The mode bits control whether the object is opened for reading
-.SM INV_READ ), (
-writing
-.SM INV_WRITE ), (
-or both.
-.PP
-A large object cannot be opened before it is created.
-.B lo_open
-returns a large object descriptor for later use in
-.B lo_read ,
-.B lo_write ,
-.B lo_lseek ,
-.B lo_tell ,
-and
-.B lo_close .
-.\"-----------
-.SH "Writing Data to a Large Object"
-.SH "Writing Data to a Large Object"
-.PP
-The routine
-.nf
-int
-lo_write(PGconn *conn, int fd, char *buf, int len)
-.fi
-writes
-.I len
-bytes from
-.I buf
-to large object
-.I fd .
-The
-.I fd
-argument must have been returned by a previous
-.I lo_open .
-.PP
-The number of bytes actually written is returned.
-In the event of an error,
-the return value is negative.
-.SH "Seeking on a Large Object"
-.SH "Seeking on a Large Object"
-.PP
-To change the current read or write location on a large object,
-call
-.nf
-int
-lo_lseek(PGconn *conn, int fd, int offset, int whence)
-.fi
-This routine moves the current location pointer for the large object
-described by
-.I fd
-to the new location specified by
-.I offset .
-The valid values for .I whence are
-.SM SEEK_SET
-.SM SEEK_CUR
-and
-.SM SEEK_END.
-.\"-----------
-.SH "Closing a Large Object Descriptor"
-.SH "Closing a Large Object Descriptor"
-.PP
-A large object may be closed by calling
-.nf
-int
-lo_close(PGconn *conn, int fd)
-.fi
-where
-.I fd
-is a large object descriptor returned by
-.I lo_open .
-On success,
-.I lo_close
-returns zero. On error, the return value is negative.
-.PP
-.SH "Built in registered functions"
-.SH "Built in registered functions"
-.PP
-There are two built-in registered functions,
-.I lo_import
-and
-.I lo_export
-which are convenient for use in SQL queries.
-.PP
-Here is an example of there use
-.nf
-CREATE TABLE image (
- name text,
- raster oid
-);
-
-INSERT INTO image (name, raster)
- VALUES ('beautiful image', lo_import('/etc/motd'));
-
-SELECT lo_export(image.raster, "/tmp/motd") from image
- WHERE name = 'beautiful image';
-.fi
-.PP
-.SH "Accessing Large Objects from LIBPQ"
-.SH "Accessing Large Objects from LIBPQ"
-Below is a sample program which shows how the large object interface in
-\*(LP can be used. Parts of the program are commented out but are left
-in the source for the readers benefit. This program can be found in
-.nf
-\&../src/test/examples
-.fi
-.PP
-Frontend applications which use the large object interface in \*(LP
-should include the header file
-.B "libpq/libpq-fs.h"
-and link with the
-.B libpq
-library.
-.bp
-.SH "Sample Program"
-.SH "Sample Program"
-.nf
-/*-------------------------------------------------------------------------
- *
- * testlo.c--
- * test using large objects with libpq
- *
- * Copyright (c) 1994, Regents of the University of California
- *
- *
- * IDENTIFICATION
- * $Header: /cvsroot/pgsql/doc/man/Attic/large_objects.3,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
- *
- *-------------------------------------------------------------------------
- */
-#include <stdio.h>
-#include "libpq-fe.h"
-#include "libpq/libpq-fs.h"
-
-#define BUFSIZE 1024
-
-/*
- * importFile -
- * import file "in_filename" into database as large object "lobjOid"
- *
- */
-Oid importFile(PGconn *conn, char *filename)
-{
- Oid lobjId;
- int lobj_fd;
- char buf[BUFSIZE];
- int nbytes, tmp;
- int fd;
-
- /*
- * open the file to be read in
- */
- fd = open(filename, O_RDONLY, 0666);
- if (fd < 0) { /* error */
- fprintf(stderr, "can't open unix file\"%s\"\n", filename);
- }
-
- /*
- * create the large object
- */
- lobjId = lo_creat(conn, INV_READ|INV_WRITE);
- if (lobjId == 0) {
- fprintf(stderr, "can't create large object");
- }
-
- lobj_fd = lo_open(conn, lobjId, INV_WRITE);
- /*
- * read in from the Unix file and write to the inversion file
- */
- while ((nbytes = read(fd, buf, BUFSIZE)) > 0) {
- tmp = lo_write(conn, lobj_fd, buf, nbytes);
- if (tmp < nbytes) {
- fprintf(stderr, "error while reading \"%s\"", filename);
- }
- }
-
- (void) close(fd);
- (void) lo_close(conn, lobj_fd);
-
- return lobjId;
-}
-
-void pickout(PGconn *conn, Oid lobjId, int start, int len)
-{
- int lobj_fd;
- char* buf;
- int nbytes;
- int nread;
-
- lobj_fd = lo_open(conn, lobjId, INV_READ);
- if (lobj_fd < 0) {
- fprintf(stderr,"can't open large object %d",
- lobjId);
- }
-
- lo_lseek(conn, lobj_fd, start, SEEK_SET);
- buf = malloc(len+1);
-
- nread = 0;
- while (len - nread > 0) {
- nbytes = lo_read(conn, lobj_fd, buf, len - nread);
- buf[nbytes] = '\0';
- fprintf(stderr,">>> %s", buf);
- nread += nbytes;
- }
- fprintf(stderr,"\n");
- lo_close(conn, lobj_fd);
-}
-
-void overwrite(PGconn *conn, Oid lobjId, int start, int len)
-{
- int lobj_fd;
- char* buf;
- int nbytes;
- int nwritten;
- int i;
-
- lobj_fd = lo_open(conn, lobjId, INV_READ);
- if (lobj_fd < 0) {
- fprintf(stderr,"can't open large object %d",
- lobjId);
- }
-
- lo_lseek(conn, lobj_fd, start, SEEK_SET);
- buf = malloc(len+1);
-
- for (i=0;i<len;i++)
- buf[i] = 'X';
- buf[i] = '\0';
-
- nwritten = 0;
- while (len - nwritten > 0) {
- nbytes = lo_write(conn, lobj_fd, buf + nwritten, len - nwritten);
- nwritten += nbytes;
- }
- fprintf(stderr,"\n");
- lo_close(conn, lobj_fd);
-}
-
-
-/*
- * exportFile -
- * export large object "lobjOid" to file "out_filename"
- *
- */
-void exportFile(PGconn *conn, Oid lobjId, char *filename)
-{
- int lobj_fd;
- char buf[BUFSIZE];
- int nbytes, tmp;
- int fd;
-
- /*
- * create an inversion "object"
- */
- lobj_fd = lo_open(conn, lobjId, INV_READ);
- if (lobj_fd < 0) {
- fprintf(stderr,"can't open large object %d",
- lobjId);
- }
-
- /*
- * open the file to be written to
- */
- fd = open(filename, O_CREAT|O_WRONLY, 0666);
- if (fd < 0) { /* error */
- fprintf(stderr, "can't open unix file\"%s\"",
- filename);
- }
-
- /*
- * read in from the Unix file and write to the inversion file
- */
- while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) {
- tmp = write(fd, buf, nbytes);
- if (tmp < nbytes) {
- fprintf(stderr,"error while writing \"%s\"",
- filename);
- }
- }
-
- (void) lo_close(conn, lobj_fd);
- (void) close(fd);
-
- return;
-}
-
-void
-exit_nicely(PGconn* conn)
-{
- PQfinish(conn);
- exit(1);
-}
-
-int
-main(int argc, char **argv)
-{
- char *in_filename, *out_filename;
- char *database;
- Oid lobjOid;
- PGconn *conn;
- PGresult *res;
-
- if (argc != 4) {
- fprintf(stderr, "Usage: %s database_name in_filename out_filename\n",
- argv[0]);
- exit(1);
- }
-
- database = argv[1];
- in_filename = argv[2];
- out_filename = argv[3];
-
- /*
- * set up the connection
- */
- conn = PQsetdb(NULL, NULL, NULL, NULL, database);
-
- /* check to see that the backend connection was successfully made */
- if (PQstatus(conn) == CONNECTION_BAD) {
- fprintf(stderr,"Connection to database '%s' failed.\n", database);
- fprintf(stderr,"%s",PQerrorMessage(conn));
- exit_nicely(conn);
- }
-
- res = PQexec(conn, "begin");
- PQclear(res);
- printf("importing file \"%s\" ...\n", in_filename);
-/* lobjOid = importFile(conn, in_filename); */
- lobjOid = lo_import(conn, in_filename);
-/*
- printf("\tas large object %d.\n", lobjOid);
-
- printf("picking out bytes 1000-2000 of the large object\n");
- pickout(conn, lobjOid, 1000, 1000);
-
- printf("overwriting bytes 1000-2000 of the large object with X's\n");
- overwrite(conn, lobjOid, 1000, 1000);
-*/
-
- printf("exporting large object to file \"%s\" ...\n", out_filename);
-/* exportFile(conn, lobjOid, out_filename); */
- lo_export(conn, lobjOid,out_filename);
-
- res = PQexec(conn, "end");
- PQclear(res);
- PQfinish(conn);
- exit(0);
-}
-.fi
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/libpq.3,v 1.2 1996/10/03 15:50:10 momjian Exp $
-.TH LIBPQ INTRO 03/12/94 Postgres95 Postgres95
-.SH DESCRIPTION
-Libpq is the programmer's interface to Postgres. Libpq is a set of
-library routines that allows queries to pass to the Postgres backend and
-instances to return through an IPC channel.
-.PP
-This version of the documentation describes the C interface library.
-Three short programs are included at the end of this section to show how
-to write programs that use Libpq.
-.PP
-There are several examples of Libpq applications in the following
-directories:
-.nf
-\&../src/test/regress
-\&../src/test/examples
-\&../src/bin/psql
-.fi
-.PP
-Frontend programs which use Libpq must include the header file
-.B "libpq-fe.h"
-and must link with the
-.B libpq
-library.
-.SH "Control and Initialization"
-.PP
-The following environment variables can be used to set up default
-environment values to avoid hard-coding database names into
-an application program:
-.sp
-\(bu
-.B PGHOST
-sets the default server name.
-.sp
-\(bu
-.B PGOPTIONS
-sets additional runtime options for the Postgres backend.
-.sp
-\(bu
-.B PGPORT
-sets the default port for communicating with the Postgres backend.
-.sp
-\(bu
-.B PGTTY
-sets the file or tty on which debugging messages from the backend server
-are displayed.
-.sp
-\(bu
-.B PGDATABASE
-sets the default Postgres database name.
-.sp
-\(bu
-.B PGREALM
-sets the
-.I Kerberos
-realm to use with Postgres, if it is different from the local realm. If
-.B PGREALM
-is set, Postgres applications will attempt authentication with servers
-for this realm and use separate ticket files to avoid conflicts with
-local ticket files. This environment variable is only used if
-.I Kerberos
-authentication is enabled.
-.SH "Database Connection Functions"
-.PP
-The following routines deal with making a connection to a backend
-from a C program.
-.PP
-.B PQsetdb
-.IP
-Makes a new connection to a backend.
-.nf
-PGconn *PQsetdb(char *pghost,
- char *pgport,
- char *pgoptions,
- char *pgtty,
- char *dbName);
-.fi
-If any argument is NULL, then the corresponding environment variable
-is checked. If the environment variable is also not set, then hardwired
-defaults are used.
-.IP
-.I PQsetdb
-always returns a valid PGconn pointer. The
-.I PQstatus
-(see below) command should be called to ensure that a connection was
-properly made before queries are sent via the connection. Libpq
-programmers should be careful to maintain the PGconn abstraction. Use
-the accessor functions below to get at the contents of PGconn. Avoid
-directly referencing the fields of the PGconn structure as they are
-subject to change in the future.
-.IP
-.B PQdb
-returns the database name of the connection.
-.nf
-char *PQdb(PGconn *conn)
-.fi
-.B PQhost
-returns the host name of the connection.
-.nf
-char *PQhost(PGconn *conn)
-.fi
-.B PQoptions
-returns the pgoptions used in the connection.
-.nf
-char *PQoptions(PGconn *conn)
-.fi
-.B PQport
-returns the pgport of the connection.
-.nf
-char *PQport(PGconn *conn)
-.fi
-.B PQtty
-returns the pgtty of the connection.
-.nf
-char *PQtty(PGconn *conn)
-.fi
-.B PQstatus
-Returns the status of the connection. The status can be CONNECTION_OK or
-CONNECTION_BAD.
-.nf
-ConnStatusType *PQstatus(PGconn *conn)
-.fi
-.B PQerrorMessage
-returns the error message associated with the connection
-.nf
-char *PQerrorMessage(PGconn* conn);
-.fi
-.PP
-.B PQfinish
-.IP
-Close the connection to the backend. Also frees memory used by the
-PGconn structure. The PGconn pointer should not be used after PQfinish
-has been called.
-.nf
-void PQfinish(PGconn *conn)
-.fi
-.PP
-.B PQreset
-.IP
-Reset the communication port with the backend. This function will close
-the IPC socket connection to the backend and attempt to reestablish a
-new connection to the same backend.
-.nf
-void PQreset(PGconn *conn)
-.fi
-.PP
-.B PQtrace
-.IP
-Enables tracing of messages passed between the frontend and the backend.
-The messages are echoed to the debug_port file stream.
-.nf
-void PQtrace(PGconn *conn,
- FILE* debug_port);
-.fi
-.PP
-.B PQuntrace
-.IP
-Disables tracing of messages passed between the frontend and the backend.
-.nf
-void PQuntrace(PGconn *conn);
-.fi
-.PP
-.SH "Query Execution Functions"
-.PP
-.B PQexec
-.IP
-Submit a query to Postgres. Returns a PGresult pointer if the query was
-successful or a NULL otherwise. If a NULL is returned,
-.I PQerrorMessage
-can be used to get more information about the error.
-.nf
-PGresult *PQexec(PGconn *conn,
- char *query);
-.fi
-The PGresult structure encapsulates the query result returned by the
-backend. Libpq programmers should be careful to maintain the PGresult
-abstraction. Use the accessor functions described below to retrieve the
-results of the query. Avoid directly referencing the fields of the PGresult
-structure as they are subject to change in the future.
-.PP
-.B PQresultStatus
-.IP
-Returns the result status of the query.
-.I PQresultStatus
-can return one of the following values:
-.nf
-PGRES_EMPTY_QUERY,
-PGRES_COMMAND_OK, /* the query was a command */
-PGRES_TUPLES_OK, /* the query successfully returned tuples */
-PGRES_COPY_OUT,
-PGRES_COPY_IN,
-PGRES_BAD_RESPONSE, /* an unexpected response was received */
-PGRES_NONFATAL_ERROR,
-PGRES_FATAL_ERROR
-.fi
-.IP
-If the result status is PGRES_TUPLES_OK, then the following routines can
-be used to retrieve the tuples returned by the query.
-.IP
-
-.B PQntuples
-returns the number of tuples (instances) in the query result.
-.nf
-int PQntuples(PGresult *res);
-.fi
-
-.B PQnfields
-returns the number of fields (attributes) in the query result.
-.nf
-int PQnfields(PGresult *res);
-.fi
-
-.B PQfname
-returns the field (attribute) name associated with the given field index.
-Field indices start at 0.
-.nf
-char *PQfname(PGresult *res,
- int field_index);
-.fi
-
-.B PQfnumber
-returns the field (attribute) index associated with the given field name.
-.nf
-int PQfnumber(PGresult *res,
- char* field_name);
-.fi
-
-.B PQftype
-returns the field type associated with the given field index. The
-integer returned is an internal coding of the type. Field indices start
-at 0.
-.nf
-Oid PQftype(PGresult *res,
- int field_num);
-.fi
-
-.B PQfsize
-returns the size in bytes of the field associated with the given field
-index. If the size returned is -1, the field is a variable length field.
-Field indices start at 0.
-.nf
-int2 PQfsize(PGresult *res,
- int field_index);
-.fi
-
-.B PQgetvalue
-returns the field (attribute) value. For most queries, the value
-returned by
-.I PQgetvalue
-is a null-terminated ASCII string representation
-of the attribute value. If the query was a result of a
-.B BINARY
-cursor, then the value returned by
-.I PQgetvalue
-is the binary representation of the type in the internal format of the
-backend server. It is the programmer's responsibility to cast and
-convert the data to the correct C type. The value returned by
-.I PQgetvalue
-points to storage that is part of the PGresult structure. One must
-explicitly copy the value into other storage if it is to be used past
-the lifetime of the PGresult structure itself.
-.nf
-char* PQgetvalue(PGresult *res,
- int tup_num,
- int field_num);
-.fi
-
-.B PQgetlength
-returns the length of a field (attribute) in bytes. If the field
-is a
-.I "struct varlena" ,
-the length returned here does
-.B not
-include the size field of the varlena, i.e., it is 4 bytes less.
-.nf
-int PQgetlength(PGresult *res,
- int tup_num,
- int field_num);
-.fi
-
-.B PQgetisnull
-returns the NULL status of a field.
-.nf
-int PQgetisnull(PGresult *res,
- int tup_num,
- int field_num);
-.fi
-
-.PP
-.B PQcmdStatus
-.IP
-Returns the command status associated with the last query command.
-.nf
-char *PQcmdStatus(PGresult *res);
-.fi
-.PP
-.B PQoidStatus
-.IP
-Returns a string with the object id of the tuple inserted if the last
-query is an INSERT command. Otherwise, returns an empty string.
-.nf
-char* PQoidStatus(PGresult *res);
-.fi
-.PP
-.B PQprint
-.IP
-+ Prints out all the tuples in an intelligent manner. The
-.B psql
-+ program uses this function for its output.
-.nf
-void PQprint(
- FILE* fout, /* output stream */
- PGresult* res, /* query results */
- PQprintOpt *ps /* option structure */
- );
-
-.fi
-.I PQprintOpt
-is a typedef'ed structure as defined below.
-.(C
-typedef struct _PQprintOpt {
- bool header; /* print table headings and row count */
- bool align; /* fill align the fields */
- bool standard; /* old brain dead format (needs align) */
- bool html3; /* output html3+ tables */
- bool expanded; /* expand tables */
- bool pager; /* use pager if needed */
- char *fieldSep; /* field separator */
- char *caption; /* html table caption (or NULL) */
- char **fieldName; /* null terminated array of field names (or NULL) */
-} PQprintOpt;
-.fi
-.LP
-.B PQclear
-.IP
-Frees the storage associated with the PGresult. Every query result
-should be properly freed when it is no longer used. Failure to do this
-will result in memory leaks in the frontend application. The PQresult*
-passed in should be a value which is returned from PQexec(). Calling
-PQclear() on an uninitialized PQresult pointer will very likely result
-in a core dump.
-.nf
-void PQclear(PQresult *res);
-.fi
-.PP
-.SH "Fast Path"
-.PP
-Postgres provides a
-.B "fast path"
-interface to send function calls to the backend. This is a trapdoor
-into system internals and can be a potential security hole. Most users
-will not need this feature.
-.nf
-PGresult* PQfn(PGconn* conn,
- int fnid,
- int *result_buf,
- int *result_len,
- int result_is_int,
- PQArgBlock *args,
- int nargs);
-.fi
-.PP
-The
-.I fnid
-argument is the object identifier of the function to be executed.
-.I result_buf
-is the buffer in which to load the return value. The caller must have
-allocated sufficient space to store the return value.
-The result length will be returned in the storage pointed to by
-.I result_len.
-If the result is to be an integer value, than
-.I result_is_int
-should be set to 1; otherwise it should be set to 0.
-.I args
-and
-.I nargs
-specify the arguments to the function.
-.nf
-typedef struct {
- int len;
- int isint;
- union {
- int *ptr;
- int integer;
- } u;
-} PQArgBlock;
-.fi
-.PP
-.I PQfn
-always returns a valid PGresult*. The resultStatus should be checked
-before the result is used. The caller is responsible for freeing the
-PGresult with
-.I PQclear
-when it is not longer needed.
-.PP
-.SH "Asynchronous Notification"
-.PP
-Postgres supports asynchronous notification via the
-.I LISTEN
-and
-.I NOTIFY
-commands. A backend registers its interest in a particular relation
-with the LISTEN command. All backends listening on a particular
-relation will be notified asynchronously when a NOTIFY of that relation
-name is executed by another backend. No additional information is
-passed from the notifier to the listener. Thus, typically, any actual
-data that needs to be communicated is transferred through the relation.
-.PP
-Libpq applications are notified whenever a connected backend has
-received an asynchronous notification. However, the communication from
-the backend to the frontend is not asynchronous. Notification comes
-piggy-backed on other query results. Thus, an application must submit
-queries, even empty ones, in order to receive notice of backend
-notification. In effect, the Libpq application must poll the backend to
-see if there is any pending notification information. After the
-execution of a query, a frontend may call
-.I PQNotifies
-to see if any notification data is available from the backend.
-.PP
-.B PQNotifies
-.IP
-returns the notification from a list of unhandled notifications from the
-backend. Returns NULL if there are no pending notifications from the
-backend.
-.I PQNotifies
-behaves like the popping of a stack. Once a notification is returned
-from
-.I PQnotifies,
-it is considered handled and will be removed from the list of
-notifications.
-.nf
-PGnotify* PQNotifies(PGconn *conn);
-.fi
-.PP
-The second sample program gives an example of the use of asynchronous
-notification.
-.PP
-.SH "Functions Associated with the COPY Command"
-.PP
-The
-.I copy
-command in Postgres has options to read from or write to the network
-connection used by Libpq. Therefore, functions are necessary to
-access this network connection directly so applications may take full
-advantage of this capability.
-.PP
-.B PQgetline
-.IP
-Reads a newline-terminated line of characters (transmitted by the
-backend server) into a buffer
-.I string
-of size
-.I length .
-Like
-.I fgets (3),
-this routine copies up to
-.I length "-1"
-characters into
-.I string .
-It is like
-.I gets (3),
-however, in that it converts the terminating newline into a null
-character.
-.IP
-.I PQgetline
-returns EOF at EOF, 0 if the entire line has been read, and 1 if the
-buffer is full but the terminating newline has not yet been read.
-.IP
-Notice that the application must check to see if a new line consists
-of the single character \*(lq.\*(rq, which indicates that the backend
-server has finished sending the results of the
-.I copy
-command. Therefore, if the application ever expects to receive lines
-that are more than
-.I length "-1"
-characters long, the application must be sure to check the return
-value of
-.I PQgetline
-very carefully.
-.IP
-The code in
-.nf
-\&../src/bin/psql/psql.c
-.fi
-contains routines that correctly handle the copy protocol.
-.nf
-int PQgetline(PGconn *conn,
- char *string,
- int length)
-.fi
-.PP
-.B PQputline
-.IP
-Sends a null-terminated
-.I string
-to the backend server.
-.IP
-The application must explicitly send the single character \*(lq.\*(rq
-to indicate to the backend that it has finished sending its data.
-.nf
-void PQputline(PGconn *conn,
- char *string);
-.fi
-.PP
-.B PQendcopy
-.IP
-Syncs with the backend. This function waits until the backend has
-finished the copy. It should either be issued when the
-last string has been sent to the backend using
-.I PQputline
-or when the last string has been received from the backend using
-.I PGgetline .
-It must be issued or the backend may get \*(lqout of sync\*(rq with
-the frontend. Upon return from this function, the backend is ready to
-receive the next query.
-.IP
-The return value is 0 on successful completion, nonzero otherwise.
-.nf
-int PQendcopy(PGconn *conn);
-.fi
-As an example:
-.nf
-PQexec(conn, "create table foo (a int4, b char16, d float8)");
-PQexec(conn, "copy foo from stdin");
-PQputline(conn, "3<TAB>hello world<TAB>4.5\en");
-PQputline(conn,"4<TAB>goodbye world<TAB>7.11\en");
-\&...
-PQputline(conn,".\en");
-PQendcopy(conn);
-.fi
-.PP
-.SH "LIBPQ Tracing Functions"
-.PP
-.B PQtrace
-.IP
-Enable tracing of the frontend/backend communication to a debugging file
-stream.
-.nf
-void PQtrace(PGconn *conn
- FILE *debug_port)
-.fi
-.PP
-.B PQuntrace
-.IP
-Disable tracing started by
-.I PQtrace
-.nf
-void PQuntrace(PGconn *conn)
-.fi
-.PP
-.SH "User Authentication Functions"
-.PP
-If the user has generated the appropriate authentication credentials
-(e.g., obtaining
-.I Kerberos
-tickets), the frontend/backend authentication process is handled by
-.I PQexec
-without any further intervention. The following routines may be
-called by Libpq programs to tailor the behavior of the authentication
-process.
-.PP
-.B fe_getauthname
-.IP
-Returns a pointer to static space containing whatever name the user
-has authenticated. Use of this routine in place of calls to
-.I getenv (3)
-or
-.I getpwuid (3)
-by applications is highly recommended, as it is entirely possible that
-the authenticated user name is
-.B not
-the same as value of the
-.B USER
-environment variable or the user's entry in
-.I /etc/passwd .
-.nf
-char *fe_getauthname(char* errorMessage)
-.fi
-.PP
-.B fe_setauthsvc
-.IP
-Specifies that Libpq should use authentication service
-.I name
-rather than its compiled-in default. This value is typically taken
-from a command-line switch.
-.nf
-void fe_setauthsvc(char *name,
- char* errorMessage)
-.fi
-Any error messages from the authentication attempts are returned in the
-errorMessage argument.
-.PP
-.SH "BUGS"
-.PP
-The query buffer is 8192 bytes long, and queries over that length will
-be silently truncated.
-.PP
-.SH "Sample Programs"
-.bp
-.SH "Sample Program 1"
-.PP
-.nf M
-/*
- * testlibpq.c
- * Test the C version of Libpq, the Postgres frontend library.
- *
- *
- */
-#include <stdio.h>
-#include "libpq-fe.h"
-
-void
-exit_nicely(PGconn* conn)
-{
- PQfinish(conn);
- exit(1);
-}
-
-main()
-{
- char *pghost, *pgport, *pgoptions, *pgtty;
- char* dbName;
- int nFields;
- int i,j;
-
-/* FILE *debug; */
-
- PGconn* conn;
- PGresult* res;
-
- /* begin, by setting the parameters for a backend connection
- if the parameters are null, then the system will try to use
- reasonable defaults by looking up environment variables
- or, failing that, using hardwired constants */
- pghost = NULL; /* host name of the backend server */
- pgport = NULL; /* port of the backend server */
- pgoptions = NULL; /* special options to start up the backend server */
- pgtty = NULL; /* debugging tty for the backend server */
- dbName = "template1";
-
- /* make a connection to the database */
- conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
- /* check to see that the backend connection was successfully made */
- if (PQstatus(conn) == CONNECTION_BAD) {
- fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
- fprintf(stderr,"%s",PQerrorMessage(conn));
- exit_nicely(conn);
- }
-
-/* debug = fopen("/tmp/trace.out","w"); */
-/* PQtrace(conn, debug); */
-
- /* start a transaction block */
- res = PQexec(conn,"BEGIN");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"BEGIN command failed\n");
- PQclear(res);
- exit_nicely(conn);
- }
- /* should PQclear PGresult whenever it is no longer needed to avoid
- memory leaks */
- PQclear(res);
-
- /* fetch instances from the pg_database, the system catalog of databases*/
- res = PQexec(conn,"DECLARE mycursor CURSOR FOR select * from pg_database");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"DECLARE CURSOR command failed\n");
- PQclear(res);
- exit_nicely(conn);
- }
- PQclear(res);
-
- res = PQexec(conn,"FETCH ALL in mycursor");
- if (PQresultStatus(res) != PGRES_TUPLES_OK) {
- fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
- PQclear(res);
- exit_nicely(conn);
- }
-
- /* first, print out the attribute names */
- nFields = PQnfields(res);
- for (i=0; i < nFields; i++) {
- printf("%-15s",PQfname(res,i));
- }
- printf("\n\n");
-
- /* next, print out the instances */
- for (i=0; i < PQntuples(res); i++) {
- for (j=0 ; j < nFields; j++) {
- printf("%-15s", PQgetvalue(res,i,j));
- }
- printf("\n");
- }
-
- PQclear(res);
-
- /* close the cursor */
- res = PQexec(conn, "CLOSE mycursor");
- PQclear(res);
-
- /* end the transaction */
- res = PQexec(conn, "END");
- PQclear(res);
-
- /* close the connection to the database and cleanup */
- PQfinish(conn);
-
-/* fclose(debug); */
-}
-.fi
-.bp
-.SH "Sample Program 2"
-.PP
-.nf M
-/*
- * testlibpq2.c
- * Test of the asynchronous notification interface
- *
- populate a database with the following:
-
-CREATE TABLE TBL1 (i int4);
-
-CREATE TABLE TBL2 (i int4);
-
-CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values (new.i); NOTIFY TBL2];
-
- * Then start up this program
- * After the program has begun, do
-
-INSERT INTO TBL1 values (10);
-
- *
- *
- */
-#include <stdio.h>
-#include "libpq-fe.h"
-
-void exit_nicely(PGconn* conn)
-{
- PQfinish(conn);
- exit(1);
-}
-
-main()
-{
- char *pghost, *pgport, *pgoptions, *pgtty;
- char* dbName;
- int nFields;
- int i,j;
-
- PGconn* conn;
- PGresult* res;
- PGnotify* notify;
-
- /* begin, by setting the parameters for a backend connection
- if the parameters are null, then the system will try to use
- reasonable defaults by looking up environment variables
- or, failing that, using hardwired constants */
- pghost = NULL; /* host name of the backend server */
- pgport = NULL; /* port of the backend server */
- pgoptions = NULL; /* special options to start up the backend server */
- pgtty = NULL; /* debugging tty for the backend server */
- dbName = getenv("USER"); /* change this to the name of your test database*/
-
- /* make a connection to the database */
- conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
- /* check to see that the backend connection was successfully made */
- if (PQstatus(conn) == CONNECTION_BAD) {
- fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
- fprintf(stderr,"%s",PQerrorMessage(conn));
- exit_nicely(conn);
- }
-
- res = PQexec(conn, "LISTEN TBL2");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"LISTEN command failed\n");
- PQclear(res);
- exit_nicely(conn);
- }
- /* should PQclear PGresult whenever it is no longer needed to avoid
- memory leaks */
- PQclear(res);
-
- while (1) {
- /* async notification only come back as a result of a query*/
- /* we can send empty queries */
- res = PQexec(conn, " ");
-/* printf("res->status = %s\n", pgresStatus[PQresultStatus(res)]); */
- /* check for asynchronous returns */
- notify = PQnotifies(conn);
- if (notify) {
- fprintf(stderr,
- "ASYNC NOTIFY of '%s' from backend pid '%d' received\n",
- notify->relname, notify->be_pid);
- free(notify);
- break;
- }
- PQclear(res);
- }
-
- /* close the connection to the database and cleanup */
- PQfinish(conn);
-
-}
-.fi
-.bp
-.SH "Sample Program 3"
-.PP
-.nf M
-/*
- * testlibpq3.c
- * Test the C version of Libpq, the Postgres frontend library.
- * tests the binary cursor interface
- *
- *
- *
- populate a database by doing the following:
-
-CREATE TABLE test1 (i int4, d float4, p polygon);
-
-INSERT INTO test1 values (1, 3.567, '(3.0, 4.0, 1.0, 2.0)'::polygon);
-
-INSERT INTO test1 values (2, 89.05, '(4.0, 3.0, 2.0, 1.0)'::polygon);
-
- the expected output is:
-
-tuple 0: got
- i = (4 bytes) 1,
- d = (4 bytes) 3.567000,
- p = (4 bytes) 2 points boundbox = (hi=3.000000/4.000000, lo = 1.000000,2.000000)
-tuple 1: got
- i = (4 bytes) 2,
- d = (4 bytes) 89.050003,
- p = (4 bytes) 2 points boundbox = (hi=4.000000/3.000000, lo = 2.000000,1.000000)
-
- *
- */
-#include <stdio.h>
-#include "libpq-fe.h"
-#include "utils/geo-decls.h" /* for the POLYGON type */
-
-void exit_nicely(PGconn* conn)
-{
- PQfinish(conn);
- exit(1);
-}
-
-main()
-{
- char *pghost, *pgport, *pgoptions, *pgtty;
- char* dbName;
- int nFields;
- int i,j;
- int i_fnum, d_fnum, p_fnum;
-
- PGconn* conn;
- PGresult* res;
-
- /* begin, by setting the parameters for a backend connection
- if the parameters are null, then the system will try to use
- reasonable defaults by looking up environment variables
- or, failing that, using hardwired constants */
- pghost = NULL; /* host name of the backend server */
- pgport = NULL; /* port of the backend server */
- pgoptions = NULL; /* special options to start up the backend server */
- pgtty = NULL; /* debugging tty for the backend server */
-
- dbName = getenv("USER"); /* change this to the name of your test database*/
-
- /* make a connection to the database */
- conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
-
- /* check to see that the backend connection was successfully made */
- if (PQstatus(conn) == CONNECTION_BAD) {
- fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
- fprintf(stderr,"%s",PQerrorMessage(conn));
- exit_nicely(conn);
- }
-
- /* start a transaction block */
- res = PQexec(conn,"BEGIN");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"BEGIN command failed\n");
- PQclear(res);
- exit_nicely(conn);
- }
- /* should PQclear PGresult whenever it is no longer needed to avoid
- memory leaks */
- PQclear(res);
-
- /* fetch instances from the pg_database, the system catalog of databases*/
- res = PQexec(conn,"DECLARE mycursor BINARY CURSOR FOR select * from test1");
- if (PQresultStatus(res) != PGRES_COMMAND_OK) {
- fprintf(stderr,"DECLARE CURSOR command failed\n");
- PQclear(res);
- exit_nicely(conn);
- }
- PQclear(res);
-
- res = PQexec(conn,"FETCH ALL in mycursor");
- if (PQresultStatus(res) != PGRES_TUPLES_OK) {
- fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
- PQclear(res);
- exit_nicely(conn);
- }
-
- i_fnum = PQfnumber(res,"i");
- d_fnum = PQfnumber(res,"d");
- p_fnum = PQfnumber(res,"p");
-
- for (i=0;i<3;i++) {
- printf("type[%d] = %d, size[%d] = %d\n",
- i, PQftype(res,i),
- i, PQfsize(res,i));
- }
- for (i=0; i < PQntuples(res); i++) {
- int *ival;
- float *dval;
- int plen;
- POLYGON* pval;
- /* we hard-wire this to the 3 fields we know about */
- ival = (int*)PQgetvalue(res,i,i_fnum);
- dval = (float*)PQgetvalue(res,i,d_fnum);
- plen = PQgetlength(res,i,p_fnum);
-
- /* plen doesn't include the length field so need to increment by VARHDSZ*/
- pval = (POLYGON*) malloc(plen + VARHDRSZ);
- pval->size = plen;
- memmove((char*)&pval->npts, PQgetvalue(res,i,p_fnum), plen);
- printf("tuple %d: got\n", i);
- printf(" i = (%d bytes) %d,\n",
- PQgetlength(res,i,i_fnum), *ival);
- printf(" d = (%d bytes) %f,\n",
- PQgetlength(res,i,d_fnum), *dval);
- printf(" p = (%d bytes) %d points \tboundbox = (hi=%f/%f, lo = %f,%f)\n",
- PQgetlength(res,i,d_fnum),
- pval->npts,
- pval->boundbox.xh,
- pval->boundbox.yh,
- pval->boundbox.xl,
- pval->boundbox.yl);
- }
-
- PQclear(res);
-
- /* close the cursor */
- res = PQexec(conn, "CLOSE mycursor");
- PQclear(res);
-
- /* end the transaction */
- res = PQexec(conn, "END");
- PQclear(res);
-
- /* close the connection to the database and cleanup */
- PQfinish(conn);
-
-}
-.fi
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/listen.l,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
-.TH "LISTEN" SQL 03/12/94 Postgres95 Postgres95
-.SH NAME
-listen \(em listen for notification on a relation
-.SH SYNOPSIS
-.nf
-\fBlisten\fR class_name
-.fi
-.SH DESCRIPTION
-.BR listen
-is used to register the current backend as a listener on the relation
-.IR class_name .
-When the command
-.BI notify " class_name"
-is called either from within a rule or at the query level, the
-frontend applications corresponding to the listening backends
-are notified. When the backend process exits, this registration
-is cleared.
-.PP
-This event notification is performed through the Libpq protocol
-and frontend application interface. The application program
-must explicitly poll a Libpq global variable,
-.IR PQAsyncNotifyWaiting ,
-and call the routine
-.IR PQnotifies
-in order to find out the name of the class to which a given
-notification corresponds. If this code is not included in
-the application, the event notification will be queued and
-never be processed.
-.SH "SEE ALSO"
-create rule(l),
-notify(l),
-select(l),
-libpq.
-.SH BUGS
-There is no way to un-\c
-.BR listen
-except to drop the connection (i.e., restart the backend server).
-.PP
-The
-.IR monitor (1)
-command does not poll for asynchronous events.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/load.l,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
-.TH LOAD SQL 01/23/93 Postgres95 Postgres95
-.SH NAME
-load \(em dynamically load an object file
-.SH SYNOPSIS
-.nf
-\fBload\fR "filename"
-.fi
-.SH DESCRIPTION
-.BR Load
-loads an object (or ".o") file into Postgres's address space. Once a
-file is loaded, all functions in that file can be accessed. This
-function is used in support of ADT's.
-.PP
-If a file is not loaded using the
-.BR load
-command, the file will be loaded automatically the first time the
-function is called by Postgres.
-.BR Load
-can also be used to reload an object file if it has been edited and
-recompiled. Only objects created from C language files are supported
-at this time.
-.SH EXAMPLE
-.nf
---
---Load the file /usr/postgres/demo/circle.o
---
-load "/usr/postgres/demo/circle.o"
-.fi
-.SH CAVEATS
-Functions in loaded object files should not call functions in other
-object files loaded through the
-.BR load
-command, meaning, for example, that all functions in file A should
-call each other, functions in the standard or math libraries, or in
-Postgres itself. They should not call functions defined in a different
-loaded file B. This is because if B is reloaded, the Postgres loader is
-not \*(lqsmart\*(rq enough to relocate the calls from the functions in A into
-the new address space of B. If B is not reloaded, however, there will
-not be a problem.
-.PP
-On DECstations, you must use
-.IR /bin/cc
-with the \*(lq-G 0\*(rq option when compiling object files to be
-loaded.
-.PP
-Note that if you are porting Postgres to a new platform, the
-.BR load
-command will have to work in order to support ADTs.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/monitor.1,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
-.TH MONITOR UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-monitor \(em run the interactive terminal monitor
-.SH SYNOPSIS
-.BR monitor
-[\c
-.BR "-N"
-]
-[\c
-.BR "-Q"
-]
-[\c
-.BR "-T"
-]
-[\c
-.BR "-a"
-system]
-[\c
-.BR "-c"
-query]
-[\c
-.BR "-d"
-path]
-.br
-.in +5n
-[\c
-.BR "-h"
-hostname]
-[\c
-.BR "-p"
-port]
-[\c
-.BR "-q"
-]
-[\c
-.BR "-t"
-tty_device]
-[dbname]
-.in -5n
-.SH DESCRIPTION
-The interactive terminal monitor is a simple frontend to Postgres retained
-for backwards compatiblity. Users are encouraged to the use the
-.IR "psql"
-interface instead.
-.PP
-.IR "monitor"
-enables you to formulate, edit and review queries before issuing them
-to Postgres. If changes must be made, a Unix editor may be called
-to edit the
-.BR "query buffer"
-managed by the terminal monitor. The editor used is determined by the
-value of the
-.SM EDITOR
-environment variable. If
-.SM EDITOR
-is not set, then
-.BR "vi"
-is used by default.
-.PP
-.IR "Monitor"
-is a frontend application, like any other. Hence, a
-.IR "postmaster"
-process must be running on the database server host before
-.IR "monitor"
-is executed. In addition, the correct
-.IR "postmaster"
-port number must be specified
-as described below.
-.PP
-The optional argument
-.IR dbname
-specifies the name of the database to be accessed. This database must
-already have been created using
-.IR createdb .
-.IR Dbname
-defaults to the value of the
-.SM USER
-environment variable.
-.PP
-.IR "Monitor"
-understands the following command-line options:
-.TP 5n
-.BR "-N"
-Specifies that query results will be dumped to the screen without any
-attempt at formatting. This is useful in with the
-.BR -c
-option in shell scripts.
-.TP
-.BR "-Q"
-Produces extremely unverbose output.
-This is useful
-with the
-.BR -c
-option in shell scripts.
-.TP
-.BR "-T"
-Specifies that attribute names will not be printed.
-This is useful
-with the
-.BR -c
-option in shell scripts.
-.TP
-.BR "-a" " system"
-Specifies an authentication system
-.IR "system"
-(see
-.IR introduction (1))
-to use in connecting to the
-.IR postmaster
-process. The default is site-specific.
-.TP
-.BR "-c" " query"
-Specifies that
-.IR "monitor"
-is to execute one query string,
-.IR "query" ,
-and then exit. This is useful for shell scripts, typically in
-conjunction with the
-.BR -N
-and
-.BR -T
-options. Examples of shell scripts in the Postgres distribution using
-.IB "monitor" " -c"
-include
-.IR createdb ,
-.IR destroydb ,
-.IR createuser ,
-and
-.IR destroyuser ,
-.TP
-.BR "-d" " path"
-.IR path
-specifies the path name of the file or tty to which frontend (i.e.,
-.IR monitor )
-debugging messages are to be written; the default is not to generate
-any debugging messages.
-.TP
-.BR "-h" " hostname"
-Specifies the hostname of the machine on which the
-.IR postmaster
-is running. Defaults to the name of the local host, or the value of
-the
-.SM PGHOST
-environment variable (if set).
-.TP
-.BR "-p" " port"
-Specifies the Internet TCP port on which the
-.IR postmaster
-is listening for connections. Defaults to 5432, or the value of the
-.SM PGPORT
-environment variable (if set).
-.TP
-.BR "-q"
-Specifies that the monitor should do its work quietly. By default, it
-prints welcome and exit messages and the queries it sends to the
-backend. If this option is used, none of this happens.
-.TP
-.BR "-t" " tty_device"
-.IR "tty_device"
-specifies the path name to the file or tty
-to which backend (i.e.,
-.IR postgres )
-debugging messages are to be written; the default is
-.IR "/dev/null" .
-.TP
-.BR "-s"
-parses after each query (enables "single step" mode).
-.TP
-.BR "-S"
-Turns off sending query when ";" is encountered.
-.PP
-You may set environment variables to avoid typing some of the above
-options. See the
-.SM "ENVIRONMENT VARIABLES"
-section below.
-.SH "MESSAGES AND PROMPTS"
-The terminal monitor gives a variety of messages to keep the user
-informed of the status of the monitor and the query buffer.
-.PP
-The terminal monitor displays two kinds of messages:
-.IP go
-The query buffer is empty and the terminal monitor is ready for input.
-Anything typed will be added to the buffer.
-.IP *
-This prompt is typed at the beginning of each line when the terminal
-monitor is waiting for input.
-.SH "TERMINAL MONITOR COMMANDS"
-.IP \ee
-Enter the editor to edit the query buffer.
-.IP \eg
-Submit query buffer to Postgres for execution.
-.IP \eh
-Get on-line help.
-.IP "\ei \fIfilename\fR"
-Include the file
-.IR filename
-into the query buffer.
-.IP \ep
-Print the current contents of the query buffer.
-.IP \eq
-Exit from the terminal monitor.
-.IP \er
-Reset (clear) the query buffer.
-.IP \es
-Escape to a Unix subshell. To return to the terminal monitor, type
-\*(lqexit\*(rq at the shell prompt.
-.IP \et
-Print the current time.
-.IP "\ew \fIfilename\fR"
-Store (write) the query buffer to an external file
-.IR filename .
-.IP \e\e
-Produce a single backslash at the current location in query buffer.
-.IP \e;
-Produce a single semi-colon at the current location in query buffer.
-.SH "ENVIRONMENT VARIABLES"
-You may set any of the following environment variables to avoid
-specifying command-line options:
-.nf
-hostname: PGHOST
-port: PGPORT
-tty: PGTTY
-options: PGOPTION
-realm: PGREALM
-.fi
-.PP
-If
-.SM PGOPTION
-is specified, then the options it contains are parsed
-.BR before
-any command-line options.
-.PP
-.SM PGREALM
-only applies if
-.IR Kerberos
-authentication is in use. If this environment variable is set, Postgres
-will attempt authentication with servers for this realm and use
-separate ticket files to avoid conflicts with local ticket files. See
-.IR introduction (1)
-for additional information on
-.IR Kerberos .
-.PP
-See
-.IR introduction (libpq)
-for additional details.
-.SH "RETURN VALUE"
-When executed with the
-.BR "-c"
-option,
-.IR monitor
-returns 0 to the shell on successful query completion, 1 otherwise.
-.SH "SEE ALSO"
-introduction(libpq),
-createdb(1),
-createuser(1),
-postgres(1),
-postmaster(1).
-.SH BUGS
-Does not poll for asynchronous notification events generated by
-.IR listen (l)
-and
-.IR notify (l).
-.PP
-Escapes (backslash characters) cannot be commented out.
-.SH "SEE ALSO"
-psql(1)
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/notify.l,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
-.TH "NOTIFY" SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-notify \(em signal all frontends and backends listening on a class
-.SH SYNOPSIS
-.nf
-\fBnotify\fR class_name
-.fi
-.SH DESCRIPTION
-.BR notify
-is used to awaken all backends and consequently all frontends
-that have executed
-.IR listen (l)
-on
-.IR class_name .
-This can be used either within an instance-level rule as part of the
-action body or from a normal query. When used from within a normal
-query, this can be thought of as interprocess communication (IPC).
-When used from within a rule, this can be thought of as an alerter
-mechanism.
-.PP
-Notice that the mere fact that a
-.BR notify
-has been executed does not imply anything in particular about
-the state of the class (e.g., that it has been updated), nor
-does the notification protocol transmit any useful information
-other than the class name. Therefore, all
-.BR notify
-does is indicate that some backend wishes its peers to examine
-.IR class_name
-in some application-specific way.
-.PP
-This event notification is performed through the Libpq protocol
-and frontend application interface. The application program
-must explicitly poll a Libpq global variable,
-.IR PQAsyncNotifyWaiting ,
-and call the routine
-.IR PQnotifies
-in order to find out the name of the class to which a given
-notification corresponds. If this code is not included in
-the application, the event notification will be queued and
-never be processed.
-.SH "SEE ALSO"
-define rule(l),
-listen(l),
-libpq.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
-.TH PAGE FILES 01/23/93 Postgres95 Postgres95
-.SH NAME
-page structure \(em Postgres database file default page format
-.SH DESCRIPTION
-This section provides an overview of the page format used by Postgres
-classes. User-defined access methods need not use this page format.
-.PP
-In the following explanation, a
-.BR byte
-is assumed to contain 8 bits. In addition, the term
-.BR item
-refers to data which is stored in Postgres classes.
-.if t \{
-Diagram 1 shows how pages in both normal Postgres classes and Postgres index
-classes (e.g., a B-tree index) are structured.
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
-.in +0.5i
-.(b M
-.PS
-.ps 11
-box with .sw at (0.99,6.01) width 5.50 height 3.50
-line from 0.988,9.012 to 6.487,9.012
-line from 3.737,9.512 to 3.737,9.012
-line from 5.112,9.512 to 5.112,9.012
-dashwid = 0.050i
-line dashed from 2.362,9.512 to 2.362,9.012
-line dashed from 3.050,9.512 to 3.050,9.012
-line dashed from 1.675,9.512 to 1.675,9.012
-line from 3.737,6.013 to 3.737,6.513 to 6.487,6.513
-line from 0.988,7.763 to 2.362,7.763 to 2.362,8.262 to 6.487,8.262
-line from 0.988,7.263 to 5.112,7.263 to 5.112,7.763 to 6.487,7.763
-line dashed from 2.362,7.763 to 5.112,7.763
-line dashed from 5.112,8.262 to 5.112,7.763
-line dashed from 4.300,8.262 to 4.300,7.763
-dashwid = 0.037i
-line dotted <-> from 2.425,8.325 to 6.425,8.325
-line dotted <-> from 1.050,9.575 to 3.675,9.575
-line dotted <-> from 3.800,9.575 to 5.050,9.575
-line dotted <-> from 5.175,9.575 to 6.425,9.575
-"\s10\fRitemPointerData\fP" at 2.925,7.978 ljust
-"\s10\fRfiller\fP" at 4.562,7.978 ljust
-"\s10\fRitemData...\fP" at 5.513,7.978 ljust
-"\s10\fIUnallocated Space\fP" at 3.237,8.753 ljust
-"\s10\fBItemContinuationData\fP" at 3.663,8.415 ljust
-"\s10\fISpecial Space\fP" at 4.688,6.240 ljust
-"\s10\fI``ItemData 2''\fP" at 2.587,7.478 ljust
-"\s10\fI``ItemData 1''\fP" at 3.413,6.865 ljust
-"\s10\fBItemIdData\fP" at 4.775,9.715 ljust
-"\s10\fBPageHeaderData\fP" at 1.875,9.715 ljust
-.PE
-.ce
-.BR "Diagram 1: Sample Page Layout"
-.)b
-.in -0.5i
-\}
-.\" Running
-.\" .q .../bin/dumpbpages
-.\" or
-.\" .q .../src/support/dumpbpages
-.\" as the postgres superuser
-.\" with the file paths associated with
-.\" (heap or B-tree index) classes,
-.\" .q .../data/base/<database-name>/<class-name>,
-.\" will display the page structure used by the classes.
-.\" Specifying the
-.\" .q -r
-.\" flag will cause the classes to be
-.\" treated as heap classes and for more information to be displayed.
-.PP
-The first 8 bytes of each page consists of a page header
-.RB ( PageHeaderData ).
-Within the header, the first three 2-byte integer fields,
-.IR lower ,
-.IR upper ,
-and
-.IR special ,
-represent byte offsets to the start of unallocated space, to the end
-of unallocated space, and to the start of \*(lqspecial space.\*(rq
-Special space is a region at the end of the page which is allocated at
-page initialization time and which contains information specific to an
-access method. The last 2 bytes of the page header,
-.IR opaque ,
-encode the page size and information on the internal fragmentation of
-the page. Page size is stored in each page because frames in the
-buffer pool may be subdivided into equal sized pages on a frame by
-frame basis within a class. The internal fragmentation information is
-used to aid in determining when page reorganization should occur.
-.PP
-Following the page header are item identifiers
-.RB ( ItemIdData ).
-New item identifiers are allocated from the first four bytes of
-unallocated space. Because an item identifier is never moved until it
-is freed, its index may be used to indicate the location of an item on
-a page. In fact, every pointer to an item
-.RB ( ItemPointer )
-created by Postgres consists of a frame number and an index of an item
-identifier. An item identifier contains a byte-offset to the start of
-an item, its length in bytes, and a set of attribute bits which affect
-its interpretation.
-.PP
-The items, themselves, are stored in space allocated backwards from
-the end of unallocated space. Usually, the items are not interpreted.
-However when the item is too long to be placed on a single page or
-when fragmentation of the item is desired, the item is divided and
-each piece is handled as distinct items in the following manner. The
-first through the next to last piece are placed in an item
-continuation structure
-.BR ( ItemContinuationData ).
-This structure contains
-.IR itemPointerData
-which points to the next piece and the piece itself. The last piece
-is handled normally.
-.SH FILES
-.TP 5n
-\&.../data/...
-Location of shared (global) database files.
-.TP 5n
-\&.../data/base/...
-Location of local database files.
-.SH BUGS
-The page format may change in the future to provide more efficient
-access to large objects.
-.PP
-This section contains insufficient detail to be of any assistance in
-writing a new access method.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/pg_dump.1,v 1.2 1996/09/19 20:09:02 scrappy Exp $
-.TH PG_DUMP UNIX 1/20/96 Postgres95 Postgres95
-.SH NAME
-pg_dump \(em dumps out a Postgres database into a script file
-.SH SYNOPSIS
-.BR pg_dump
-[\c
-.BR "-f"
-filename
-]
-[\c
-.BR "-H"
-hostname
-]
-[\c
-.BR "-p"
-port]
-[\c
-.BR "-v"
-]
-[\c
-.BR "-d[a]"
-]
-[\c
-.BR "-S"
-help]
-[\c
-.BR "-a"
-]
-[\c
-.BR "-t"
-table]
-[\c
-.BR "-o"
-]
-dbname
-.in -5n
-.SH DESCRIPTION
-.IR "pg_dump"
-is a utility for dumping out a
-Postgres database into a script file containing query commands. The script
-files are in a ASCII format and can be used to reconstruct the database,
-even on other machines and other architectures.
-.IR "pg_dump"
-will produce the queries necessary to re-generate all
-user-defined types, functions, tables, indices, aggregates, and
-operators. In addition, all the data is copied out in ASCII format so
-that it can be readily copied in again, as well, as imported into tools
-for textual editing.
-.PP
-.IR "pg_dump"
-is useful for dumping out the contents of a database to move from one
-postgres95 installation to another. After running
-.IR "pg_dump"
-, one should examine the output script file for any warnings, especially
-in light of the limitations listed below.
-.SH "CAVEATS AND LIMITATIONS"
-.IR pg_dump
-has a few limitations.
-The limitations mostly stem from
-difficulty in extracting certain meta-information from the system
-catalogs.
-.TP
-.BR "rules and views"
-pg_dump does not understand user-defined rules and views and
-will fail to dump them properly. (This is due to the fact that
-rules are stored as plans in the catalogs and not textually)
-.TP
-.BR "partial indices"
-pg_dump does not understand partial indices. (The reason is
-the same as above. Partial index predicates are stored as plans)
-.TP
-.BR "large objects"
-pg_dump does not handle large objects. Large objects are ignored and
-must be dealt with manually.
-.TP
-.BR "oid preservation"
-pg_dump does not preserve oid's while dumping. If you have
-stored oid's explicitly in tables in user-defined attributes,
-and are using them as keys, then the output scripts will not
-regenerate your database correctly.
-.SH "SEE ALSO"
-copy(l)
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/pg_hba.conf.5,v 1.1 1996/11/09 10:29:49 scrappy Exp $
-.TH pg_hba.conf 5 11/04/96 Postgres Postgres
-.SH NAME
-$PGDATA/pg_hba.conf
-.SH DESCRIPTION
-"Host-based access control" is the name for the basic controls Postgres
-exercises on what clients are allowed to access a database system.
-It is called that because one of the factors that can control access is
-from what host the client is connecting.
-.PP
-Each database system contains a file named "pg_hba.conf", in its PGDATA
-directory, that controls who can connect to that database system.
-.PP
-The exact format of the pg_hba.conf file is described in the comments at
-the top of the sample file pg_hba.conf.sample, which resides in the
-Postgres "library" directory.
-
-.SH "SEE ALSO"
-introduction(1).
-
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/postgres.1,v 1.2 1996/09/26 16:49:09 momjian Exp $
-.TH POSTGRES95 UNIX 11/05/95 Postgres95 Postgres95
-.SH NAME
-postgres \(em the Postgres backend server
-.SH SYNOPSIS
-.BR "postgres"
-[\c
-.BR "-B"
-n_buffers]
-[\c
-.BR "-E"
-]
-[\c
-.BR "-F"
-]
-[\c
-.BR "-P"
-filedes]
-[\c
-.BR "-Q"
-]
-.br
-.in +5n
-[\c
-.BR "-d"
-debug_level]
-[\c
-.BR "-o"
-output_file]
-[\c
-.BR "-s"
-]
-[dbname]
-.in -5n
-.SH DESCRIPTION
-The Postgres backend server can be executed directly from the user shell.
-This should be done only while debugging by the DBA, and should not be
-done while other Postgres backends are being managed by a
-.IR postmaster
-on this set of databases.
-.PP
-The optional argument
-.IR dbname
-specifies the name of the database to be accessed.
-.IR Dbname
-defaults to the value of the
-.SM USER
-environment variable.
-.PP
-The
-.IR postgres
-server understands the following command-line options:
-.TP 5n
-.BR "-B" " n_buffers"
-If the backend is running under the
-.IR postmaster ,
-.IR "n_buffers"
-is the number of shared-memory buffers that the
-.IR "postmaster"
-has allocated for the backend server processes that it starts. If the
-backend is running standalone, this specifies the number of buffers to
-allocate. This value defaults to 64.
-.TP
-.BR "-E"
-Echo all queries.
-.TP
-.BR "-F"
-Disbable automatic fsync() call after each transaction.
-This option improves performance, but an operating system crash
-while a transaction is in progress will probably cause data loss.
-.TP
-.BR "-P" " filedes"
-.IR "filedes"
-specifies the file descriptor that corresponds to the socket (port) on
-which to communicate to the frontend process. This option is
-.BR not
-useful for interactive use.
-.TP
-.BR "-Q"
-Specifies \*(lqquiet\*(rq mode.
-.TP
-.BR "-d" " debug_level"
-Turns on debugging at the numeric level
-.IR "debug_level" .
-Turning on debugging will cause query parse trees and query plans to
-be displayed.
-.TP
-.BR "-o" " output_file"
-Sends all debugging and error output to
-.IR output_file .
-If the backend is running under the
-.IR postmaster ,
-error messages are still sent to the frontend process as well as to
-.IR output_file ,
-but debugging output is sent to the controlling tty of the
-.IR postmaster
-(since only one file descriptor can be sent to an actual file).
-.TP
-.BR "-s"
-Print time information and other statistics at the end of each query.
-This is useful for benchmarking or for use in tuning the number of
-buffers.
-.SH "DEPRECATED COMMAND OPTIONS"
-There are several other options that may be specified, used mainly
-for debugging purposes. These are listed here only for the use by
-Postgres system developers.
-.BR "Use of any of these options is highly discouraged" .
-Furthermore, any of these options may disappear or change at any time.
-.TP
-.BR "-A" "n|r|b|Q\fIn\fP|X\fIn\fP"
-.IP
-This option generates a tremendous amount of output.
-.TP
-.BR "-L"
-Turns off the locking system.
-.TP
-.BR "-N"
-Disables use of newline as a query delimiter.
-.TP
-.BR "-S"
-Indicates that the transaction system can run with the assumption of
-stable main memory, thereby avoiding the necessary flushing of data
-and log pages to disk at the end of each transaction system. This is
-only used for performance comparisons for stable vs. non-stable
-storage. Do not use this in other cases, as recovery after a system
-crash may be impossible when this option is specified in the absence
-of stable main memory.
-.TP
-.BR "-b"
-Enables generation of bushy query plan trees (as opposed to left-deep
-query plans trees). These query plans are not intended for actual
-execution; in addition, this flag often causes Postgres to run out of
-memory.
-.TP
-.BR "-f"
-Forbids the use of particular scan and join methods:
-.IR s " and " i
-disable sequential and index scans respectively, while
-.IR n ", " m " and " h
-disable nested-loop, merge and hash joins respectively.
-This is another feature that may not necessarily produce executable
-plans.
-.TP
-.BR "-p"
-Indicates to the backend server that it has been started by a
-.IR postmaster
-and make different assumptions about buffer pool management, file
-descriptors, etc.
-.TP
-.BR "-t" "pa[rser]|pl[anner]|e[xecutor]"
-Print timing statistics for each query relating to each of the major
-system modules. This option cannot be used with
-.BR "-s" .
-.SH "SEE ALSO"
-ipcclean(1),
-psql(1),
-postmaster(1).
-.SH "DIAGNOSTICS"
-Of the nigh-infinite number of error messages you may see when you
-execute the backend server directly, the most common will probably be:
-.TP
-.BR "semget: No space left on device"
-If you see this message, you should run the
-.IR ipcclean
-command. After doing this, try starting
-.IR postgres
-again. If this still doesn't work, you probably need to configure
-your kernel for shared memory and semaphores as described in the
-installation notes.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/postmaster.1,v 1.2 1996/10/03 23:34:36 momjian Exp $
-.TH POSTMASTER UNIX 11/05/95 Postgres95 Postgres95
-.SH "NAME"
-postmaster \(em run the Postgres postmaster
-.SH "SYNOPSIS"
-.BR "postmaster"
-[\c
-.BR "-B"
-n_buffers]
-[\c
-.BR "-D"
-data_dir]
-[\c
-.BR "-S" \c
-]
-[\c
-.BR "-a"
-system]
-.br
-.in +5n
-[\c
-.BR "-b"
-backend_pathname]
-[\c
-.BR "-d"
-[debug_level]]
-[\c
-.BR "-n" \c
-]
-.br
-[\c
-.BR "-o"
-backend_options]
-[\c
-.BR "-p"
-port]
-[\c
-.BR "-s" \c
-]
-.in -5n
-.SH "DESCRIPTION"
-The
-.IR "postmaster"
-manages the communication between frontend and backend processes, as
-well as allocating the shared buffer pool and semaphores (on machines
-without a test-and-set instruction). The
-.IR postmaster
-does not itself interact with the user and should be started as a
-background process.
-.BR "Only one postmaster should be run on a machine."
-.PP
-The
-.IR "postmaster"
-understands the following command-line options:
-.TP 5n
-.BR "-B" " n_buffers"
-.IR "n_buffers"
-is the number of shared-memory buffers for the
-.IR "postmaster"
-to allocate and manage for the backend server processes that it
-starts. This value defaults to 64.
-.TP
-.BR "-D" " data_dir"
-Specifies the directory to use as the root of the tree of database
-directories. This directory uses the value of the environment
-variable
-.SM PGDATA.
-If
-.SM PGDATA
-is not set, then the directory used is
-.SM $POSTGRESHOME\c
-/data. If neither environment variable is set and this command-line
-option is not specified, the default directory that was
-set at compile-time is used.
-.TP
-.BR "-S"
-Specifies that the
-.IR "postmaster"
-process should start up in silent mode. That is, it will disassociate
-from the user's (controlling) tty and start its own process group.
-This should not be used in combination with debugging options because
-any messages printed to standard output and standard error are
-discarded.
-.TP
-.BR "-a" " system"
-Specifies whether or not to use the authentication system
-.IR "system"
-(see
-.IR introduction (1))
-for frontend applications to use in connecting to the
-.IR postmaster
-process. Specify
-.IR "system"
-to enable a system, or
-.BI "no" "system"
-to disable a system. For example, to permit users to use
-.IR Kerberos
-authentication, use
-.BR "-a kerberos" ;
-to deny any unauthenticated
-connections, use
-.BR "-a nounauth .
-The default is site-specific.
-.TP
-.BR "-b" " backend_pathname"
-.IR "backend_pathname"
-is the full pathname of the Postgres backend server executable file that
-the
-.IR "postmaster"
-will invoke when it receives a connection from a frontend application.
-If this option is not used, then the
-.IR postmaster
-tries to find this executable file in the directory in which its own
-executable is located (this is done by looking at the pathname under
-which the
-.IR "postmaster"
-was invoked. If no pathname was specified, then the
-.SM PATH
-environment variable is searched for an executable named
-\*(lqpostgres\*(rq).
-.TP
-.BR "-d" " [debug_level]"
-The optional argument
-.IR debug_level
-determines the amount of debugging output the backend servers will
-produce.
-If
-.I debug_level
-is one, the postmaster will trace all connection traffic,
-and nothing else.
-For levels two and higher,
-debugging is turned on in the backend process and the postmaster
-displays more information,
-including the backend environment and process traffic.
-Note that if no file is specified for backend servers to
-send their debugging output then this output will appear on the
-controlling tty of their parent
-.IR postmaster .
-.TP
-.BR "-n" ", " "-s"
-The
-.IR "-s" " and " "-n"
-options control the behavior of the
-.IR "postmaster"
-when a backend dies abnormally. \fBNeither option is intended for use in
-ordinary operation\fP.
-.IP
-The ordinary strategy for this situation is to notify all other
-backends that they must terminate and then reinitialize the shared
-memory and semaphores. This is because an errant backend could have
-corrupted some shared state before terminating.
-.IP
-If the
-.IR "-s"
-option is supplied, then the
-.IR "postmaster"
-will stop all other backend processes by sending the signal
-.SM SIGSTOP,
-but will not cause them to terminate. This permits system programmers
-to collect core dumps from all backend processes by hand.
-.IP
-If the
-.IR "-n"
-option is supplied, then the
-.IR "postmaster"
-does not reinitialize shared data structures. A knowledgable system
-programmer can then use the
-.IR shmemdoc
-program to examine shared memory and semaphore state.
-.TP
-.BR "-o" " backend_options"
-The
-.IR postgres (1)
-options specified in
-.IR "backend_options"
-are passed to all backend server processes started by this
-.IR postmaster .
-If the option string contains any spaces, the entire string must be
-quoted.
-.TP
-.BR "-p" " port"
-Specifies the Internet TCP port on which the
-.IR postmaster
-is to listen for connections from frontend applications. Defaults to
-5432, or the value of the
-.SM PGPORT
-environment variable (if set). If you specify a port other than the
-default port then all frontend application users must specify the same
-port (using command-line options or
-.SM PGPORT\c
-) when starting any libpq application, including psql.
-.SH "WARNINGS"
-If at all possible,
-.BR "do not"
-use
-.SM SIGKILL
-when killing the
-.IR "postmaster" "."
-.SM SIGHUP,
-.SM SIGINT,
-or
-.SM SIGTERM
-(the default signal for
-.IR "kill" "(1))"
-should be used instead. Hence, avoid
-.nf
-kill -KILL
-.fi
-or its alternative form
-.nf
-kill -9
-.fi
-as this will prevent the
-.IR postmaster
-from freeing the system resources (e.g., shared memory and semaphores)
-that it holds before dying. This prevents you from having to deal with
-the problem with
-.IR shmat (2)
-described below.
-.SH "EXAMPLES"
-.nf
-
-# start postmaster using default values
-nohup postmaster >logfile 2>&1 &
-
-.fi
-This command will start up
-.IR "postmaster"
-on the default port (5432) and will search
-.SM $PATH
-to find an executable file called \*(lqpostgres\*(rq. This is the
-simplest and most common way to start the
-.IR "postmaster" .
-.nf
-
-# start with specific port and executable name
-nohup postmaster -p -b /usr/postgres/bin/postgres &
-
-.fi
-This command will start up a
-.IR "postmaster"
-communicating through the port 1234, and will attempt to use the
-backend located at \*(lq/usr/postgres/bin/postgres\*(rq. In order to
-connect to this
-.IR "postmaster"
-using psql, you would need to either
-specify
-.BR "-p 1234"
-on the
-.IR "psql"
-command-line or set the environment variable
-.SM PGPORT
-to 1234.
-.SH "SEE ALSO"
-ipcs(1),
-ipcrm(1),
-ipcclean(1),
-psql(1),
-postgres(1),
-.SH "DIAGNOSTICS"
-.TP
-.BR "FindBackend: could not find a backend to execute..."
-If you see this message, you do not have the
-.IR "postgres"
-executable in your path. Add the directoy in which postgres resides to
-your path.
-.TP
-.BR "semget: No space left on device"
-If you see this message, you should run the
-.IR "ipcclean"
-command. After doing this, try starting the
-.IR "postmaster"
-again. If this still doesn't work, you probably need to configure
-your kernel for shared memory and semaphores as described in the
-installation notes. If you run multiple
-.IR postmaster s
-on a single host, or have reduced the shared memory and semaphore
-parameters from the defaults in the generic kernel, you may have to
-go back and increase the shared memory and semaphores configured
-into your kernel.
-.TP
-.BR "StreamServerPort: cannot bind to port"
-If you see this message, you should be certain that there is no other
-.IR "postmaster"
-process already running. The easiest way to determine this is by
-using the command
-.nf
-ps -ax | grep postmaster
-.fi
-on BSD-based systems
-.nf
-ps -e | grep postmast
-.fi
-(the equivalent syntax is on System V-like or POSIX-compliant systems such as HP-UX). If you
-are sure that no other
-.IR "postmaster"
-processes are running and you still get this error, try specifying a
-different port using the
-.BR "-p"
-option. You may also get this error if you terminate the
-.IR "postmaster"
-and immediately restart it using the same port; in this case, you must
-simply wait a few seconds until the operating system closes the port
-before trying again. Finally, you may get this error if you specify
-a port number that your operating system considers to be reserved.
-For example, many versions of Unix consider port numbers under 1024 to
-be \*(lqtrusted\*(rq and only permit the Unix superuser to access them.
-.TP
-.BR "IpcMemoryAttach: shmat() failed: Permission denied"
-A likely explanation is that another user attempted to start a
-.IR "postmaster"
-process on the same port which acquired shared resources and then
-died. Since Postgres shared memory keys are based on the port number
-assigned to the
-.IR "postmaster" ,
-such conflicts are likely if there is more than one installation on
-a single host. If there are no other
-.IR "postmaster"
-processes currently running (see above), run
-.IR "ipcclean"
-and try again. If other
-.IR "postmaster" s
-are running, you will have to find the owners of those processes to
-coordinate the assignment of port numbers and/or removal of unused
-shared memory segments.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/psql.1,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
-.TH PSQL UNIX 1/20/96 Postgres95 Postgres95
-.SH NAME
-psql \(em run the interactive query front-end
-.SH SYNOPSIS
-.BR psql
-[\c
-.BR "-a"
-authsvc
-]
-[\c
-.BR "-A"
-]
-[\c
-.BR "-c"
-query
-]
-[\c
-.BR "-d"
-dbName]
-[\c
-.BR "-e"
-]
-[\c
-.BR "-f"
-filename]
-[\c
-.BR "-h"
-hostname]
-[\c
-.BR "-H"
-]
-[\c
-.BR "-l"
-port]
-[\c
-.BR "-n"
-]
-[\c
-.BR "-o"
-filename
-]
-[\c
-.BR "-p"
-port]
-[\c
-.BR "-q"
-]
-[\c
-.BR "-s"
-]
-[\c
-.BR "-S"
-]
-[\c
-.BR "-t"
-]
-[\c
-.BR "-x"
-]
-[dbname]
-.in -5n
-.SH DESCRIPTION
-psql is a interactive query front-end to Postgres. It enables you to
-type in queries interactively, issue them to Postgres, and see the query
-results.
-.IR psql
-can be used in a pipe sequence, and automatically detects when it
-is not listening or talking to a real tty.
-.IR psql
-is designed to be an enhanced version of the older
-.IR "monitor"
-program.
-.PP
-.IR "psql"
-is a frontend application, like any other. Hence, a
-.IR "postmaster"
-process must be running on the database server host before
-.IR "psql"
-is executed. In addition, the correct
-.IR "postmaster"
-port number must be specified
-as described below.
-.PP
-The optional argument
-.IR dbname
-specifies the name of the database to be accessed. This database must
-already have been created.
-.IR dbname
-defaults to the value of the
-.SM USER
-environment variable or, if that's not set, to the Unix account name of the
-current user.
-.PP
-.IR "psql"
-understands the following command-line options:
-.TP
-.BR "-a" " system"
-Specifies an authentication system
-.IR "system"
-(see
-.IR introduction (1))
-to use in connecting to the
-.IR postmaster
-process. The default is site-specific.
-.TP
-.BR "-A"
-Turn off fill justification when printing out attributes.
-.TP
-.BR "-c" " query"
-Specifies that
-.IR "psql"
-is to execute one query string,
-.IR "query" ,
-and then exit. This is useful for shell scripts, typically in
-conjunction with the
-.BR -q ""
-options.
-.BR -c
-option in shell scripts.
-.TP
-.BR "-d" " dbName"
-Specifies the name of the database to connect to.
-.TP
-.BR "-e" " "
-Echo the query sent to the backend
-.TP
-.BR "-f" " filename"
-Use the file
-.IR "filename"
-as the source of queries instead of reading queries interactively.
-.TP
-.BR "-h" " hostname"
-Specifies the hostname of the machine on which the
-.IR postmaster
-is running. Defaults to the name of the local host, or the value of
-the
-.SM PGHOST
-environment variable (if set).
-.TP
-.BR "-H"
-Turns on
-.SM HTML3.0
-tabular output.
-.TP
-.BR "-l"
-Lists all available databases
-.TP
-.BR "-n"
-Do not use the readline library for input line editing and command history.
-.TP
-.BR "-p" " port"
-Specifies the Internet TCP port on which the
-.IR postmaster
-is listening for connections. Defaults to 5432, or the value of the
-.SM PGPORT
-environment variable (if set).
-.TP
-.BR "-q"
-Specifies that
-.IR psql
-should do its work quietly. By default, it
-prints welcome and exit messages and prompts for each query, and prints
-out the number of rows returned from a query.
-If this option is used, none of this happens. This is useful with the
-.BR -c
-option in shell scripts.
-.TP
-.BR "-s"
-Run in single-step mode where the user at prompted for each query before
-it is sent to the backend.
-.TP
-.BR "-S"
-Run ins single-line mode where each query is terminated by a newline,
-instead of a semicolon.
-.TP
-.BR "-t"
-Turn off printing of attributes names.
-This is useful with the
-.BR -c
-option in shell scripts.
-.TP
-.BR "-x"
-Turns on extended field mode. When enabled each tuple will have its field
-names printed on the left with the field values printed on the right.
-This is useful for tuples which are otherwise too long to fit into
-one screen line. HTML tuple output supports this mode also.
-.PP
-You may set environment variables to avoid typing some of the above
-options. See the
-.SM "ENVIRONMENT VARIABLES"
-section below.
-.SH "CONNECTING TO A DATABASE"
-.IR psql
-attempts to make a connection to the database at the hostname and
-port number specified on the command line. If the connection could not
-be made for any reason (e.g. insufficient privileges, postmaster is not
-running on the server, etc)
-.IR psql
-will return an error that says
-.nf
-Connection to database failed.
-.fi
-The reason for the connection failure is not provided.
-.SH "ENTERING QUERIES"
-In normal operation, psql provides a prompt with the name of the
-database that psql is current connected to followed by the string "=>".
-For example,
-.nf
-Welcome to the POSTGRES95 interactive sql monitor:
- Please read the file COPYRIGHT for copyright terms of POSTGRES95
-
- type \e? for help on slash commands
- type \eq to quit
- type \eg or terminate with semicolon to execute query
- You are currently connected to the database: testdb
-
-testdb=>
-.fi
-.PP
-At the prompt, the user may type in SQL queries. Unless the -S option
-is set, input lines are sent to the backend when a query-terminating
-semicolon is reached.
-.PP
-Whenever a query is executed, psql also polls for asynchronous notification
-events generated by
-.IR listen (l)
-and
-.IR notify (l).
-.PP
-.SH "PSQL COMMANDS"
-.IP "\ea"
-Toggle field alignment when printing out attributes.
-.IP "\eC \fIcaption\fR"
-Set the HTML3.0 table caption.
-.IP "\ec \fIdbname\fR"
-Establish a connection to a new database. The previous connection is closed.
-.IP "\ed [\fItable\fR]"
-List tables in the database, or if
-.IR table
-is specified, list the columns in
-.IR table.
-If table name is
-.IR *,
-list all tables and column information for each tables.
-.IP "\ee [\fIfilename\fR]"
-Edit the current query buffer or \fIfile\fR.
-.IP "\eE [\fIfilename\fR]"
-Edit the current query buffer or \fIfile\fR and execute it
-upon editor exit.
-.IP "\ef [\fIseparator\fR]"
-Set the field separator. Default is a single blank space.
-.IP "\eg [\fI|command\fR] | [\fIfilename\fR]"
-Send the current query input buffer to the backend and optionally
-save the output in
-.IR filename
-or pipe the output into
-.IR "|command".
-.IP "\eh [\fIcommand\fR]"
-Give syntax help on the specified SQL command. If the
-.IR command
-is not specified, list all the commands for which syntax help is
-available. If the
-.IR command
-is
-.IR *,
-give syntax help on all SQL commands.
-.IP "\eH"
-Toggle html3 output.
-.IP "\ei \fIfilename\fR"
-Read queries from
-.IR filename
-into the query input buffer.
-.IP "\el"
-List all the databases in the server.
-.IP "\em"
-Toggle monitor-like table display.
-This is standard SQL output (i.e extra border characters).
-.IP "\eo [\fI|command\fR] | [\fIfilename\fR]"
-Send query results to
-.IR filename .
-Or pipe into
-.IR command .
-If no arguments are specified, send query results to
-.IR stdout .
-.IP "\ep"
-Print the current query buffer.
-.IP \eq
-Quit the psql program.
-.IP "\er"
-Reset(clear) the query buffer.
-.IP "\es [\fIfilename\fR]"
-Print or save the command line history to \fIfilename\fR. (Only available if psql is
-configured to use readline)
-.IP "\et"
-Toggle display of output attribute name headings and row count (defaults to on).
-.IP "\eT"
-Set html3.0 <table ...> options.
-.IP "\ex"
-Toggles extended field mode. When enabled each tuple will have its field
-names printed on the left with the field values printed on the right.
-This is useful for tuples which are otherwise too long to fit into
-one screen line. HTML tuple output mode supports this flag too.
-.IP "\e! [\fIcommand\fR]"
-Escape to shell or execute
-.IR command.
-.IP \e?
-Get help information about the \e commands.
-.SH "ENVIRONMENT VARIABLES"
-You may set any of the following environment variables to avoid
-specifying command-line options:
-.nf
-hostname: PGHOST
-port: PGPORT
-tty: PGTTY
-options: PGOPTION
-realm: PGREALM
-.fi
-.PP
-If
-.SM PGOPTION
-is specified, then the options it contains are parsed
-.BR before
-any command-line options.
-.PP
-.SM PGREALM
-only applies if
-.IR Kerberos
-authentication is in use. If this environment variable is set, Postgres
-will attempt authentication with servers for this realm and use
-separate ticket files to avoid conflicts with local ticket files. See
-.IR introduction (1)
-for additional information on
-.IR Kerberos .
-.PP
-See
-.IR introduction (libpq)
-for additional details.
-.SH "RETURN VALUE"
-When executed with the
-.BR "-c"
-option,
-.IR psql
-returns 0 to the shell on successful query completion, 1 otherwise.
-.IR psql
-will also return 1 if the connection to a database could not be made for
-any reason.
-.SH "SEE ALSO"
-introduction(libpq),
-monitor(1)
-postgres(1),
-postmaster(1).
-.SH BUGS
-If multiple queries are sent to the backend at once without semicolon
-termination after each query, psql gets confused about the query
-results. The queries will still be processed correctly by the backend.
-
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.TH PURGE SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-purge \(em discard historical data
-.SH SYNOPSIS
-.nf
-\fBpurge\fR classname [ \fBbefore\fR abstime ] [ \fBafter\fR reltime ]
-.fi
-.SH DESCRIPTION
-.BR Purge
-allows a user to specify the historical retention properties of a
-class. If the date specified is an absolute time such as \*(lqJan 1
-1987\*(rq, Postgres will discard tuples whose validity expired before
-the indicated time.
-.BR Purge
-with no
-.IR before
-clause is equivalent to \*(lqpurge before now\*(rq. Until specified
-with a purge command, instance preservation defaults to
-\*(lqforever\*(rq.
-.PP
-The user may purge a class at any time as long as the purge date never
-decreases. Postgres will enforce this restriction, silently.
-.PP
-Note that the
-.BR purge
-command does not do anything except set a parameter for system
-operation. Use
-.IR vacuum (l)
-to enforce this parameter.
-.SH EXAMPLE
-.nf
---
---Always discard data in the EMP class
---prior to January 1, 1989
---
-purge EMP before "Jan 1 1989"
-.fi
-.nf
---
---Retain only the current data in EMP
---
-purge EMP
-.fi
-.SH "SEE ALSO"
-vacuum(l).
-.SH "BUGS AND CAVEATS"
-Error messages are quite unhelpful. A complaint about
-\*(lqinconsistent times\*(rq followed by several nine-digit numbers
-indicates an attempt to \*(lqback up\*(rq a purge date on a relation.
-.PP
-You cannot purge certain system catalogs (namely, \*(lqpg_class\*(rq,
-\*(lqpg_attribute\*(rq, \*(lqpg_am\*(rq, and \*(lqpg_amop\*(rq) due
-to circularities in the system catalog code.
-.PP
-This definition of the
-.BR purge
-command is really only useful for non-archived relations, since
-tuples will not be discarded from archive relations (they are
-never vacuumed).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/remove_view.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
-.TH "DROP VIEW" SQL 04/25/94 Postgres95 Postgres95
-.SH NAME
-drop view \(em removes a view from Postgres
-.SH SYNOPSIS
-.nf
-\fBdrop view\fR view_name
-.fi
-.SH DESCRIPTION
-This command drops an existing view from the Postgres system. To
-execute this command you must be the owner of the view.
-.SH EXAMPLE
-.nf
-/*
- * this command will remove the "myview" view
- */
-drop view myview
-.fi
-.SH "SEE ALSO"
-create view(l),
-drop rule(l),
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/rename.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
-.TH RENAME SQL 02/08/94 Postgres95 Postgres95
-.SH NAME
-rename \(em rename a class or an attribute in a class
-.SH SYNOPSIS
-.nf
-\fBalter table\fR classname1
- \fBrename to\fR classname2
-\fBalter table\fR classname1 [\fB*\fR]
- \fBrename [column]\fR attname1 \fBto\fR attname2
-.fi
-.SH DESCRIPTION
-The
-.BR rename
-command
-causes the name of a class or attribute to change without changing any
-of the data contained in the affected class. Thus, the class or
-attribute will remain of the same type and size after this command is
-executed.
-.PP
-In order to rename an attribute in each class in an entire inheritance
-hierarchy, use the
-.IR classname
-of the superclass and append a \*(lq*\*(rq. (By default, the attribute
-will not be renamed in any of the subclasses.) This should
-.BR always
-be done when changing an attribute name in a superclass. If it is
-not, queries on the inheritance hierarchy such as
-.nf
-select * from super* s
-.fi
-will not work because the subclasses will be (in effect) missing an
-attribute found in the superclass.
-.PP
-You must own the class being modified in order to rename it or part of
-its schema. Renaming any part of the schema of a system catalog is
-not permitted.
-.SH EXAMPLE
-.nf
---
--- change the emp class to personnel
---
-alter table emp rename to personnel
-.fi
-.nf
---
--- change the sports attribute to hobbies
---
-alter table emp rename column sports to hobbies
-.fi
-.nf
---
--- make a change to an inherited attribute
---
-alter table person * rename column last_name to family_name
-.fi
-.SH BUGS
-Execution of historical queries using classes and attributes whose
-names have changed will produce incorrect results in many situations.
-.PP
-Renaming of types, operators, rules, etc., should also be supported.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/revoke.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
-.TH REVOKE SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-revoke \(em revoke access privileges
-.SH SYNOPSIS
-.nf
-\fBrevoke\fR <privilege[,privilege,...]>
- \fBon\fR <rel1>[,...<reln>]
- \fBfrom\fR [\fBpublic\fR | group <group> | <username>]
-
- \fBprivilege\fR is {\fBALL\fR | \fBSELECT\fR | \fBINSERT\fR | \fBUPDATE\fR | \fBDELETE\fR | \fBRULE\fR}
-.fi
-.SH DESCRIPTION
-.PP
-.B revoke
-allows you to revoke privileges given to all users or certain users or groups.
-.SH EXAMPLES
-.nf
---
---Example of a revoke
---
-revoke insert
- on mytab
- from public
-.fi
-.SH "SEE ALSO"
-grant(l)
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/rollback.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
-.TH ROLLBACK SQL 01/20/96 Postgres95 Postgres95
-.\" XXX This .XA has to go after the .TH so that the index page number goes
-.\" in the right place...
-.SH NAME
-rollback \(em rollback, e.g. aborts, the current transaction
-.SH SYNOPSIS
-.nf
-\fBrollback\fP \fB[transaction|work]\fR
-.fi
-.SH DESCRIPTION
-This command rolls back the current transaction and causes all the
-updates made by the transaction to be discarded.
-.PP
-.IR "rollback"
-is functionally equivalent to the
-.IR "abort"
-command.
-.SH "SEE ALSO"
-abort(l),
-begin(l),
-end(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/select.l,v 1.2 1996/10/07 02:34:53 momjian Exp $
-.TH SELECT SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-select \(em retrieve instances from a class
-.SH SYNOPSIS
-.nf
-\fBselect\fR [distinct]
- expression1 [\fBas\fR attr_name-1]
- {, expression-1 [\fBas\fR attr_name-i]}
- [\fBinto\fR \fBtable\fR classname]
- [\fBfrom\fR from-list]
- [\fBwhere\fR where-clause]
- [\fBgroup by\fR attr_name1 {, attr_name-i....}
- [\fBorder by\fR attr_name1
- [\fBusing op1\fR] {, attr_namei [\fBusing opi\fR] }
-.fi
-.SH DESCRIPTION
-.BR Select
-will get all instances which satisfy the qualification,
-.IR qual ,
-compute the value of each element in the target list, and either (1)
-return them to an application program through one of two different
-kinds of portals or (2) store them in a new class.
-.PP
-If
-into table class name
-is specified, the result of the query will be stored in a new class
-with the indicated name.
-.PP
-The
-.BR "order by"
-clause allows a user to specify that he wishes the instances sorted
-according to the corresponding operator. This operator must be a
-binary one returning a boolean. Multiple sort fields are allowed and
-are applied from left to right.
-.PP
-The target list specifies the fields to be retrieved. Each
-.IR attr_name
-specifies the desired attribute or portion of an array attribute.
-Thus, each
-.IR attr_name
-takes the form
-.nf
-class_name.att_name
-.fi
-or, if the user only desires part of an array,
-.nf
---
---Specify a lower and upper index for each dimension
---(i.e., clip a range of array elements)
---
-class_name.att_name[lIndex-1:uIndex-1]..[lIndex-i:uIndex-i]
-
---
---Specify an exact array element
---
-class_name.att_name[uIndex-1]..[uIndex-i]
-.fi
-where each
-.IR lIndex
-or
-.IR uIndex
-is an integer constant.
-.PP
-When you retrieve an attribute which is of a complex type, the behavior
-of the system depends on whether you used "nested dots" to project
-out attributes of the complex type or not. See the examples below.
-.PP
-You must have read access to a class to read its values (see
-.IR "grant/revoke" (l).
-.SH EXAMPLES
-.nf
---
---Find all employees who make more than their manager
---
-select e.name
- from emp e, emp m
- where e.mgr = m.name
- and e.sal > m.sal
-.fi
-.nf
---
---Retrieve all fields for those employees who make
---more than the average salary
---
-select avg(sal) as ave
- into table avgsal from emp;
-.fi
-.nf
---
---Retrieve all employee names in sorted order
---
-select distinct name
- from emp
- order by name using <
-.fi
-.nf
---
---Retrieve all employee names that were valid on 1/7/85
---in sorted order
---
-selec name
- from emp['January 7 1985'] e
- order by name using <
-.fi
-.nf
---
---Construct a new class, raise, containing 1.1
---times all employee's salaries
---
-select 1.1 * emp.salary as salary
- into tables raise
- from emp
-.fi
-.SH "SEE ALSO"
-insert(l),
-close(l),
-create table(l),
-fetch(l),
-update(l).
-.SH BUGS
-.BR "Select into"
-does not delete duplicates.
-.PP
-If the backend crashes in the course of executing a
-.BR "select into" ,
-the class file will remain on disk. It can be safely removed by the
-database DBA, but a subsequent
-.BR "select into"
-to the same name will fail with a cryptic error message about
-\*(lqBlockExtend\*(rq.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/sql.l,v 1.1.1.1 1996/08/18 22:14:28 scrappy Exp $
-.TH INTRODUCTION SQL 11/5/95 Postgres95 Postgres95
-.SH "Section 4 \(em SQL Commands (COMMANDS)"
-.SH "General Information"
-.SH DESCRIPTION
-The following is a description of the general syntax of SQL.
-Individual SQL statements and commands are treated separately in the
-document; this section describes the syntactic classes from which the
-constituent parts of SQL statements are drawn.
-.SH Comments
-A
-.IR comment
-is an arbitrary sequence of characters following double dashes up to the end
-of the line e.g:
-.nf
--- This is a comment
-.fi
-.SH "Names"
-.IR Names
-in SQL are sequences of not more than NAMEDATALEN alphanumeric characters,
-starting with an alphabetic character. By default, NAMEDATALEN is set
-to 16, but at the time the system is built, NAMEDATALEN can be changed
-by changing the #ifdef in src/backend/include/postgres.h. Underscore
-(\*(lq_\*(rq) is considered an alphabetic character.
-.SH "Keywords"
-The following identifiers are reserved for use as
-.IR keywords
-and may not be used otherwise:
-.PP
-.ft B
-.nf
-.if n .ta 5 +15 +15 +15
-.if t .ta 0.5i +1.5i +1.5i +1.5i
-.fi
-.ft
-.ft B
-.nf
-.if n .ta 5 +15 +15 +15
-.if t .ta 0.5i +1.5i +1.5i +1.5i
-.fi
-.ft
-.PP
-In addition, all Postgres classes have several predefined attributes used
-by the system.
-.SH "Constants"
-There are six types of
-.IR constants
-for use in SQL. They are described below.
-.SH "String Constants"
-.IR Strings
-in SQL are arbitrary sequences of ASCII characters bounded by single
-quotes (' '). Uppercase alphabetics within strings are accepted
-literally. Non-printing characters may be embedded within strings by
-prepending them with a backslash, e.g., `\en'. Also, in order to embed
-quotes within strings, it is necessary to prefix them with `\e' . The
-same convention applies to `\e' itself. Because of the limitations on
-instance sizes, string constants are currently limited to a length of
-a little less than 8192 bytes. Larger objects may be created using the
-Postgres Large Object interface.
-.SH "Integer Constants"
-.IR "Integer constants"
-in SQL are collection of ASCII digits with no decimal point. Legal
-values range from \(mi2147483647 to +2147483647. This will vary
-depending on the operating system and host machine.
-.SH "Floating Point Constants"
-.IR "Floating point constants"
-consist of an integer part, a decimal point, and a fraction part or
-scientific notation of the following format:
-.nf
-{<dig>} .{<dig>} [e [+-] {<dig>}]
-.fi
-Where <dig> is a digit. You must include at least one <dig> after the
-period and after the [+-] if you use those options. An exponent with
-a missing mantissa has a mantissa of 1 inserted. There may be no
-extra characters embedded in the string.
-Floating point constaints are of type float4.
-.SH "Constants of Postgres User-Defined Types"
-A constant of an
-.IR arbitrary
-type can be entered using the notation:
-.nf
-'string'::type-name
-.fi
-or
-.nf
-CAST 'string' AS type-name
-.fi
-The value inside the string is passed to the input
-conversion routine for the type called type-name. The result is a
-constant of the indicated type. The explicit typecast may be omitted
-if there is no ambiguity as to the type the constant must be, in which
-case it is automatically coerced.
-.SH "Array constants"
-.IR "Array constants"
-are arrays of any Postgres type, including other arrays, string
-constants, etc. The general format of an array constant is the
-following:
-.nf
-{<val1><delim><val2><delim>}
-.fi
-Where
-.IR "<delim>"
-is the delimiter for the type stored in the \*(lqpg_type\*(rq class.
-(For built-in types, this is the comma character, \*(lq,\*(rq.) An
-example of an array constant is
-.nf
-{{1,2,3},{4,5,6},{7,8,9}}
-.fi
-This constant is a two-dimensional, 3 by 3 array consisting of three
-sub-arrays of integers.
-.PP
-Individual array elements can and should be placed between quotation
-marks whenever possible to avoid ambiguity problems with respect to
-leading white space.
-.\" Elements of single-element arrays (e.g.,
-.\" \*(lq{"1"}\*(rq) must be quoted.
-.PP
-.SH "FIELDS AND COLUMNS"
-.SH "Fields"
-A
-.IR field
-is either an attribute of a given class or one of the following:
-.nf
-oid
-tmin
-tmax
-xmin
-xmax
-cmin
-cmax
-.fi
-.PP
-.IR Oid
-stands for the unique identifier of an instance which is added by
-Postgres to all instances automatically. Oids are not reused and are 32
-bit quantities.
-.PP
-.IR "Tmin, tmax, xmin, cmin, xmax"
-and
-.IR cmax
-stand respectively for the time that the instance was inserted, the
-time the instance was deleted, the identity of the inserting
-transaction, the command identifier within the transaction, the
-identity of the deleting transaction and its associated deleting
-command. For further information on these fields consult [STON87].
-Times are represented internally as instances of the \*(lqabstime\*(rq
-data type. Transaction identifiers are 32 bit quantities which are
-assigned sequentially starting at 512. Command identifiers are 16 bit
-objects; hence, it is an error to have more than 65535 SQL commands
-within one transaction.
-.SH "Columns"
-A
-.IR column
-is a construct of the form:
-.nf
-Instance-variable{.composite_field}.field `['number`]'
-.fi
-.IR Instance-variable
-identifies a particular class and can be thought of as standing for
-the instances of that class. An instance variable is either a class
-name, a surrogate for a class defined by means of a
-.IR from
-clause, or the keyword
-.BR new
-or
-.BR current.
-New and current can only appear in the action portion of a rule, while
-other instance variables can be used in any SQL statement.
-.IR Composite_field
-is a field of of one of the Postgres composite types indicated in the
-.IR information (l)
-section, while successive composite fields address attributes in the
-class(s) to which the composite field evaluates. Lastly,
-.IR field
-is a normal (base type) field in the class(s) last addressed. If
-.IR field
-is of type array, then the optional
-.IR number
-designator indicates a specific element in the array. If no number is
-indicated, then all array elements are returned.
-.SH "Operators"
-Any built-in system, or user-defined operator may be used in SQL.
-For the list of built-in and system operators consult
-.BR "introduction" "(3)."
-For a list of user-defined operators consult your system administrator
-or run a query on the pg_operator class. Parentheses may be used for
-arbitrary grouping of operators.
-.SH "Expressions (a_expr)"
-An
-.IR expression
-is one of the following:
-.nf
-( a_expr )
-constant
-attribute
-a_expr binary_operator a_expr
-a_expr right_unary_operator
-left_unary_operator a_expr
-parameter
-functional expressions
-aggregate expressions
-.fi
-We have already discussed constants and attributes. The two kinds of
-operator expressions indicate respectively binary and left_unary
-expressions. The following sections discuss the remaining options.
-.SH "Parameters"
-A
-.IR parameter
-is used to indicate a parameter in a SQL function. Typically this
-is used in SQL function definition statement. The form of a
-parameter is:
-.nf
-\'$' number
-.fi
-For example, consider the definition of a function, DEPT, as
-.nf
-create function DEPT (char16)
- returns dept
- as 'select * from
- dept where name=$1'
- language 'sql'
-.fi
-.SH "Functional Expressions"
-A
-.IR "functional expression"
-is the name of a legal SQL function, followed by its argument list
-enclosed in parentheses, e.g.:
-.nf
-fn-name (a_expr{ , a_expr})
-.fi
-For example, the following computes the square root of an employee
-salary.
-.nf
-sqrt(emp.salary)
-.fi
-.SH "Aggregate Expression"
-An
-.IR "aggregate expression"
-represents a simple aggregate (i.e., one that computes a single value)
-or an aggregate function (i.e., one that computes a set of values).
-The syntax is the following:
-.nf
-aggregate.name (attribute)
-.fi
-Here,
-.IR aggregate_name
-must be a previously defined aggregate.
-.SH "Target_list"
-A
-.IR "target list"
-is a parenthesized, comma-separated list of one or more elements, each
-of which must be of the form:
-.nf
-a_expr[AS result_attname]
-.fi
-Here, result_attname is the name of the attribute to be created (or an
-already existing attribute name in the case of update statements.) If
-.IR result_attname
-is not present, then
-.IR a_expr
-must contain only one attribute name which is assumed to be the name
-of the result field. In Postgres default naming is only used if
-.IR a_expr
-is an attribute.
-.SH\82\82 "Qualification"
-A
-.IR qualification
-consists of any number of clauses connected by the logical operators:
-.nf
-not
-and
-or
-.fi
-A clause is an
-.IR a_expr
-that evaluates to a Boolean over a set of instances.
-.SH "From List"
-The
-.IR "from list"
-is a comma-separated list of
-.IR "from expressions" .
-.PP
-Each
-.IR "from expression"
-is of the form:
-.nf
-[class_reference] instance_variable
- {, [class_ref] instance_variable...}
-.fi
-where
-.IR class_reference
-is of the form
-.nf
-class_name [time_expression] [*]
-.fi
-The
-.IR "from expression"
-defines one or more instance variables to range over the class
-indicated in
-.IR class_reference .
-Adding a
-.IR time_expression
-will indicate that a historical class is desired. One can also request
-the instance variable to range over all classes that are beneath the
-indicated class in the inheritance hierarchy by postpending the
-designator \*(lq*\*(rq.
-.SH\82\82 "Time Expressions"
-A
-.IR "time expression"
-is in one of two forms:
-.nf
- ['date']
- ['date-1', 'date-2']
-.fi
-The first case requires instances that are valid at the indicated
-time. The second case requires instances that are valid at some time
-within the date range specified. If no time expression is indicated,
-the default is \*(lqnow\*(rq.
-.PP
-In each case, the date is a character string of the form
-.nf
-[MON-FRI] 'MMM DD [HH:MM:SS] YYYY' [Timezone]
-.fi
-where MMM is the month (Jan \- Dec), DD is a legal day number in the
-specified month, HH:MM:SS is an optional time in that day (24-hour
-clock), and YYYY is the year. If the time of day HH:MM:SS is not
-specified, it defaults to midnight at the start of the specified day.
-As of Version 3.0, times are no longer read and written using
-Greenwich Mean Time; the input and output routines default to the
-local time zone.
-.PP
-For example,
-.nf
-['Jan 1 1990']
-['Mar 3 00:00:00 1980', 'Mar 3 23:59:59 1981r']
-.fi
-are valid time specifications.
-.PP
-Note that this syntax is slightly different than that used by the
-time-range type.
-.SH "SEE ALSO"
-insert(l),
-delete(l),
-execute(l),
-update(l),
-select(l),
-monitor(1).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/unix.1,v 1.1.1.1 1996/08/18 22:14:28 scrappy Exp $
-.TH INTRODUCTION UNIX 11/05/95 Postgres95 Postgres95
-.SP INFORMATION UNIX 11/05/95
-.BH "SECTION 2 \(em Unix COMMANDS (Unix)"
-.SH "OVERVIEW"
-This section outlines the interaction between Postgres and
-the operating system. In particular, this section describes
-the Postgres support programs that are executable as Unix
-commands.
-.SH TERMINOLOGY
-In the following documentation, the term
-.IR site
-may be interpreted as the host machine on which Postgres is installed.
-Since it is possible to install more than one set of Postgres
-databases on a single host, this term more precisely denotes any
-particular set of installed Postgres binaries and databases.
-.PP
-The
-.IR "Postgres super-user"
-is the user named \*(lqpostgres\*(rq who owns the Postgres
-binaries and database files. As the database super-user, all
-protection mechanisms may be bypassed and any data accessed
-arbitrarily. In addition, the Postgres super-user is allowed to execute
-some support programs which are generally not available to all users.
-Note that the Postgres super-user is
-.IR not
-the same as the Unix super-user,
-.IR root ,
-and should have a non-zero userid for security reasons.
-.PP
-The
-.IR "database base administrator"
-or DBA, is the person who is responsible for installing Postgres to
-enforce a security policy for a site. The DBA can add new users by
-the method described below
-and maintain a set of template databases for use by
-.IR createdb (1).
-.PP
-The
-.IR postmaster
-is the process that acts as a clearing-house for requests to the Postgres
-system.
-Frontend applications connect to the
-.IR postmaster ,
-which keeps tracks of any system errors and communication between the
-backend processes. The
-.IR postmaster
-can take several command-line arguments to tune its behavior.
-However,
-supplying arguments is necessary only if you intend to run multiple
-sites or a non-default site. See
-.IR postmaster (1)
-for details.
-.PP
-The
-.IR "Postgres backend"
-(the actual executable program called "postgres") may be executed
-directly from the user shell by the
-Postgres super-user (with the database name as an argument). However,
-doing this bypasses the shared buffer pool and lock table associated
-with a postmaster/site, therefore this is not recommended in a multiuser
-site.
-.SH NOTATION
-\*(lq.../\*(rq at the front of a file name is used to represent the
-path to the Postgres super-user's home directory. Anything in brackets
-(\*(lq[\*(rq and \*(lq]\*(rq) is optional. Anything in braces
-(\*(lq{\*(rq and \*(lq}\*(rq) can be repeated 0 or more times.
-Parentheses (\*(lq(\*(rq and \*(lq)\*(rq ) are used to group boolean
-expressions. \*(lq|\*(rq is the boolean operator
-.SM OR .
-.SH "USING Postgres FROM Unix"
-All Postgres commands that are executed directly from a Unix shell are
-found in the directory \*(lq.../bin\*(rq. Including this directory in
-your search path will make executing the commands easier.
-.PP
-A collection of system catalogs exist at each site. These include a
-class (\*(lqpg_user\*(rq) that contains an instance for each valid
-Postgres user. The instance specifies a set of Postgres privileges, such as
-the ability to act as Postgres super-user, the ability to create/destroy
-databases, and the ability to update the system catalogs. A Unix
-user cannot do anything with Postgres until an appropriate instance is
-installed in this class. Further information on the system catalogs
-is available by running queries on the appropriate classes.
-.SH "Security"
-.SP SECURITY UNIX 03/12/94
-.SH "USER AUTHENTICATION"
-.IR Authentication
-is the process by which the backend server and
-.IR postmaster
-ensure that the user requesting access to data is in fact who he/she
-claims to be. All users who invoke Postgres are checked against the
-contents of the \*(lqpg_user\*(rq class to ensure that they are
-authorized to do so. However, verification of the user's actual
-identity is performed in a variety of ways.
-.SS "From the user shell"
-A backend server started from a user shell notes the user's (effective)
-user-id before performing a
-.IR setuid (3)
-to the user-id of user \*(lqpostgres\*(rq. The effective user-id is used
-as the basis for access control checks. No other authentication is
-conducted.
-.SS "From the network"
-If the Postgres system is built as distributed, access to the Internet
-TCP port of the
-.IR postmaster
-process is available to anyone. However, Postgres offers optional
-host-based authentication where only access from certain hosts are
-allowed. Of course, host-based authentication is not fool-proof in
-Unix, either. It is possible for determined intruders to also
-masquerade the origination host. Those security issues are beyond the
-scope of Postgres.
-.PP
-If greater security is desired, Postgres and its clients may be
-modified to use a network authentication system. For example, the
-.IR postmaster ,
-.IR psql
-and the
-.IR libpq
-library have already been configured to use either Version 4 or Version 5 of
-the
-.IR Kerberos
-authentication system from the Massachusetts Institute of Technology.
-For more information on using
-.IR Kerberos
-with Postgres, see the appendix below.
-.SH "ACCESS CONTROL"
-Postgres provides mechanisms to allow users to limit the access to
-their data that is provided to other users.
-.SS "Database superusers"
-Database super-users (i.e., users who have \*(lqpg_user.usesuper\*(rq
-set) silently bypass all of the access controls described below with
-two exceptions: manual system catalog updates are not permitted if the
-user does not have \*(lqpg_user.usecatupd\*(rq set, and destruction of
-system catalogs (or modification of their schemas) is never allowed.
-.SS "Access Privilege
-The use of access privilege to limit reading, writing and setting
-of rules on classes is covered in
-.IR "grant/revoke" (l).
-.SS "Class removal and schema modification"
-Commands that destroy or modify the structure of an existing class,
-such as
-.IR "alter" ,
-.IR "drop table" ,
-and
-.IR "drop index" ,
-only operate for the owner of the class. As mentioned above, these
-operations are
-.BR never
-permitted on system catalogs.
-.SH "FUNCTIONS AND RULES"
-Functions and rules allow users to insert code into the backend server
-that other users may execute without knowing it. Hence, both
-mechanisms permit users to
-.BR "trojan horse"
-others with relative impunity. The only real protection is tight
-control over who can define functions (e.g., write to relations with
-SQL fields) and rules. Audit trails and alerters on
-\*(lqpg_class\*(rq, \*(lqpg_user\*(rq and \*(lqpg_group\*(rq are also
-recommended.
-.SS "Functions"
-Functions written in any language except SQL
-run inside the backend server
-process with the permissions of the user \*(lqpostgres\*(rq (the
-backend server runs with its real and effective user-id set to
-\*(lqpostgres\*(rq). It is possible for users to change the server's
-internal data structures from inside of trusted functions. Hence,
-among many other things, such functions can circumvent any system
-access controls. This is an inherent problem with user-defined C functions.
-.SS "Rules"
-Like SQL functions, rules always run with the identity and
-permissions of the user who invoked the backend server.
-.SH "SEE ALSO"
-postmaster(1),
-alter(l),
-insert(l),
-grant/revoke(l),
-copy(l),
-create(l),
-delete(l),
-drop table(l),
-drop index(l),
-drop rule(l),
-update(l),
-select(l),
-kerberos(1),
-kinit(1),
-kerberos(3)
-.SH CAVEATS
-.PP
-There are no plans to explicitly support encrypted data inside of
-Postgres (though there is nothing to prevent users from encrypting
-data within user-defined functions). There are no plans to explicitly
-support encrypted network connections, either, pending a total rewrite
-of the frontend/backend protocol.
-.PP
-User names, group names and associated system identifiers (e.g., the
-contents of \*(lqpg_user.usesysid\*(rq) are assumed to be unique
-throughout a database. Unpredictable results may occur if they are
-not.
-.SH "APPENDIX: USING KERBEROS"
-.SS "Availability"
-The
-.IR Kerberos
-authentication system is not distributed with Postgres, nor is it
-available from the University of California at Berkeley. Versions of
-.IR Kerberos
-are typically available as optional software from operating system
-vendors. In addition, a source code distribution may be obtained
-through MIT Project Athena by anonymous FTP from ATHENA-DIST.MIT.EDU
-(18.71.0.38). (You may wish to obtain the MIT version even if your
-vendor provides a version, since some vendor ports have been
-deliberately crippled or rendered non-interoperable with the MIT
-version.) Users located outside the United States of America and
-Canada are warned that distribution of the actual encryption code in
-.IR Kerberos
-is restricted by U. S. government export regulations.
-.PP
-Any additional inquiries should be directed to your vendor or MIT
-Project Athena (\*(lqinfo-kerberos@ATHENA.MIT.EDU\*(rq). Note that FAQLs
-(Frequently-Asked Questions Lists) are periodically posted to the
-.IR Kerberos
-mailing list, \*(lqkerberos@ATHENA.MIT.EDU\*(rq (send mail to
-\*(lqkerberos-request@ATHENA.MIT.EDU\*(rq to subscribe), and USENET
-news group, \*(lqcomp.protocols.kerberos\*(rq.
-.SS "Installation"
-Installation of
-.IR Kerberos
-itself is covered in detail in the
-.IR "Kerberos Installation Notes" .
-Make sure that the server key file (the
-.IR srvtab
-or
-.IR keytab )
-is somehow readable by user \*(lqpostgres\*(rq.
-.PP
-Postgres and its clients can be compiled to use either Version 4 or
-Version 5 of the MIT
-.IR Kerberos
-protocols by setting the
-.SM KRBVERS
-variable in the file \*(lq.../src/Makefile.global\*(rq to the
-appropriate value. You can also change the location where Postgres
-expects to find the associated libraries, header files and its own
-server key file.
-.PP
-After compilation is complete, Postgres must be registered as a
-.IR Kerberos
-service. See the
-.IR "Kerberos Operations Notes"
-and related manual pages for more details on registering services.
-.SS "Operation"
-After initial installation, Postgres should operate in all ways as a
-normal
-.IR Kerberos
-service. For details on the use of authentication, see the manual
-pages for
-.IR postmaster (1)
-and
-.IR psql (1).
-.PP
-In the
-.IR Kerberos
-Version 5 hooks, the following assumptions are made about user
-and service naming: (1) user principal names (anames) are assumed to
-contain the actual Unix/Postgres user name in the first component; (2)
-the Postgres service is assumed to be have two components, the service
-name and a hostname, canonicalized as in Version 4 (i.e., all domain
-suffixes removed).
-.PP
-.nf
-user example: frew@S2K.ORG
-user example: aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
-host example: postgres_dbms/ucbvax@S2K.ORG
-.fi
-.PP
-Support for Version 4 will disappear sometime after the production
-release of Version 5 by MIT.
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/update.l,v 1.2 1996/10/07 02:34:54 momjian Exp $
-.TH UPDATE SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-update \(em replace values of attributes in a class
-.SH SYNOPSIS
-.nf
-\fBupdate\fR classname \fBset\fR attname-1 = expression-1,
- {attname-i = expression-i}
- [\fBfrom\fR from-list]
- [\fBwhere\fR qual]
-.fi
-.SH DESCRIPTION
-.BR Update
-changes the values of the attributes specified
-for all instances which satisfy the qualification,
-.IR qual .
-Only the attributes to be modified need appear as atributes.
-.PP
-Array references use the same syntax found in
-.IR select(l).
-That is, either single array elements, a range of array elements or
-the entire array may be replaced with a single query.
-.IR from-list
-is a non-standard extension to allow columns from
-other tables to appear in the target_list.
-.PP
-You must have write access to the class in order to modify it, as well
-as read access to any class whose values are mentioned in the target list
-or qualification.
-.SH EXAMPLES
-.nf
---
---Give all employees who work for Smith a 10% raise
---
-update emp
- set sal = 1.1 * sal
- where mgr = 'Smith'
-.fi
-.SH "SEE ALSO"
-create table(l),
-select(l).
+++ /dev/null
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/man/Attic/vacuum.l,v 1.3 1996/10/04 14:50:18 momjian Exp $
-.TH VACUUM SQL 11/05/95 Postgres95 Postgres95
-.SH NAME
-vacuum \(em vacuum a database
-.SH SYNOPSIS
-.nf
-\fBvacuum [table]\fP
-.fi
-.SH DESCRIPTION
-.BR Vacuum
-is the Postgres vacuum cleaner. It opens every class in the database,
-moves deleted records to the archive for archived relations, cleans
-out records from aborted transactions, and updates statistics in the
-system catalogs. The statistics maintained include the number of
-tuples and number of pages stored in all classes. Running
-.BR vacuum
-periodically will increase Postgres's speed in processing user queries.
-.PP
-The open database is the one that is vacuumed.
-.PP
-We recommend that production databases be vacuumed nightly, in order
-to keep statistics relatively current. The
-.BR vacuum
-query may be executed at any time, however. In particular, after
-copying a large class into Postgres or deleting a large number of
-records, it may be a good idea to issue a
-.BR vacuum
-query. This will update the system catalogs with the results of all
-recent changes, and allow the Postgres query optimizer to make better
-choices in planning user queries.
-.PP
-The purge(l) command can be used to control the archive retention
-characteristics of a given table.
-.SH "SEE ALSO"
-purge(l).
projects / postgresql / commitdiff