opensourcemirror
/
postgresql
mirror of git://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Releases Wiki Activity

moved man pages here, as requested by Bryan

This commit is contained in:
Marc G. Fournier 1996-11-14 10:18:14 +00:00
parent 389fe48cbb
commit 7ac541daf1
63 changed files with 8609 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/man/README Normal file
View File

@ -0,0 +1,3 @@
The page.5 source should be run through pic when generating troff
output. nroff doesn't handle pic.

23
src/man/abort.l Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/abort.l,v 1.1 1996/11/14 10:15:07 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).

61
src/man/alter_table.l Normal file
View File

@ -0,0 +1,61 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/alter_table.l,v 1.1 1996/11/14 10:15:09 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).

20
src/man/begin.l Normal file
View File

@ -0,0 +1,20 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/begin.l,v 1.1 1996/11/14 10:15:11 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).

219
src/man/bki.5 Normal file
View File

@ -0,0 +1,219 @@
.\" This is -*-nroff-*-
.\" $Header: /cvsroot/pgsql/src/man/Attic/bki.5,v 1.1 1996/11/14 10:15:12 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).

700
src/man/built-in.3 Normal file
View File

@ -0,0 +1,700 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/built-in.3,v 1.1 1996/11/14 10:15:15 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.

446
src/man/catalogs.3 Normal file
View File

@ -0,0 +1,446 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/catalogs.3,v 1.1 1996/11/14 10:15: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

23
src/man/cleardbdir.1 Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/cleardbdir.1,v 1.1 1996/11/14 10:15:24 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)

28
src/man/close.l Normal file
View File

@ -0,0 +1,28 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/close.l,v 1.1 1996/11/14 10:15:27 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).

33
src/man/cluster.l Normal file
View File

@ -0,0 +1,33 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/cluster.l,v 1.1 1996/11/14 10:15:32 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

23
src/man/commit.l Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/commit.l,v 1.1 1996/11/14 10:15:36 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).

177
src/man/copy.l Normal file
View File

@ -0,0 +1,177 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/copy.l,v 1.1 1996/11/14 10:15:39 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.

94
src/man/create_aggregate.l Normal file
View File

@ -0,0 +1,94 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_aggregate.l,v 1.1 1996/11/14 10:15:42 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).

25
src/man/create_database.l Normal file
View File

@ -0,0 +1,25 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_database.l,v 1.1 1996/11/14 10:15:45 scrappy 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.

417
src/man/create_function.l Normal file
View File

@ -0,0 +1,417 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_function.l,v 1.1 1996/11/14 10:15:48 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.

317
src/man/create_index.l Normal file
View File

@ -0,0 +1,317 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_index.l,v 1.1 1996/11/14 10:15:55 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

219
src/man/create_operator.l Normal file
View File

@ -0,0 +1,219 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_operator.l,v 1.1 1996/11/14 10:15:58 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.

221
src/man/create_rule.l Normal file
View File

@ -0,0 +1,221 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_rule.l,v 1.1 1996/11/14 10:16:03 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).

145
src/man/create_table.l Normal file
View File

@ -0,0 +1,145 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_table.l,v 1.1 1996/11/14 10:16:08 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).

161
src/man/create_type.l Normal file
View File

@ -0,0 +1,161 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_type.l,v 1.1 1996/11/14 10:16:12 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).

69
src/man/create_version.l Normal file
View File

@ -0,0 +1,69 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_version.l,v 1.1 1996/11/14 10:16:15 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.

45
src/man/create_view.l Normal file
View File

@ -0,0 +1,45 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_view.l,v 1.1 1996/11/14 10:16:17 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),

127
src/man/createdb.1 Normal file
View File

@ -0,0 +1,127 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/createdb.1,v 1.1 1996/11/14 10:16:20 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 .

122
src/man/createuser.1 Normal file
View File

@ -0,0 +1,122 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/createuser.1,v 1.1 1996/11/14 10:16:23 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.

37
src/man/delete.l Normal file
View File

@ -0,0 +1,37 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/delete.l,v 1.1 1996/11/14 10:16:29 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).

134
src/man/destroydb.1 Normal file
View File

@ -0,0 +1,134 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/destroydb.1,v 1.1 1996/11/14 10:16:32 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.

26
src/man/destroydb.l Normal file
View File

@ -0,0 +1,26 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/destroydb.l,v 1.1 1996/11/14 10:16:35 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.

119
src/man/destroyuser.1 Normal file
View File

@ -0,0 +1,119 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/destroyuser.1,v 1.1 1996/11/14 10:16:39 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.

41
src/man/drop.l Normal file
View File

@ -0,0 +1,41 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop.l,v 1.1 1996/11/14 10:16:43 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).

24
src/man/drop_aggregate.l Normal file
View File

@ -0,0 +1,24 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_aggregate.l,v 1.1 1996/11/14 10:16:47 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).

28
src/man/drop_function.l Normal file
View File

@ -0,0 +1,28 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_function.l,v 1.1 1996/11/14 10:16:53 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.

22
src/man/drop_index.l Normal file
View File

@ -0,0 +1,22 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_index.l,v 1.1 1996/11/14 10:17:01 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).

44
src/man/drop_operator.l Normal file
View File

@ -0,0 +1,44 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_operator.l,v 1.1 1996/11/14 10:17:04 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).

27
src/man/drop_rule.l Normal file
View File

@ -0,0 +1,27 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_rule.l,v 1.1 1996/11/14 10:17:07 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.

30
src/man/drop_type.l Normal file
View File

@ -0,0 +1,30 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_type.l,v 1.1 1996/11/14 10:17:09 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.

17
src/man/end.l Normal file
View File

@ -0,0 +1,17 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/end.l,v 1.1 1996/11/14 10:17:10 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).

70
src/man/fetch.l Normal file
View File

@ -0,0 +1,70 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/fetch.l,v 1.1 1996/11/14 10:17:13 scrappy 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.

33
src/man/grant.l Normal file
View File

@ -0,0 +1,33 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/grant.l,v 1.1 1996/11/14 10:17:15 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)

83
src/man/initdb.1 Normal file
View File

@ -0,0 +1,83 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/initdb.1,v 1.1 1996/11/14 10:17:17 scrappy 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).

113
src/man/insert.l Normal file
View File

@ -0,0 +1,113 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/insert.l,v 1.1 1996/11/14 10:17:19 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)

36
src/man/ipcclean.1 Normal file
View File

@ -0,0 +1,36 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/ipcclean.1,v 1.1 1996/11/14 10:17:22 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.

499
src/man/large_objects.3 Normal file
View File

@ -0,0 +1,499 @@
.\" 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/src/man/Attic/large_objects.3,v 1.1 1996/11/14 10:17:24 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

962
src/man/libpq.3 Normal file
View File

@ -0,0 +1,962 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.1 1996/11/14 10:17:26 scrappy 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

44
src/man/listen.l Normal file
View File

@ -0,0 +1,44 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/listen.l,v 1.1 1996/11/14 10:17:28 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.

51
src/man/load.l Normal file
View File

@ -0,0 +1,51 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/load.l,v 1.1 1996/11/14 10:17:30 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.

269
src/man/monitor.1 Normal file
View File

@ -0,0 +1,269 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/monitor.1,v 1.1 1996/11/14 10:17:32 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)

48
src/man/notify.l Normal file
View File

@ -0,0 +1,48 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/notify.l,v 1.1 1996/11/14 10:17:38 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.

130
src/man/page.5 Normal file
View File

@ -0,0 +1,130 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/page.5,v 1.1 1996/11/14 10:17:40 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/src/man/Attic/page.5,v 1.1 1996/11/14 10:17:40 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.

85
src/man/pg_dump.1 Normal file
View File

@ -0,0 +1,85 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_dump.1,v 1.1 1996/11/14 10:17:42 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)

21
src/man/pg_hba.conf.5 Normal file
View File

@ -0,0 +1,21 @@
.\" This is -*-nroff-*-
.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_hba.conf.5,v 1.1 1996/11/14 10:17:44 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).

171
src/man/postgres.1 Normal file
View File

@ -0,0 +1,171 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/postgres.1,v 1.1 1996/11/14 10:17:46 scrappy 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.

327
src/man/postmaster.1 Normal file
View File

@ -0,0 +1,327 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/postmaster.1,v 1.1 1996/11/14 10:17:48 scrappy 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.

359
src/man/psql.1 Normal file
View File

@ -0,0 +1,359 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/psql.1,v 1.1 1996/11/14 10:17:50 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.

61
src/man/purge.l Normal file
View File

@ -0,0 +1,61 @@
.\" 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).

23
src/man/remove_view.l Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/remove_view.l,v 1.1 1996/11/14 10:17:55 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),

63
src/man/rename.l Normal file
View File

@ -0,0 +1,63 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/rename.l,v 1.1 1996/11/14 10:17:56 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.

29
src/man/revoke.l Normal file
View File

@ -0,0 +1,29 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/revoke.l,v 1.1 1996/11/14 10:17:58 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)

24
src/man/rollback.l Normal file
View File

@ -0,0 +1,24 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/rollback.l,v 1.1 1996/11/14 10:18:00 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).

133
src/man/select.l Normal file
View File

@ -0,0 +1,133 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/select.l,v 1.1 1996/11/14 10:18:02 scrappy 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.

349
src/man/sql.l Normal file
View File

@ -0,0 +1,349 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/sql.l,v 1.1 1996/11/14 10:18:04 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‚‚ "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‚‚ "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).

279
src/man/unix.1 Normal file
View File

@ -0,0 +1,279 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/unix.1,v 1.1 1996/11/14 10:18:07 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.

43
src/man/update.l Normal file
View File

@ -0,0 +1,43 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/update.l,v 1.1 1996/11/14 10:18:11 scrappy 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).

37
src/man/vacuum.l Normal file
View File

@ -0,0 +1,37 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/vacuum.l,v 1.1 1996/11/14 10:18:14 scrappy 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).