Skip to content

P
Postgres FD Implementation
Commit a76ad509 authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Remove old man pages. All info is in new man pages or other docs.

parent d0a19198
Hide whitespace changes
Inline Side-by-side
Showing with 1 addition and 9006 deletions
src/GNUmakefile.in
View file @ a76ad509
......@@ -7,7 +7,7 @@
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/src/Attic/GNUmakefile.in,v 1.42 1999/07/01 00:06:28 tgl Exp $
# $Header: /cvsroot/pgsql/src/Attic/GNUmakefile.in,v 1.43 1999/08/08 15:20:21 thomas Exp $
#
#-------------------------------------------------------------------------
......@@ -43,9 +43,6 @@ install:
$(MAKE) -C pl install
cat ../register.txt
install-man:
$(MAKE) -C man install
lexverify:
$(MAKE) -C lextest all
@if test ! -f lextest/lextest; then \
......
src/man/Makefile deleted 100644 → 0
View file @ d0a19198
#-------------------------------------------------------------------------
#
# Makefile
# Makefile for doc directory to install man pages
#
# Copyright (c) 1994, Regents of the University of California
# Copyright (c) 1996, Dr George D Detlefsen
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/src/man/Attic/Makefile,v 1.8 1999/06/05 04:15:09 scrappy Exp $
#
#-------------------------------------------------------------------------
SRCDIR=..
include ../Makefile.global
all:
install:
-mkdir $(POSTMANDIR)
-mkdir $(POSTMANDIR)/man1
-mkdir $(POSTMANDIR)/man3
-mkdir $(POSTMANDIR)/man5
-mkdir $(POSTMANDIR)/manl
cp *.1* $(POSTMANDIR)/man1
cp *.3* $(POSTMANDIR)/man3
cp *.5* $(POSTMANDIR)/man5
cp *.l* $(POSTMANDIR)/manl
clean:
dep depend:
src/man/abort.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/abort.l,v 1.4 1998/03/23 15:09:22 momjian Exp $
.TH ABORT SQL 01/23/93 PostgreSQL PostgreSQL
.\" 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 - 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),
commit(l),
rollback(l).
src/man/alter_table.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/alter_table.l,v 1.7 1998/06/24 13:21:23 momjian Exp $
.TH "ALTER TABLE" SQL 09/25/97 PostgreSQL
.SH NAME
alter table - add attributes to a class, or rename an attribute or class
.SH SYNOPSIS
.nf
\fBalter table\fR classname [ * ]
\fBadd\fR [ \fBcolumn\fR ] attname type
\fBalter table\fR classname [ * ]
\fBadd\fR \fB(\fR attname type \fB)\fR
\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 "alter table"
command causes a new attribute to be added to an existing class,
.IR classname ,
or 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
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
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.
.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
--
-- add a health-care number to all persons
-- (including employees, students, ...)
--
alter table person * add column health_care_id int4
--
-- change the emp class to personnel
--
alter table emp rename to personnel
--
-- change the sports attribute to hobbies
--
alter table emp rename column sports to hobbies
--
-- make a change to an inherited attribute
--
alter table person * rename column last_name to family_name
.fi
.SH "SEE ALSO"
create_table(l),
update(l).
src/man/alter_user.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/alter_user.l,v 1.2 1998/03/06 18:02:49 momjian Exp $
.TH "ALTER USER" SQL 01/26/98 PostgreSQL PostgreSQL
.SH NAME
alter user -- alter user account information within a PostgreSQL instance
.SH SYNOPSIS
.nf
\fBalter user\fR username
[\fBwith password\fR password]
[\fBcreatedb\fR | \fBnocreatedb\fR]
[\fBcreateuser\fR | \fBnocreateuser\fR]
[\fBin group\fR group-1, ..., group-n]
[\fBvalid until '\fRabstime\fB'\fR]
.fi
.SH DESCRIPTION
.BR "alter user"
is used to change the attributes of a user's PostgreSQL account. For a
detailed description of each of the clause in the alter user statement,
please see the create_user(l) manual page. Please note that it is not
possible to alter a user's usesysid via the alter user statement. Also,
it is only possible for the postgres user or any user with read and modify
permissions on pg_shadow to alter user passwords.
If any of the clauses of the alter user statement are omitted, the
corresponding value in the pg_shadow relation is left unchanged.
This statement can be used to modify users created with createuser(1).
.SH EXAMPLES
.nf
---
--- Change a user password
---
alter user tab with password hu8jmn3;
.fi
.nf
---
--- Change a user's valid until date
---
alter user tab valid until 'Jan 31 2030';
.fi
.nf
---
--- Give a user the ability to create other users.
---
alter user tab createuser;
.fi
.SH "SEE ALSO"
create_user(l), drop_user(l).
src/man/begin.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/begin.l,v 1.6 1999/06/11 05:40:18 vadim Exp $
.TH BEGIN SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
begin - begins a transaction in chained mode
.SH SYNOPSIS
.nf
\fBbegin\fP \fB[transaction|work]\fR
.fi
.SH DESCRIPTION
By default, Postgres executes transactions in unchained mode (also known as
autocommit feature in other DBMSes). In other words, each user statement is
executed in its own transaction and commit is implicit (if execution was
successfull). BEGIN initiates a user transaction in chained mode, i.e. all
user statements after BEGIN command will be executed in single transaction
untill explicit COMMIT, ROLLBACK or execution abort. Statements in chained
mode are executed much faster, because of transaction start/commit requires
significant CPU and disk activity. This mode is also required for
consistency when changing one of related tables.
Default transaction isolation level in Postgres is READ COMMITTED one, when
queries inside transaction see only changes committed before query
execution. So, you have to use SET TRANSACTION ISOLATION LEVEL SERIALIZABLE
command just after BEGIN if you need in better transaction isolation. In
SERIALIZABLE mode queries will see only changes committed before entire
transaction began (actually, before execution of first DML statement in
serializable transaction).
If the transaction is committed, Postgres will ensure either that all
updates are done or else that none of them are done. Transactions have the
standard ACID (atomic, consistent, isolatable, and durable) property.
\fBNote\fR: There is no explicit BEGIN command in SQL92; transaction
initiation is always implicit and it terminates either with a COMMIT or with
a ROLLBACK statement (i.e. all transactions are chained). SQL92 also
requires SERIALIZABLE to be default transaction isolation level.
.SH "SEE ALSO"
rollback(l),
commit(l),
set(l),
lock(l).
src/man/catalogs.3 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/catalogs.3,v 1.6 1999/05/20 02:44:53 tgl Exp $
.TH "SYSTEM CATALOGS" INTRO 03/13/94 PostgreSQL PostgreSQL
.SH "Section 7 - 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_shadow 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/rollback log
pg_magic shared magic constant
pg_time shared commit/rollback 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:
INTERNAL function: actual C name of function
C function: currently, this field is unused
SQL function: text of query(s)
PL function: text in procedural language */
bytea probin /* path to object file (C functions 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_shadow
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
src/man/cleardbdir.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/cleardbdir.1,v 1.4 1998/06/24 13:21:23 momjian Exp $
.TH CLEARDBDIR UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
cleardbdir - 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)
src/man/close.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/close.l,v 1.3 1998/01/11 22:17:09 momjian Exp $
.TH CLOSE SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
close - 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).
src/man/cluster.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/cluster.l,v 1.7 1998/03/15 02:13:23 momjian Exp $
.TH CLUSTER SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
cluster - 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, as the class is
updated, the changes are not clusterd. No attempt is made to keep new
instances or updated tuples clustered. If desired, the user can
recluster manually by issuing the command again.
.PP
The table is actually copied to temporary table in index order, then
renamed back to the original name. For this reason, all grant
permissions and other indexes are lost when cluster is performed.
.PP
In cases where you are accessing single rows randomly within a table,
the actual order of the data in the heap table unimportant. However, if
you tend to access some data more than others, and there is an index
that groups them together, you will benefit from using the CLUSTER
command.
.PP
Another place CLUSTER is good is in cases where you use an index to pull
out several rows from a table. If you are requesting a range of indexed
values from a table, or a single indexed value that has multiple rows
that match, CLUSTER will help because once the index identifies the heap
page for the first row that matches, all other rows that match are
probably already on the same heap page, saving disk accesses and speeding up
the query.
.PP
There are two ways to cluster data. The first is with the CLUSTER
command, which reoreders the original table with the ordering of the
index you specify. This can be slow on large tables because the rows
are fetched from the heap in index order, and if the heap table is
unordered, the entries are on random pages, so there is one disk page
retrieved for every row moved. PostgreSQL has a cache, but the majority
of a big table will not fit in the cache.
.PP
Another way is to use SELECT ... INTO TABLE temp FROM ...ORDER BY ...
This uses the PostgreSQL sorting code in ORDER BY to match the index,
and is much faster for unordered data. You then drop the old table, use
ALTER TABLE RENAME to rename 'temp' to the old name, and recreate the b
bindexes. The only problem is that oids will not be preserved. From
then on, CLUSTER should be fast because most of the heap data has
already been ordered, and the existing index is used.
.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
src/man/commit.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/commit.l,v 1.5 1998/03/25 01:54:51 momjian Exp $
.TH COMMIT SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
commit - 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"
rollback(l),
begin(l),
commit(l),
rollback(l).
src/man/copy.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/copy.l,v 1.7 1999/02/02 03:45:31 momjian Exp $
.TH COPY SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
copy - 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.
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 represented as \\N.
A literal backslash character is represented 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 PostgreSQL, 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.
src/man/create_aggregate.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_aggregate.l,v 1.6 1998/06/23 17:52:31 momjian Exp $
.TH "CREATE AGGREGATE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
create aggregate - 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),
drop_aggregate(l).
src/man/create_database.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_database.l,v 1.6 1998/06/23 17:52:31 momjian Exp $
.TH "CREATE DATABASE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
create database - create a new database
.SH SYNOPSIS
.nf
\fBcreate database\fP dbname [\fBwith location = '\fPdbpath\fB'\fP]
.fi
.SH DESCRIPTION
.BR "create database"
creates a new Postgres database. The creator becomes the administrator
of the new database. An alternate location can be specified as either an
environment variable known to the backend server (e.g. 'PGDATA2') or as
an absolute path name (e.g. '/home/postgres/data'). In either case, the
location must be pre-configured by
.BR initarea
.SH "SEE ALSO"
createdb(1),
drop_database(l),
destroydb(1),
initarea(1),
initdb(1).
src/man/create_function.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_function.l,v 1.11 1999/05/20 02:44:53 tgl Exp $
.TH "CREATE FUNCTION" SQL 11/05/95 PostgreSQL PostgreSQL
.SH "NAME"
create function - define a new function
.SH "SYNOPSIS"
.nf
\fBcreate function\fP function_name
\fB(\fP[type1 {, type-n}]\fB)\fP
\fBreturns\fP type-r
\fBas\fP { '/full/path/to/objectfile' | 'sql-queries' |
'builtin-function-name' | 'pl-program-text' }
\fBlanguage\fP { 'c' | 'sql' | 'internal' | 'plname' }
.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" .
or
.IR "\*(lqplname\*(rq" .
(The
.IR "plname"
is the language name of a created procedural language. See
create_language(l) for details.)
(The argument list
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 depending on the language,
as explained below.
.SH "INTERNAL FUNCTIONS"
Internal functions are functions written in C which have been statically
linked into the postgres backend process. The
.BR as
clause gives the C-language name of the function, which need not be the
same as the name being declared for SQL use. (For reasons of backwards
compatibility, an empty
.BR as
string is accepted as meaning that the C-language function name is the
same as the SQL name.) Normally, all internal functions present in the
backend are declared as SQL functions during database initialization,
but a user could use
.BR "create function"
to create additional alias names for an internal function.
.SH "C FUNCTIONS"
Functions written in C can be defined to Postgres, which will dynamically
load them into its address space. The
.IR as
clause gives the full path name of the object file that contains the
function. This file is loaded 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.
.SH "Writing C Functions"
For a C function, the string following
.BR as
should be the
.BR "FULL PATH"
of the object code file for the function, bracketed by quotation
marks. (Postgres will not compile a function automatically - it must
be compiled before it is used in a
.BR "create function"
command. See below for additional information.)
.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
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').
.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 "PL FUNCTIONS"
Procedural languages aren't built into Postgres. They are offered
by loadable modules. Please refer to the documentation for the
PL in question for details about the syntax and how the
.IR "as"
clause is interpreted by the PL handler.
.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), create_language(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"
For functions written in C, the SQL name declared in
.BR "create function"
must be exactly the same as the actual name of the function in the
C code (hence it must be a legal C function name).
.PP
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
Another solution is not to use dynamic loading, but to link your
functions into the backend statically and declare them as INTERNAL
functions. Then, the functions must all have distinct C names but
they can be declared with the same SQL names (as long as their
argument types differ, of course). This way avoids the overhead of
an SQL wrapper function, at the cost of more effort to prepare a
custom backend executable.
.PP
.IR opaque
cannot be given as an argument to a SQL function.
.SH "BUGS"
C functions cannot return a set of values.
src/man/create_index.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_index.l,v 1.12 1998/08/19 02:04:12 momjian Exp $
.TH "CREATE INDEX" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
create index - construct a secondary index
.SH SYNOPSIS
.nf
\fBcreate\fR [\fBunique\fR] \fBindex\fR index-name
\fBon\fR classname [\fBusing\fR am-name]
\fB(\fR attname [type_class], ...\fB )\fR
\fBcreate\fR [\fBunique\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 fields for the index are
specified as attribute names. It may also have 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
\fBNote:\fR currently, only
.IR btree
access method supports multi-attribute indices.
Up to 7 keys may be specified.
.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"
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
The \fBunique\fR keyword causes the system to check for duplicate
values when the index is created (if data already exist) and each
time data is added.
Attempts to insert or update non-duplicate data will generate an error.
.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 |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 |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 |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
.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 name_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
src/man/create_language.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_language.l,v 1.4 1999/07/15 15:21:45 momjian Exp $
.TH "CREATE LANGUAGE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH "NAME"
create language - define a new language for functions
.SH "SYNOPSIS"
.nf
\fBcreate\fP [\fBtrusted\fP] \fBprocedural language\fP 'lanname'
\fBhandler\fP call_handler
\fBlancompiler\fP 'comment'
.fi
.SH "DESCRIPTION"
With this command, a Postgres user can register a new language with
Postgres. Subsequently, functions and trigger procedures can be
defined in this new language. The user must have the Postgres superuser
privilege to register a new language.
.PP
The lanname is the name of the new procedural language. It is converted
to lower case before the new entry in the pg_language system catalog
is inserted. Note that this case translation is also done on
create_function(l) and drop_language(l). Thus, the language name
is case insensitive. A procedural language cannot override one of the
builtin languages of Postgres.
.PP
The argument for \fBhandler\fP
is the name of a previously registered function that
will be called to execute the PL procedures.
.PP
The \fBlancompiler\fP argument is the string that will be inserted
in the lancompiler attribute of the new pg_language entry. Up to now,
Postgres doesn't use this attribute in any way.
.PP
The \fBtrusted\fP keyword specifies, that the call handler for the
language is safe - i.e. it offers an unprivileged user no functionality
to get around access restrictions. If this keyword is omitted when
registering the language, only users with the Postgres superuser privilege
can use this language to create new functions (like the 'C' language).
.SH "WRITING PL HANDLERS"
The call handler for a procedural language must be written in a compiler
language such as 'C' and registered with Postgres as a function taking
no arguments and returning
.IR "opaque"
type. This prevents the call handler from beeing called directly as a function
from queries.
But there are arguments
on the actual call when a PL function or trigger procedure in the
language offered by the handler is to be executed.
.PP
When called from the trigger manager, the only argument is the object ID from
the procedures pg_proc entry. All other information from the trigger manager
is found in the global CurrentTriggerData pointer.
.PP
When called from the function manager, the arguments are the object ID of the
procedures pg_proc entry, the number of arguments given to the PL function,
the arguments in a FmgrValues structure and a pointer to a boolean where the
function tells the caller if the return value is the SQL NULL value.
.PP
It's up to the call handler to fetch the pg_proc entry
and to analyze the argument and return types of the called procedure.
the
.IR "as"
clause from the create_function(l) of the procedure will be found in
the prosrc attribute of the pg_proc entry. This may be the source text
in the procedural language itself (like for PL/Tcl), a pathname to a
file or anything else that tells the call handler what to do in detail.
.SH "EXAMPLE"
Following is a template for a PL handler written in 'C':
.nf
#include "executor/spi.h"
#include "commands/trigger.h"
#include "fmgr.h" /* for FmgrValues struct */
#include "access/heapam.h"
#include "utils/syscache.h"
#include "catalog/pg_proc.h"
#include "catalog/pg_type.h"
Datum
plsample_call_handler(
Oid prooid,
int pronargs,
FmgrValues *proargs,
bool *isNull)
{
Datum retval;
TriggerData *trigdata;
if (CurrentTriggerData == NULL) {
/*
* Called as a function
*/
retval = ...
} else {
/*
* Called as a trigger procedure
*/
trigdata = CurrentTriggerData;
CurrentTriggerData = NULL;
retval = ...
}
*isNull = false;
return retval;
}
.fi
Only a few thousand lines of code have to be added instead of the dots
to complete the PL call handler. See create_function(l) how to compile
it into a loadable module. The following commands then register the
sample procedural language.
.nf
create function plsample_call_handler () returns opaque
as '/usr/local/pgsql/lib/plsample.so'
language 'C';
create procedural language 'plsample'
handler plsample_call_handler
lancompiler 'PL/Sample';
.fi
.SH "SEE ALSO"
.PP
create_function(l), drop_language(l).
.SH "RESTRICTIONS"
Since the call handler for a procedural language must be
registered with Postgres in the 'C' language, it inherits
all the restrictions of 'C' functions.
.SH "BUGS"
Currently, the definitions for a procedural language once
created cannot be changed.
src/man/create_operator.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_operator.l,v 1.9 1999/05/20 03:21:02 tgl Exp $
.TH "CREATE OPERATOR" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
create operator - 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, join =\fR join_proc ]
[\fB, hashes\fR]
[\fB, sort1 =\fR left_sort_op ]
[\fB, sort2 =\fR right_sort_op ]
\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 punctuation characters. The following
characters are valid for single-character operator names:
.nf
.ce 1
~ ! @ # % ^ & ` ?
.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
.ce 1
| $ : + - * / < > =
.fi
The operator "!=" is mapped to "<>" on input, and they are
therefore equivalent.
.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 should be identified if one exists,
so that Postgres can reverse the order of the operands if it wishes.
For example, the operator
area-less-than, >>>, would probably have a commutator operator,
area-greater-than, <<<. Hence, the query optimizer
could freely convert:
.nf
.ce 1
"0,0,1,1"::box >>> MYBOXES.description
.fi
to
.nf
.ce 1
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
Similarly, if there is a negator operator then it should be identified.
Suppose that an operator, area-equal, ===,
exists, as well as an area not equal, !==.
The negator link allows the query optimizer to simplify
.nf
.ce 1
NOT MYBOXES.description === "0,0,1,1"::box
.fi
to
.nf
.ce 1
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 newly created
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. (As of Postgres 6.5,
it also works to just have both operators refer to each other.)
.PP
The next three 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 can use a hash-join algorithm
along the lines of [SHAP86]; however, it must know whether this
strategy is applicable.
The current hash-join algorithm
is only correct for operators that represent equality tests;
furthermore, equality of the datatype must mean bitwise equality
of the representation of the type. (For example, a datatype that
contains unused bits that don't matter for equality tests could
not be hashjoined.)
The
.BR hashes
flag indicates to the query optimizer that a hash join may safely be
used with this operator.
.PP
Similarly, the two sort operators indicate to the query optimizer
whether merge-sort is a usable join strategy and which operators should
be used to sort the two operand classes.
Sort operators should only be provided for an equality
operator, and they should refer to less-than operators for the
left and right side data types respectively.
.PP
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
.ce 1
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 create_function(l))
which accepts arguments of the correct data types and returns a
floating point number. The query optimizer simply calls this
function, passing the parameter "0,0,1,1"
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
.ce 1
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
.fi
and the operator
.nf
.ce 1
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,
join = area_join_procedure,
hashes,
sort1 = <<<,
sort2 = <<<)
.\" 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 dummy entry for the commutator (with invalid oprproc field) will be placed
in the system catalogs. This entry will be overridden when the commutator
is eventually defined.
src/man/create_rule.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_rule.l,v 1.11 1999/02/07 22:10:09 wieck Exp $
.TH "CREATE RULE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
create rule - 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]
[\fBnothing\fP | action | \fB(\fPactions...\fB)\fP]
.fi
.SH DESCRIPTION
.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 a class name.
.PP
The
.BR "where"
clause, and the
.IR action
are respectively normal SQL
.BR "where"
clauses and collections of SQL commands with the following change:
.IP
.BR new
or
.BR old
can appear instead of
an instance variable whenever an instance
variable is permissible in SQL.
.PP
Since v6.4 rules on
.IR select
are restricted to build
.BR views .
.BR "Create view"
should be used instead.
.PP
The semantics of a rule is that at the time an individual instance is
updated, inserted or deleted, there is an
.BR old
instance
(for updates and deletes) and a
.BR new
instance (for updates and inserts). If the event specified in the
.BR "on"
clause and the condition specified in the
.BR "where"
clause are true, then the
.IR action
part of the rule is executed. First, however, values from fields in
the old instance and/or the new instance are substituted for:
.nf
old.attribute-name
new.attribute-name
.fi
The
.IR action
part of the rule executes with same transaction identifier
before the user command that caused activation.
.PP
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
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 update
command to one of the classes will cause
Postgres to abort the transaction during the attempt to apply rules.
.nf
--
--Example of a circular rewrite rule combination.
--
create rule bad_rule_combination_1 as
on update to EMP
do update TOY set ...;
create rule bad_rule_combination_2 as
on update to TOY
do update EMP set ...;
.fi
.PP
You must have
.IR "rule definition"
access to a class in order to define a rule on it.
.PP
In contrast to queries run by trigger procedures,
the rule actions are executed under the permissions of the owner
of the
.BR event
class. Thus, if the owner of a class defines a rule that inserts something
into another one (like in the log example below), the user updating the
.BR event
class must not have
.IR insert
permissions for the class specified in the
.BR "rule actions" .
This technique can safely be used to deny users from modifying event logging.
.SH EXAMPLES
.nf
--
--Make Sam get the same salary adjustment as Joe
--
create rule example_1 as
on update to EMP where old.name = "Joe"
do update EMP set salary = new.salary
where EMP.name = "Sam";
.fi
At the time Joe receives a salary adjustment, the event will become
true and Joe's old 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 executed. This propagates
Joe's salary on to Sam.
.nf
--
-- Log changes to salary
--
create rule example_2 as
on insert to EMP
do insert into EMP_LOG (name, newsal, when)
values (new.name, new.salary, 'now'::text);
create rule example_3 as
on update to EMP where old.salary != new.salary
do insert into EMP_LOG (name, oldsal, newsal, when)
values (old.name, old.salary, new.salary, 'now'::text);
create rule example_4 as
on delete to EMP
do insert into EMP_LOG (name, oldsal, when)
values (old.name, old.salary, 'now'::text);
.fi
.SH "SEE ALSO"
drop_rule(l),
create_view(l),
create_trigger(l).
.SH BUGS
.PP
The rule system stores the rule definition as query plans into text
attributes. This implies that creation of rules may fail if the
rule in its internal representations exceed some value
that is on the order of one page (8KB).
src/man/create_sequence.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_sequence.l,v 1.6 1998/08/30 21:03:19 scrappy Exp $
.TH "CREATE SEQUENCE" SQL 07/13/98 PostgreSQL PostgreSQL
.SH NAME
create sequence - create a new sequence number generator
.SH SYNOPSIS
.nf
\fBcreate sequence\fR seqname
[\fBincrement\fP incby_value]
[\fBminvalue\fP min_value]
[\fBmaxvalue\fP max_value]
[\fBstart\fP start_value]
[\fBcache\fP cache_value]
[\fBcycle\fP]
.fi
.SH DESCRIPTION
.BR "Create sequence"
will enter a new sequence number generator into the current data base.
Actually, a new single-record
.BR table
with name
.IR seqname
will be created and initialized.
The generator will be
\*(lqowned\*(rq by the user issuing the command.
.PP
The
.BR increment
clause is optional. A positive value will make an ascending sequence,
negative - descending. Default value is 1.
.PP
The optional integer
.BR minvalue
determines the minimum value the sequence can generate. Defaults are
1/-2147483647 for ascending/descending sequences.
.PP
The optional integer
.BR maxvalue
determines the maximum value the sequence can generate. Defaults are
2147483647/-1 for ascending/descending sequences.
.PP
The optional
.BR start
value sets the first value to be generated. Default is
.BR minvalue
for ascending sequences and
.BR maxvalue
for descending ones.
.PP
The
.BR cache
option enables sequence numbers to be preallocated and
stored in memory for faster access. The minimum value is 1
(one value will be allocated at a time, i.e., no cache)
and that is the default. See below for details.
.PP
The optional
.BR cycle
keyword may be used to enable the sequence to continue after the
.BR maxvalue/minvalue
has been reached by ascending/descending sequence.
If the limit is reached, the next number generated will be
whatever the
.BR minvalue/maxvalue
is.
.PP
After a sequence object has been created, you may use the function
.BR nextval
with the sequence name as argument to generate a new number from the
specified sequence.
.PP
The function
.BR currval
('sequence_name')
may be used to re-fetch the number returned by the last call to
.BR nextval
for the specified sequence in the current session.
.BR NOTE:
currval will return an error if nextval has never been called for the
given sequence in the current backend session. Also beware that it
does not give the last number ever allocated, only the last one allocated
by this backend.
.PP
The function
.BR setval
('sequence_name', value)
may be used to set the current value of the specified sequence.
The next call to
.BR nextval
will return the given value + the sequence increment.
.PP
Use a query like
.nf
SELECT * FROM <sequence_name>;
.fi
to get the parameters of a sequence. Aside from fetching the original
parameters, you can use
.nf
SELECT last_value FROM <sequence_name>;
.fi
to obtain the last value allocated by any backend.
.PP
Low-level locking is used to ensure that multiple backends can safely use
a sequence object concurrently.
.PP
.BR NOTE:
Unexpected results may be obtained if a cache setting greater than one
is used for a sequence object that will be used concurrently by multiple
backends. Each backend will allocate "cache" successive sequence values
during one access to the sequence object and increase the sequence
object's last_value accordingly. Then, the next cache-1 uses of nextval
within that backend simply return the preallocated values without touching
the shared object. So, numbers allocated but not used in the current session
will be lost. Furthermore, although multiple backends are guaranteed to
allocate distinct sequence values, the values may be generated out of
sequence when all the backends are considered. (For example, with a cache
setting of 10, backend A might reserve values 1..10 and return nextval=1, then
backend B might reserve values 11..20 and return nextval=11 before backend
A has generated nextval=2.) Thus, with a cache setting of one it is safe
to assume that nextval values are generated sequentially; with a cache
setting greater than one you should only assume that the nextval values
are all distinct, not that they are generated purely sequentially.
Also, last_value will reflect the latest value reserved by any backend,
whether or not it has yet been returned by nextval.
.PP
.SH EXAMPLES
.nf
--
-- Create sequence seq caching 2 numbers, starting with 10
--
create sequence seq cache 2 start 10;
.fi
.nf
--
-- Select next number from sequence
--
select nextval ('seq');
.fi
.nf
--
-- Use sequence in insert
--
insert into table _table_ values (nextval ('seq'),...);
.nf
--
-- Set the sequence value after a copy in
--
create function table_id_max() returns int4
as 'select max(id) from _table_'
language 'sql';
copy _table_ from 'input_file';
select setval('seq', table_id_max());
.fi
.SH "SEE ALSO"
drop_sequence(l).
src/man/create_table.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_table.l,v 1.23 1999/02/02 03:45:32 momjian Exp $
.TH "CREATE TABLE" SQL 09/25/97 PostgreSQL
.SH NAME
create table - create a new class
.SH SYNOPSIS
.nf
\fBcreate\fR [\fBtemp\fR] \fBtable\fR classname
\fB(\fP
attname type
[\fBdefault\fP value]
[[\fBnot null\fP] [\fBunique\fP] | [\fBprimary key\fP]]
[\fBreferences\fP classname \fB(\fP attname \fB)\fP]
[\fBcheck (\fP condition\fB )\fP]
[\fB,\fP attname type [constraint] [\fB,\fP ...] ]
[\fB, primary key ( \fPattname, attname[,...] \fB)\fP]
[\fB, unique ( \fPattname, attname[,...] \fB)\fP]
[\fB, foreign key ( \fPattname, attname[,...] \fB) references\fP classname]
[\fB,\fP [\fBconstraint\fR cname] \fBcheck\fR \fB(\fR test \fB)\fR [, \fBcheck\fR \fB(\fR test \fB)\fR ] ]
\fB)\fP
[\fBinherits\fR \fB(\fR classname [\fB,\fR classname] \fB)\fR]
.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.
Each attribute is created with the type specified by
.IR type "."
Each type may be a simple type, a complex type (set) or an array type.
Each attribute may be specified to be non-null and
each may have a default value, specified by the
.IR default
clause which is the keyword "default" followed by a constant or expression.
.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
N.B. As of Postgres version 6.0, consistant array dimensions within an
attribute are not enforced. This will likely change in a future release.
.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(l)
statements.
.PP
The optional
.BR constraint
clauses specify constraints or tests which new or updated entries
must satisfy for an insert or update operation to succeed. Each constraint
must evaluate to a boolean expression. Multiple attributes may be referenced within
a single constraint. The use of \fBprimary key (\fPattname[\fB,\fP...]\fB)\fP
as a table constraint
is mutually incompatible with \fBprimary key\fP used as a column constraint.
.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
.SH EXAMPLES
.nf
--
-- Create class emp with attributes name, sal and bdate
--
create table emp (name name, salary float4, bdate abstime)
.fi
.nf
--
--Create class permemp with pension information that
--inherits all fields of emp
--
create table permemp (plan name) inherits (emp)
.fi
.nf
--
--Create class emppay with attributes name and wage with
--a default salary and constraints on wage range
--
create table emppay (name text not null, wage float4 default 10.00
constraint empcon check (wage > 5.30 and wage <= 30.00), check (name <> ''))
.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
.nf
--
--Create a table using SQL92 syntax
create table component
(
assembly char(8) not null
references job (id),
product char(8) not null
references product (id),
sorting int,
qty int check (qty >= 0),
primary key (assembly, product),
unique (assembly, product, sorting),
constraint not_same check (assembly != product)
)
.fi
.PP
.SH BUGS
The \fBforeign key\fP and \fBreferences\fP keywords are parsed but not yet
implemented in PostgreSQL 6.3.1.
.SH "SEE ALSO"
drop_table(l).
src/man/create_trigger.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_trigger.l,v 1.4 1998/06/23 17:52:33 momjian Exp $
.TH "CREATE TRIGGER" SQL 09/25/97 PostgreSQL
.SH NAME
create trigger - create a new trigger
.SH SYNOPSIS
.nf
\fBcreate trigger\fR trigname \fB{before|after}\fP
\fB{Event1 [OR Event2 [OR Event3]]}\fB
\fBon\fR relname \fBfor each {row|statement}\fR
\fBexecute procedure\fR funcname \fB(\fR arguments \fB)\fR
where \fBEventX\fR is one of INSERT, DELETE, UPDATE
.fi
.SH DESCRIPTION
.BR "Create Trigger"
will enter a new trigger into the current data base. The trigger will be
associated with the relation
.IR relname
and will execute the specified
.IR funcname .
Only relation owner may create a trigger on this relation.
Currently, STATEMENT triggers are not implemented.
.PP
The trigger can be specified to fire either
.BR before
the operation is attempted on a tuple (e.g. before constraints are checked and
the insert/update/delete is attempted) or
.BR after
the operation has been attempted (e.g. after constraints are checked and the
insert/update/delete has completed).
If the trigger fires
.BR before
then the trigger may
skip the operation for the current tuple,
or change tuple being inserted (for insert/update operations only).
If the trigger fires
.BR after
then all changes including the last insertion/updation/deletion
are "visible" to trigger.
.PP
Refer to the SPI and trigger programming guides for more information.
.SH EXAMPLES
Examples are included in the contrib area of the source distribution.
.SH "SEE ALSO"
drop_trigger(l).
src/man/create_type.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_type.l,v 1.6 1998/06/24 13:21:24 momjian Exp $
.TH "CREATE TYPE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
create type - 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),
large_objects(3).
src/man/create_user.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_user.l,v 1.3 1998/06/24 13:21:24 momjian Exp $
.TH "CREATE USER" SQL 01/26/98 PostgreSQL PostgreSQL
.SH NAME
create user -- create a new user within a PostgreSQL instance
.SH SYNOPSIS
.nf
\fBcreate user <username>
[\fBwith password\fR password]
[\fBcreatedb\fR | \fBnocreatedb\fR]
[\fBcreateuser\fR | \fBnocreateuser\fR]
[\fBin group\fR group-1, ..., group-n]
[\fBvalid until '\fRabstime\fB'\fR]
.fi
.SH DESCRIPTION
.BR "create user"
will add a new user to an instance of PostgreSQL. The new user will be
given a usesysid of 'SELECT max(usesysid) + 1 FROM pg_shadow'. This means
that a PostgreSQL user's usesysid will not correspond to their operating
system(OS) user id. The exception to this rule is the 'postgres' user,
whose OS user id is used as the usesysid during the initdb process. If
you still want the OS user id and the usesysid to match for any given
user, then use the createuser(1) script provided with the PostgreSQL
distribution.
The 'with password' clause sets the user's password within the pg_shadow
relation. For this reason, pg_shadow is no longer accessible to the
'public' group. Please note that when initdb(1) is executed for an
instance of PostgreSQL that the postgres user's password is initially set
to NULL. When a user's password in the pg_shadow relation is NULL, then
user authentication proceeds as it historically has (HBA, PG_PASSWORD,
etc). However, if a password is set for a user, then a new authentication
system supplants any other configured for the PostgreSQL instance, and the
password stored in the pg_shadow relation is used for authentication. For
more details on how this authentication system functions see pg_crypt(3).
If the 'with password' clause is omitted, then the user's password is set
to the empty string with equates to a NULL value in the authentication
system mentioned above.
The createdb/nocreatedb clause defines a user's ability to create
databases. If createdb is specified, then the user being defined will be
allowed to create his/her own databases. Using nocreatedb will deny a
user the ability to create databases. If this clause is omitted, then
nocreatedb is used by default.
The createuser/nocreateuser clause allows/prevents a user from creating
new users in an instance of PostgreSQL. Omitting this clause will set the
user's value of this attribute to be nocreateuser.
At the current time the 'in group' clause is non-functional. The intent
is to use this clause to affect the groups a user is a member of (as
defined in the pg_group relation).
Finally, the 'valid until' clause sets an absolute time after which the
user's PostgreSQL login is no longer valid. Please note that if a user
does not have a password defined in the pg_shadow relation, then the valid
until date will not be checked during user authentication. If this clause
is omitted, then a NULL value is stored in pg_shadow for this attribute, and
the login will be valid for all time.
.SH EXAMPLES
.nf
---
--- Create a user with no password
---
create user tab;
.fi
.nf
---
--- Create a user with a password
---
create user tab with password jw8s0F4;
.fi
.nf
---
--- Create a user with a password, whose account is valid thru 2001
--- Note that after one second has ticked in 2002, the account is not
--- valid
---
create user tab with password jw8s0F4 valid until 'Jan 1 2002';
.fi
.nf
---
--- Create an account where the user can create databases.
---
create user tab with password jw8s0F4 createdb;
.fi
.SH "SEE ALSO"
alter_user(l), drop_user(l).
src/man/create_version.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_version.l,v 1.5 1998/06/24 13:21:25 momjian Exp $
.TH "CREATE VERSION" SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
create version - 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).
.SH "BUGS"
Snapshots (i.e., the optional
.IR abstime
clause) are not implemented in Postgres.
src/man/create_view.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_view.l,v 1.4 1998/06/23 17:52:34 momjian Exp $
.TH "CREATE VIEW" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
create view - 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),
src/man/createdb.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/createdb.1,v 1.13 1998/10/14 02:54:30 momjian Exp $
.TH CREATEDB UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
createdb - create a database
.SH SYNOPSIS
.BR createdb
[\c
.BR -a
system]
[\c
.BR -h
host]
[\c
.BR -p
port]
[\c
.BR "-u"]
[\c
.BR -D
location]
[dbname]
.SH DESCRIPTION
.BR 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"
to use in connecting to the
.IR postmaster
process. This option no longer has any effect.
.TP
.BR "-D" " dbpath"
Specifies the alternate database location for this database.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to the using local Unix domain sockets.
.TP
.BR "-p" " port"
Specifies the Internet TCP/IP port or local Unix domain socket file
extension 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 "-u"
Use password authentication. Prompts for username and password.
.SH EXAMPLES
.nf
# create the demo database using the postmaster on the local host, port 5432.
createdb demo
.fi
.nf
# create the demo database using the postmaster on host eden,
# port 5000.
createdb -p 5000 -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"
create_database(l),
destroy_db(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 .
.SH NOTE
The command internally runs \fIcreate database\fP from \fP\fIpsql\fP
connected to the \fItemplate1\fP database to perform the operation.
src/man/createuser.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/createuser.1,v 1.13 1998/10/14 02:54:31 momjian Exp $
.TH CREATEUSER UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
createuser - create a Postgres user
.SH SYNOPSIS
.BR createuser
[\c
.BR -a
system]
[\c
.BR -d
]
[\c
.BR -D
]
[\c
.BR -h
host]
[\c
.BR -i
id]
[\c
.BR -p
port]
[\c
.BR -u
]
[\c
.BR -U
]
[username]
.SH DESCRIPTION
.IR Createuser
creates a new Postgres user. Only users with \*(lqusesuper\*(rq set in
the \*(lqpg_shadow\*(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"
to use in connecting to the
.IR postmaster
process. This option no longer has any effect.
.TP
.BR "-d"
Allows the user to create databases.
.TP
.BR "-D"
Does not allow the user to create databases.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to using local Unix domain sockets.
.TP
.BR "-i" " id"
Use
.IR id
as the user id.
.TP
.BR "-p" " port"
Specifies the TCP/IP port or local Unix domain socket file
extension 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 "-u"
Allows the user to create other users.
.TP
.BR "-U"
Does not allow the user to create other users.
.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"
create_user(l),
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_shadow\*(rq"
You do not have a valid entry in the relation \*(lqpg_shadow\*(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_shadow\*(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 NOTE
The command internally runs \fIcreate user\fP from \fIpsql\fP
connected to the \fItemplate1\fP database to perform the operation.
src/man/declare.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/declare.l,v 1.5 1998/04/28 18:39:11 momjian Exp $
.TH FETCH SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
declare - declare a cursor
.SH SYNOPSIS
.nf
\fBdeclare\fR cursor_name [ \fBbinary\fR ] \fBcursor for\fR select statement
.fi
.SH DESCRIPTION
.BR Declare
allows a user to create cursors.
Cursors are only available in transactions.
.PP
Normal cursors return data back in ASCII format. Since data is stored
natively in binary format, the system must do a conversion to produce
the ASCII format. In addition, ASCII formats are often larger in size
than binary format. Once the attributes come back in ASCII, often the
client application then has to convert it to a binary format to
manipulate it anyway.
.PP
\fBBinary\fR cursors give you back the data in the native binary
representation. Thus, binary cursors will tend to be a little faster
since there's less overhead of conversion.
.PP
However, ASCII is architectural neutral whereas binary representation
can differ between different machine architecture. Thus, if your client
machine uses a different representation than you server machine, getting
back attributes in binary format is probably not what you want. Also, if
your main purpose is displaying the data in ASCII, then getting it back
in ASCII will save you some effort on the client side.
.PP
For an example, see the fetch(l) manual page.
.SH "SEE ALSO"
fetch(l),
begin(l),
commit(l),
select(l).
src/man/delete.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/delete.l,v 1.4 1998/06/24 13:21:25 momjian Exp $
.TH DELETE SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
delete - 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.
.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).
src/man/destroydb.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/destroydb.1,v 1.12 1998/10/14 02:54:32 momjian Exp $
.TH DESTROYDB UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
destroydb - destroy an existing database
.SH SYNOPSIS
.BR destroydb
[\c
.BR "-i"]
[\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 "-i"
Prompts before destroying a database (interactive).
.TP
.BR "-a" " system"
Specifies an authentication system
.IR "system"
to use in connecting to the
.IR postmaster
process. This option no longer has any effect.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to using local Unix domain sockets.
.TP
.BR "-p" " port"
Specifies the TCP/IP port or local Unix domain socket file extension
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 the demo database using the postmaster on host eden, port 5000.
destroydb -p 5000 -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"
drop_database(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.
.SH NOTE
The command internally runs \fIdrop database\fP from \fIpsql\fP
connected to the \fItemplate1\fP database to perform the operation.
src/man/destroyuser.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/destroyuser.1,v 1.12 1998/10/14 02:54:33 momjian Exp $
.TH DESTROYUSER UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
destroyuser - 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_shadow\*(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"
to use in connecting to the
.IR postmaster
process. This option no longer has any effect.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to using local Unix domain sockets.
.TP
.BR "-p" " port"
Specifies the TCP/IP port or local Unix domain socket file extension
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"
drop_user(l),
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_shadow\*(rq"
You do not have a valid entry in the relation \*(lqpg_shadow\*(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_shadow\*(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.
.SH NOTE
The command internally runs \fIdrop user\fP from \fIpsql\fp connected
to the \fItemplate1\fP database to perform the operation.
src/man/drop.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop.l,v 1.6 1998/06/23 17:52:34 momjian Exp $
.TH "DROP ATTRIBUTE" SQL 09/26/97 PostgreSQL
.SH NAME
drop - destroy existing attributes
.SH SYNOPSIS
.nf
\fBdrop {aggregate|database|function|index|operator
|rule|sequence|table|trigger|type|view}\fR
.fi
.SH DESCRIPTION
.BR "drop attribute"
removes an attribute from the database.
Refer to a specific man page (e.g. "man drop_table") for details.
.SH "SEE ALSO"
delete(l),
drop_aggregate(l),
drop_database(l),
drop_function(l),
drop_index(l),
drop_operator(l),
drop_rule(l),
drop_sequence(l),
drop_table(l),
drop_trigger(l),
drop_type(l),
drop_view(l).
src/man/drop_aggregate.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_aggregate.l,v 1.5 1998/06/23 17:52:35 momjian Exp $
.TH "DROP AGGREGATE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
drop aggregate - remove the definition of an aggregate
.SH SYNOPSIS
.nf
\fBdrop aggregate\fR aggname aggtype
.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 for type int4
--
drop aggregate avg int4
.fi
.SH "SEE ALSO"
create_aggregate(l).
src/man/drop_database.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_database.l,v 1.4 1998/06/24 13:21:26 momjian Exp $
.TH "DROP DATABASE" SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
drop database - 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.
src/man/drop_function.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_function.l,v 1.4 1998/06/23 17:52:35 momjian Exp $
.TH "DROP FUNCTION" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
drop function - 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.
src/man/drop_index.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_index.l,v 1.4 1998/06/23 17:52:35 momjian Exp $
.TH "DROP INDEX" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
drop index - 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).
src/man/drop_language.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_language.l,v 1.3 1998/06/23 17:52:35 momjian Exp $
.TH "DROP LANGUAGE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
drop language - remove a user-defined procedural language
.SH SYNOPSIS
.nf
\fBdrop procedural language\fR 'lanname'
.fi
.SH DESCRIPTION
.BR "drop procedural language"
will remove the definition of the previously registered PL with the
name
.IR lanname .
.SH EXAMPLE
.nf
--
--this command removes the PL/Sample language
--
drop procedural language 'plsample';
.fi
.SH "SEE ALSO"
create_language(l).
.SH BUGS
No checks are made if functions or trigger procedures registered
in this language still exist. To reenable them without having to
drop and recreate all the functions, the pg_proc's prolang attribute
of the functions must be adjusted to the new object ID of the
recreated pg_language entry for the PL.
src/man/drop_operator.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_operator.l,v 1.4 1998/06/23 17:52:36 momjian Exp $
.TH "DROP OPERATOR" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
drop operator - 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).
src/man/drop_rule.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_rule.l,v 1.4 1999/02/07 22:10:10 wieck Exp $
.TH "DROP RULE" SQL 11/05/95 PostgreSQL PostgreSQL
.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),
drop_trigger(l).
src/man/drop_sequence.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_sequence.l,v 1.2 1998/01/11 22:17:31 momjian Exp $
.TH "DROP TABLE" SQL 04/01/97 PostgreSQL PostgreSQL
.SH NAME
drop sequence - destroy existing sequence
.SH SYNOPSIS
.nf
\fBdrop sequence\fR sequence_name_1 { \fB,\fR sequence_name_N }
.fi
.SH DESCRIPTION
.BR "Drop Sequence"
removes sequence number generators from the data base.
With current implementation of sequences as special tables it
works just like \fBdrop table\fR(l).
src/man/drop_table.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_table.l,v 1.4 1998/06/24 13:21:26 momjian Exp $
.TH "DROP TABLE" SQL 09/26/97 PostgreSQL
.SH NAME
drop table - 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 reversible. 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_aggregate(l),
drop_database(l),
drop_function(l),
drop_index(l),
drop_operator(l),
drop_rule(l),
drop_sequence(l),
drop_trigger(l),
drop_type(l),
drop_view(l).
src/man/drop_trigger.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_trigger.l,v 1.4 1998/06/23 17:52:36 momjian Exp $
.TH "DROP TRIGGER" SQL 09/26/97 PostgreSQL
.SH NAME
drop trigger - destroy existing trigger
.SH SYNOPSIS
.nf
\fBdrop trigger\fR trigname \fBon\fR relname
.fi
.SH DESCRIPTION
.BR "Drop Trigger"
removes trigger for relation from the data base. Only relation owner may destroy a
trigger.
.SH EXAMPLE
.nf
--
--Destroy the empverify trigger on relation emp
--
drop trigger empverify on emp
.fi
.SH "SEE ALSO"
create_trigger(l).
src/man/drop_type.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_type.l,v 1.7 1998/10/14 02:54:35 momjian Exp $
.TH "DROP TYPE" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
drop type - 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"
create_type(l),
drop_operator(l).
.SH "BUGS"
If a built-in type is removed, the behavior of the backend is unpredictable.
src/man/drop_user.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_user.l,v 1.2 1998/06/24 13:21:26 momjian Exp $
.TH "DROP USER" SQL 01/26/98 PostgreSQL PostgreSQL
.SH NAME
drop user -- drop user from within a PostgreSQL instance
.SH SYNOPSIS
.nf
\fBdrop user\fR username
.fi
.SH DESCRIPTION
.BR "drop user"
statement removes the named user from a PostgreSQL instance, along with
any databases owned by the user. It does not remove tables, views, or
triggers owned by the named user in database not owned by the user. This
statement can be used in the place of destroyuser(1), regardless of how
the user was created.
.SH EXAMPLES
.nf
---
--- Drop a user
---
drop user tab;
.fi
.SH "SEE ALSO"
alter_user(l), create_user(l).
src/man/drop_view.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_view.l,v 1.4 1998/06/24 13:21:26 momjian Exp $
.TH "DROP VIEW" SQL 04/25/94 PostgreSQL PostgreSQL
.SH NAME
drop view - 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).
src/man/ecpg.1 deleted 100644 → 0
View file @ d0a19198
.TH ECPG UNIX 11/28/98 PostgreSQL \fIPostgreSQL\fP
.SH NAME
ecpg - embedded SQL preprocessor for C / PostgreSQL
.SH SYNOPSIS
.\" \fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ]
\fBecpg\fR [-v ] [-t] [-I include-path ] [-o outfile ] file1 [ file2 ] [ ... ]
.SH DESCRIPTION
.B \fIecpg\fP
is an embedded SQL preprocessor for C / PostgreSQL. It
enables development of C programs with embedded SQL code.
.PP
.B \fIecpg\fP
is ultimately intended to be as compliant as possible with the
ANSI SQL-2 standard and existing commercial ESQL/C packages.
.SH OPTIONS
.B \fIecpg\fP
interprets the following flags when it is invoked
on the command line:
.PP
.PD 0
.TP 10
.BI \-v
Print version information.
.PD
.TP
.B \-t
Turn off auto-transactin mode.
.PD
.TP
.PD
.TP
.B \-I include-path
Specify additional include path. Defaults are \.,
/usr/local/include, the PostgreSQL include path which is defined at compile
time (default: /usr/local/pgsql/lib), /usr/include
.PD
.TP
.B \-o
Specifies that ecpg should write all its output to outfile.
If no such option is given the output is written to foo.c
(if the input file was named foo.pgc.)
If the input file was named foo.bar the output file will be
named foo.bar.c.
.PD
.TP
.B file1, file2...
The files to be processed.
.\"
.SH INSTALLATION
The
.B \fIecpg\fP
preprocessor is built during the PostgreSQL installation. Binaries and
libraries are installed into the PGBASE (i.e., /usr/local/pgsql/... )
subdirectories.
.SH PREPROCESSING FOR COMPILATION
.B \fIecpg\fP
.\" (-d ) (-o file) file.pgc ( 2> ecpf.log)
(-o file) file.pgc
.LP
.\" The optional \-d flag turns on debugging and 2> ecpg.log
.\" redirects the debug output. The .pgc extension is an
.\" arbitrary means of denoting ecpg source.
The .pgc extension is an arbitrary means of denoting ecpg source.
.SH COMPILING AND LINKING
Assuming the \fIPostgreSQL\fP binaries are in /usr/local/pgsql:
.LP
gcc -g -i /usr/local/pgsql/include (-o file) file.c
-L /usr/local/pgsql/lib -lecpg -lpq
.SH ECPG GRAMMAR
.LP
.SH LIBRARIES
.LP
The preprocessor will prepend two directives to the source:
.LP
\fI#include <ecpgtype.h>\fP and \fI#include <ecpglib.h>\fP
.SH VARIABLE DECLARATION
Variables declared within ecpg source code must be prepended with:
.LP
EXEC SQL BEGIN DECLARE SECTION;
.LP
Similarly, variable declaration sections must terminate with:
.LP
EXEC SQL END DECLARE SECTION;
.LP
NOTE: prior to version 2.1.0, each variable had to be declared
on a separate line. As of version 2.1.0 multiple variables may
be declared on a single line:
.LP
char foo(16), bar(16);
.LP
.SH ERROR HANDLING
The SQL communication area is defined with:
.LP
EXEC SQL INCLUDE sqlca;
.LP
NOTE: the lowercase `sqlca'. While SQL convention may be
followed, i.e., using uppercase to separate embedded SQL
from C statements, sqlca (which includes the sqlca.h
header file) MUST be lowercase. This is because the EXEC SQL
prefix indicates that this INCLUDE will be parsed by ecpg.
ecpg observes case sensitivity (SQLCA.h will not be found.)
EXEC SQL INCLUDE can be used to include other header files
as long as case sensitivity is observed.
.LP
The sqlprint command is used with the EXEC SQL WHENEVER
statement to turn on error handling throughout the
program:
.LP
EXEC SQL WHENEVER sqlerror sqlprint;
.LP
EXEC SQL WHENEVER not found sqlprint;
.LP
PLEASE NOTE: this is *not* an exhaustive example of usage for
the EXEC SQL WHENEVER statement. Further examples of usage may
be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by
Groff and Weinberg.)
.LP
.SH CONNECTING TO THE DATABASE SERVER
Prior to version 2.1.0 the database name was single quoted:
.RS
EXEC SQL CONNECT 'test1';
.RE
.LP
As of version 2.1.0, the syntax has been simplified:
.LP
.RS
EXEC SQL CONNECT test1;
.RE
(The database name is no longer quoted.)
.LP
Specifying a server and port name in the connect statement is also possible
as of version 6.4. of PostgreSQL. The syntax is:
.LP
.RS
dbname[@server][:port]
.RE
.LP
or
.LP
.RS
<tcp|unix>:postgresql://server[:port][/dbname][?options]
.RE
.SH QUERIES
.LP
.SS Create Table:
.LP
EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
.RS
EXEC SQL CREATE UNIQUE index num1 on foo(number);
.RE
EXEC SQL COMMIT;
.LP
.SS Insert:
.LP
EXEC SQL INSERT INTO foo (number, ascii)
.RS
VALUES (9999, 'doodad');
.RE
EXEC SQL COMMIT;
.LP
.SS Delete:
.LP
EXEC SQL DELETE FROM foo
.RS
WHERE number = 9999;
.RE
EXEC SQL COMMIT;
.LP
.SS Singleton Select:
.LP
EXEC SQL SELECT foo INTO :FooBar FROM table1
.RS
WHERE ascii = 'doodad';
.RE
.LP
.SS Select using Cursors:
.LP
EXEC SQL DECLARE foo_bar CURSOR FOR
.RS
SELECT number, ascii FROM foo
.RS
ORDER BY ascii;
.RE
.RE
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
.LP
...
EXEC SQL CLOSE foo_bar;
.RS
EXEC SQL COMMIT;
.RE
.LP
.SS Updates
.LP
EXEC SQL UPDATE foo
.RS
SET ascii = 'foobar'
.RE
.RS
WHERE number = 9999;
.RE
EXEC SQL COMMIT;
.LP
.SH BUGS
.LP
The is no EXEC SQL PREPARE statement.
.LP
The complete structure definition MUST be listed
inside the declare section.
.LP
See the TODO file in the source for some more missing features.
.LP
.SH "RETURN VALUE"
.LP
ecpg returns 0 to the shell on successful completion, -1
for errors.
.LP
.SH "SEE ALSO"
.PD 0
.TP
\fIcc\fP(1), \fIpgintro\fP(l), \fIcommit\fP(l), \fIdelete\fP(l)
.TP
\fIfetch\fP(l), \fIselect\fP(l), \fIsql\fP(l) , \fIupdate\fP(l)
.PD
.SH FILES
.PD 0
.TP
.B /usr/src/pgsql/postgresql-${ver}/src/interfaces...
./ecpg/include.......source for \fIecpg\fP header files.
./ecpg/lib...........source for \fIecpg\fP libraries.
./ecpg/preproc.......source for \fIecpg\fP header files.
./ecpg/test..........source for \fIecpg\fP libraries.
(test contains examples of syntax for ecpg SQL-C.)
.PD
.TP
.B /usr/local/pgsql/bin
\fIPostgreSQL\fP binaries including \fIecpg\fP.
.PD
.TP
.B /usr/local/pgsql/include
\fIPostgreSQL\fP headers including \fIecpglib.h\fP \fIecpgtype.h\fP
and \fIsqlca.h\fP.
.PD
.TP
.B /usr/local/pgsql/lib
\fIPostgreSQL\fP libraries including \fIlibecpg.a\fP and
\fIlibecpg.so\fP.
.SH AUTHORS
Linus Tolke \fI<linus@epact.se>\fP
- original author of ECPG (up to version 0.2).
.br
.PP
Michael Meskes \fI<meskes@debian.org>\fP
- actual author and maintainer of ECPG.
.br
.PP
Thomas Good \fI<tomg@q8.nrnet.org>\fP
- author of this revision of the ecpg man page.
.br
.zZ
\ No newline at end of file
src/man/end.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/end.l,v 1.4 1998/03/25 01:54:52 momjian Exp $
.TH END SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
end - 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"
rollback(l),
begin(l).
src/man/explain.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/explain.l,v 1.12 1999/05/17 17:03:51 momjian Exp $
.TH EXPLAIN SQL 06/12/97 PostgreSQL PostgreSQL
.SH NAME
explain - explains statement execution details
.SH SYNOPSIS
.nf
\fBexplain [verbose]\fR query
.fi
.SH DESCRIPTION
This command outputs details about the supplied query. The default
output is the computed query cost. The cost value is only meaningful to
the optimizer in comparing various query plans. \f2verbose\f1 displays
the full query plan and cost to your screen, and pretty-prints the plan
to the postmaster log file.
.SH EXAMPLES
In the examples, the table has a single column of float4.
\fBcost\fR is the cost of scanning a base/join relation,
\fBrows\fR is the expected number of rows from a scan,
\fBwidth\fR is the length of a tuple.
.nf
tgl=> explain select a from test\g
NOTICE:QUERY PLAN:
Seq Scan on test (cost=0.00 rows=0 width=4)
EXPLAIN
tgl=> explain verbose select sum(a) from test;
NOTICE:QUERY PLAN:
{AGG :cost 0 :size 0 :width 0 :state <> :qptargetlist
({TLE :resdom {RESDOM :resno 1 :restype 700 :restypmod 4 :resname "sum"
:reskey 0 :reskeyop 0 :resjunk false}
:expr {AGGREG :aggname "sum" :basetype 700 :aggtype 700 :aggno 0
:target {VAR :varno 1 :varattno 1 :vartype 700 :varnoold 1 :varoattno 1}}})
:qpqual <> :lefttree {SEQSCAN :cost 0 :size 0 :width 4 :state <>
:qptargetlist ({TLE :resdom {RESDOM :resno 1 :restype 700 :restypmod 4
:resname "null" :reskey 0 :reskeyop 0 :resjunk false}
:expr {VAR :varno 1 :varattno 1 :vartype 700 :varnoold 1 :varoattno 1}})
:qpqual <> :lefttree <> :righttree <> :scanrelid 1} :righttree <> :numagg 1 }
Aggregate (cost=0.00 rows=0 width=0)
-> Seq Scan on test (cost=0.00 rows=0 width=4)
.fi
The Postgres optimizer has chosen to use a sequential scan to retrieve rows from
this table. Indices will used by the optimizer
after tables grow large enough to warrant the access
overhead; typically this might happen when tables have a few hundred rows.
.SH "SEE ALSO"
delete(l),
insert(l),
select(l).
.SH BUGS
.PP
The query cost and plan can be affected by running vacuum.
src/man/fetch.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/fetch.l,v 1.7 1998/06/24 13:21:26 momjian Exp $
.TH FETCH SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
fetch - 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 commit(l)
because the data that they store spans multiple user queries.
.SH EXAMPLE
.nf
--
--set up and use a cursor
--
begin work;
declare mycursor cursor for
select * from pg-user;
--
--Fetch all the instances available in the cursor FOO
--
fetch all in FOO;
--
--Fetch 5 instances backward in the cursor FOO
--
fetch backward 5 in FOO;
--
--close
--
close foo;
commit;
.fi
.SH "SEE ALSO"
begin(l),
commit(l),
close(l),
move(l),
select(l).
src/man/grant.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/grant.l,v 1.5 1998/06/24 13:21:26 momjian Exp $
.TH GRANT SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
grant - 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, only the table owner has rights.
.SH EXAMPLES
.nf
--
--Example of a grant
--
grant insert
on mytab
to public
.fi
.SH "SEE ALSO"
revoke(l).
src/man/initdb.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" $Header: /cvsroot/pgsql/src/man/Attic/initdb.1,v 1.4 1998/06/24 13:21:26 momjian Exp $
.TH INITDB UNIX 11/29/96 PostgreSQL PostgreSQL
.SH NAME
initdb - create a new Postgres database system
.SH SYNOPSIS
.BR "initdb"
[\c
.BR "--pglib="\c
.IR "directory"\c
]
[\c
.BR "--pgdata="\c
.IR "directory"\c
]
[\c
.BR "--username="\c
.IR "username"\c
]
[\c
.BR "--template"\c
]
[\c
.BR "--noclean"\c
]
[\c
.BR "--debug"\c
]
.BR "initdb"
[\c
.BR "-l"
.IR "directory"\c
]
[\c
.BR "-r"
.IR "directory"\c
]
[\c
.BR "-u"
.IR "username"\c
]
[\c
.BR "-t"\c
]
[\c
.BR "-n"\c
]
[\c
.BR "-d"\c
]
.SH DESCRIPTION
.IR Initdb
Creates a new Postgres database system. A database system is a
collection of databases that are all administered by the same Unix user
and managed by a single postmaster.
.PP
Creating a database system consists of creating the directories in which
the database data will live, generating the shared catalog tables
(tables that don't belong to any particular database), and
creating the
.IR template1
database. What is the
.IR template1
database? When you create a database, Postgres does it by copying
everything from the
.IR template1
database. It contains catalog tables filled in for things like the
builtin types.
.PP
After
.IR initdb
creates the database, it
.BR vacuum 's
it.
.PP
There are 3 ways to give parameters to
.IR initdb .
First, you can use initdb command options. Second, you can set environment
variables before invoking initdb. Third, you can have a program called
.IR postconfig
in your Unix command search path.
.IR Initdb
invokes that program and the program writes
.IR initdb
parameters to its standard output stream.
.PP
Command options always override parameters specified any other way.
The values returned by
.IR postconfig
override any environment variables, but your
.IR postconfig
program may base its output on the environment variables if you want
their values to be used.
.PP
The value that
.IR postconfig
outputs must have the format
.PP
var1=value1 var2=value2 ...
.PP
It can output nothing if it doesn't want to supply any parameters.
The "varN" values are equal to the corresponding environment variable
names. For example, outputting "PGDATA=/tmp/postgres_test" has the
same effect as invoking
.IR initdb
with an environment variable called "PGDATA" whose value is
"/tmp/postgres_test".
.PP
There are 3 parameters you must supply to initdb to tell it how to
create the database system:
.PP
1) Where are the files that make up Postgres? Apart from files that
have to go in particular directories because of their function, the
files that make up the Postgres software were installed in a directory
called the "pglib" directory. An example of a file that will be found
there that
.IR initdb
needs is global1.bki.source, which contains all the information that goes
into the shared catalog tables. Use the
.BR --pglib
(\c
.BR -l )
option or the
.BR PGLIB
environment variable.
.PP
2) Where in your Unix filesystem do you want the database data to go?
The top level directory is called the "pgdata" directory. Use the
.BR --pgdata
(\c
.BR -d )
option or the
.BR PGDATA
environment variable.
.PP
3) Who will be the Postgres superuser for this database system? The
Postgres superuser is a Unix user that owns all files that store the database
system and also owns the postmaster and backend processes that access them.
Use the
.BR --username
(\c
.BR -u )
option or the
.BR PGUSER
environment variable. Or just let it default to you (the Unix user who
runs
.IR initdb ).
Note that only the Unix superuser can create a database system with a
different user as Postgres superuser.
.PP
.IR Initdb
understands the following command-line options:
.BR "--pglib="\c
.IR "directory"
.BR "-l"
.IR "directory"
Use the Postgres files in the specified directory, as explained above.
.BR "--pgdata="\c
.IR "directory"
.BR "-r"
.IR "directory"
Put the database system in this directory, as explained above.
.BR "--username="\c
.IR "username"
.BR "-u"
.IR "username"
Build the database system with the specified Unix user as the Postgres
superuser for it, as explained above.
.BR "--template"
.BR "-t"
Replace the
.IR template1
database in an existing database system, and don't touch anything else.
This is useful when you need to upgrade your
.IR template1
database using
.IR initdb
from a newer release of Postgres, or when your
.IR template1
database has become corrupted by some system problem. Normally the
contents of
.IR template1
remain constant throughout the life of the database system. You can't
destroy anything by running
.IR initdb
with the
.BR --template
option.
.BR "--noclean"
.BR "-n"
Run in \*(lqnoclean\*(rq mode. By default,
when
.IR initdb
determines that error prevent it from completely creating the database
system, it removes any files it may have created before determining
that it can't finish the job. That includes any core files left by
the programs it invokes. This option inhibits any tidying-up and is
thus useful for debugging.
.BR "--debug"
.BR "-d"
Print debugging output from the bootstrap backend.
The bootstrap backend is the program
.IR initdb
uses to create the catalog tables. This option generates a tremendous
amount of output. It also turns off the final vacuuming step.
.SH FILES
.TP
postconfig
(Somewhere in the Unix command search path (defined by the PATH environment
variable)). This is a program that specifies defaults for some of the
command options. See above.
.TP
PGLIB/global1.bki.source
Contents for the shared catalog tables in the new database system. This
file is part of the Postgres software.
.TP
PGLIB/local1_template1.bki.source
Contents for the template1 tables in the new database system. This
file is part of the Postgres software.
.SH "SEE ALSO"
vacuum(l),
bki(5),
create_database(l),
createuser(1),
psql(1).
src/man/initlocation.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" $Header: /cvsroot/pgsql/src/man/Attic/initlocation.1,v 1.2 1998/01/11 22:17:38 momjian Exp $
.TH INITDB UNIX 11/05/97 PostgreSQL
.SH NAME
initlocation - create a new Postgres storage area
.SH SYNOPSIS
.BR "initlocation"
.IR "directory"
.PP
.BR "initlocation"
.IR "$environment_variable"
.SH DESCRIPTION
.IR initlocation
creates a new Postgres database storage area. A storage area contains
distinct Postgres databases, with each database in a separate directory
and managed by a single postmaster.
.PP
Creating a database storage area consists of creating the directories in which
the database data will live.
There are 2 types of arguments for
.IR initlocation .
First, you can specify an explicit
absolute path to the top directory of the storage area.
Second, you can specify an environment variable (e.g. $PGDATA2).
This environment variable should be known to the backend for later use in
.IR "create database" .
In either case Postgres will add /base/
to the specified path to create the storage area.
.SH "SEE ALSO"
create_database(l),
initdb(1).
src/man/insert.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/insert.l,v 1.12 1998/10/14 02:54:36 momjian Exp $
.TH INSERT SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
insert - 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 [distinct]
expression1 [,expression-i]
[\fBfrom\fR from-list] [\fBwhere\fR qual]
[\fBgroup by\fR attr_name1 {, attr_name-i....}]
[\fBunion {all} select\fR ...]
.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.
.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.
.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)
src/man/ipcclean.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/ipcclean.1,v 1.3 1998/01/11 22:17:40 momjian Exp $
.TH IPCCLEAN UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
ipcclean - 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.
src/man/libpq.3 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.27 1999/05/21 00:36:01 tgl Exp $
.TH LIBPQ INTRO 08/08/98 PostgreSQL PostgreSQL
.SH DESCRIPTION
Current documentation for this topic is available in the new Programmer's Guide
chapter on libpq.
This man page is obsolete, though in sync with the Programmer's Guide as of 1998/08/15.
.PP
Libpq is the programmer's interface to Postgres. Libpq is a set of
library routines which allows
client programs to pass queries to the Postgres backend
server and to receive the results of these queries.
.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.
If it is set to a non-zero-length string, it causes TCP/IP
communication to be used, rather than the default local Unix domain sockets.
.sp
\(bu
.B PGUSER
sets the username used to connect to the database and for authentication.
.sp
\(bu
.B PGOPTIONS
sets additional runtime options for the Postgres backend.
.sp
\(bu
.B PGPORT
sets the default port or local Unix domain socket file extension
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.
.PP
The following environment variables can be used to specify user-level default behavior
for every Postgres session:
.sp
\(bu
.B PGDATESTYLE
sets the default style of date/time representation.
.sp
\(bu
.B PGTZ
sets the default time zone.
.PP
The following environment variables can be used to specify default internal
behavior for every Postgres session:
.sp
\(bu
.B PGGEQO
sets the default mode for the genetic optimizer.
.sp
\(bu
.B PGRPLANS
sets the default mode to allow or disable right-sided plans in the optimizer.
.sp
\(bu
.B PGCOSTHEAP
sets the default cost for heap searches for the optimizer.
.sp
\(bu
.B PGCOSTINDEX
sets the default cost for indexed searches for the optimizer.
\(bu
.B PGQUERY_LIMIT
sets the maximum number of rows returned by a query.
.sp
.PP
See the
set(l)
man page for information on the arguments for these environment variables.
.SH "Database Connection Functions"
.PP
The following routines deal with making a connection to a backend
from a C program.
.PP
.B PQsetdb
.br
.B PQsetdbLogin
.IP
Makes a new connection to a backend.
.B PQsetdb
is the method usually used to
connect to the database when username/password authentication is not
needed.
.nf
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
.fi
.IP
.B PQsetdbLogin
is the method used to
connect to the database when username/password authentication is
needed.
.nf
PGconn *PQsetdbLogin(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName,
char *login,
char *pwd);
.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
and
.I PQsetdbLogin
always return 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
.SH "Query Execution Functions"
.PP
.B PQexec
.IP
Submit a query to Postgres. Returns a PGresult
pointer or possibly a NULL pointer. If a NULL is returned, it
should be treated like a PGRES_FATAL_ERROR result: use
.I PQerrorMessage
to get more information about the error.
.nf
PGresult *PQexec(PGconn *conn,
const 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 returning no data */
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
routines described below can be used to retrieve the
tuples returned by the query. Note that a SELECT that
happens to retrieve zero tuples still shows PGRES_TUPLES_OK.
PGRES_COMMAND_OK is for commands that can never return tuples.
.PP
.B PQresStatus
.IP
Converts the enumerated type returned by PQresultStatus into
a string constant describing the status code.
.nf
const char *PQresStatus(ExecStatusType status);
.fi
.IP
Older code may perform this same operation by direct access to a constant
string array inside libpq,
.nf
extern const char * const pgresStatus[];
.fi
.IP
However, using the function is recommended instead, since it is more portable
and will not fail on out-of-range values.
.PP
.B PQresultErrorMessage
.IP
returns the error message associated with the query, or an empty string
if there was no error.
.nf
const char *PQresultErrorMessage(PGresult *res);
.fi
.IP
Immediately following a PQexec or PQgetResult call, PQerrorMessage
(on the connection) will return the same string as PQresultErrorMessage
(on the result). However, a PGresult will retain its error message
until destroyed, whereas the connection's error message will change when
subsequent operations are done. Use PQresultErrorMessage when you want to
know the status associated with a particular PGresult; use PQerrorMessage
when you want to know the status from the latest operation on the connection.
.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
short PQfsize(PGresult *res,
int field_index);
.fi
.B PQfmod
returns the type-specific modification data of the field
associated with the given field index.
Field indices start at 0.
.nf
int PQfmod(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 PQcmdTuples
.IP
Returns the number of tuples (instances) affected by INSERT, UPDATE, and
DELETE queries.
.nf
char *PQcmdTuples(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 "Asynchronous Query Processing"
.PP
The PQexec function is adequate for submitting queries in simple synchronous
applications. It has a couple of major deficiencies however:
.IP
PQexec waits for the query to be completed. The application may have other
work to do (such as maintaining a user interface), in which case it won't
want to block waiting for the response.
.IP
Since control is buried inside PQexec, it is hard for the frontend
to decide it would like to try to cancel the ongoing query. (It can be
done from a signal handler, but not otherwise.)
.IP
PQexec can return only one PGresult structure. If the submitted query
string contains multiple SQL commands, all but the last PGresult are
discarded by PQexec.
.PP
Applications that do not like these limitations can instead use the
underlying functions that PQexec is built from: PQsendQuery and
PQgetResult.
.PP
.B PQsendQuery
.IP
Submit a query to Postgres without
waiting for the result(s). TRUE is returned if the query was
successfully dispatched, FALSE if not (in which case, use
PQerrorMessage to get more information about the failure).
.nf
int PQsendQuery(PGconn *conn,
const char *query);
.fi
After successfully calling PQsendQuery, call PQgetResult one or more
times to obtain the query results. PQsendQuery may not be called
again (on the same connection) until PQgetResult has returned NULL,
indicating that the query is done.
.PP
.B PQgetResult
.IP
Wait for the next result from a prior PQsendQuery,
and return it. NULL is returned when the query is complete
and there will be no more results.
.nf
PGresult *PQgetResult(PGconn *conn);
.fi
PQgetResult must be called repeatedly until it returns NULL,
indicating that the query is done. (If called when no query is
active, PQgetResult will just return NULL at once.)
Each non-null result from PQgetResult should be processed using
the same PGresult accessor functions previously described.
Don't forget to free each result object with PQclear when done with it.
Note that PQgetResult will block only if a query is active and the
necessary response data has not yet been read by PQconsumeInput.
.PP
Using PQsendQuery and PQgetResult solves one of PQexec's problems:
if a query string contains multiple SQL commands, the results of those
commands can be obtained individually. (This allows a simple form of
overlapped processing, by the way: the frontend can be handling the
results of one query while the backend is still working on later
queries in the same query string.) However, calling PQgetResult will
still cause the frontend to block until the backend completes the
next SQL command. This can be avoided by proper use of three more
functions:
.PP
.B PQconsumeInput
.IP
If input is available from the backend, consume it.
.nf
void PQconsumeInput(PGconn *conn);
.fi
No direct return value is available from PQconsumeInput, but
after calling it, the application may check PQisBusy and/or
PQnotifies to see if their state has changed.
PQconsumeInput may be called even if the application is not
prepared to deal with a result or notification just yet.
It will read available data and save it in a buffer, thereby
causing a select(2) read-ready indication to go away. The
application can thus use PQconsumeInput to clear the select
condition immediately, and then examine the results at leisure.
.PP
.B PQisBusy
.IP
Returns TRUE if a query is busy, that is, PQgetResult would block
waiting for input. A FALSE return indicates that PQgetResult can
be called with assurance of not blocking.
.nf
int PQisBusy(PGconn *conn);
.fi
PQisBusy will not itself attempt to read data from the backend;
therefore PQconsumeInput must be invoked first, or the busy
state will never end.
.PP
.B PQsocket
.IP
Obtain the file descriptor number for the backend connection socket.
A valid descriptor will be >= 0; a result of -1 indicates that
no backend connection is currently open.
.nf
int PQsocket(PGconn *conn);
.fi
PQsocket should be used to obtain the backend socket descriptor
in preparation for executing select(2). This allows an application
to wait for either backend responses or other conditions.
If the result of select(2) indicates that data can be read from
the backend socket, then PQconsumeInput should be called to read the
data; after which, PQisBusy, PQgetResult, and/or PQnotifies can be
used to process the response.
.PP
A typical frontend using these functions will have a main loop that uses
select(2) to wait for all the conditions that it must respond to. One of
the conditions will be input available from the backend, which in select's
terms is readable data on the file descriptor identified by PQsocket.
When the main loop detects input ready, it should call PQconsumeInput
to read the input. It can then call PQisBusy, followed by PQgetResult
if PQisBusy returns FALSE. It can also call PQnotifies to detect NOTIFY
messages (see "Asynchronous Notification", below).
.PP
A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel
a query that is still being processed by the backend.
.PP
.B PQrequestCancel
.IP
Request that <ProductName>Postgres</ProductName> abandon
processing of the current query.
.nf
int PQrequestCancel(PGconn *conn);
.fi
The return value is TRUE if the cancel request was successfully
dispatched, FALSE if not. (If not, PQerrorMessage tells why not.)
Successful dispatch is no guarantee that the request will have any
effect, however. Regardless of the return value of PQrequestCancel,
the application must continue with the normal result-reading
sequence using PQgetResult. If the cancellation
is effective, the current query will terminate early and return
an error result. If the cancellation fails (say because the
backend was already done processing the query), then there will
be no visible result at all.
.PP
Note that if the current query is part of a transaction, cancellation
will abort the whole transaction.
.PP
PQrequestCancel can safely be invoked from a signal handler. So, it is
also possible to use it in conjunction with plain PQexec, if the decision
to cancel can be made in a signal handler. For example, psql invokes
PQrequestCancel from a SIGINT signal handler, thus allowing interactive
cancellation of queries that it issues through PQexec. Note that
PQrequestCancel will have no effect if the connection is not currently open
or the backend is not currently processing a query.
.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 no 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
notification condition with the LISTEN command. All backends listening on a
particular condition will be notified asynchronously when a NOTIFY of that
condition name is executed by any 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 a database relation.
Commonly the condition name is the same as the associated relation, but it is
not necessary for there to be any associated relation.
.PP
libpq applications submit LISTEN commands as ordinary
SQL queries. Subsequently, arrival of NOTIFY messages can be detected by
calling PQnotifies().
.PP
.B PQNotifies
.IP
Returns the next notification from a list of unhandled
notification messages received from the backend. Returns NULL if
there are no pending notifications. PQnotifies behaves like the
popping of a stack. Once a notification is returned from
PQnotifies, it is considered handled and will be removed from the
list of notifications.
.nf
PGnotify* PQNotifies(PGconn *conn);
.fi
After processing a PGnotify object returned by PQnotifies,
be sure to free it with free() to avoid a memory leak.
.PP
The second sample program gives an example of the use of asynchronous
notification.
.PP
PQnotifies() does not actually read backend data; it just returns messages
previously absorbed by another libpq function. In prior
releases of libpq, the only way to ensure timely receipt
of NOTIFY messages was to constantly submit queries, even empty ones, and then
check PQnotifies() after each PQexec(). While this still works, it is
deprecated as a waste of processing power. A better way to check for NOTIFY
messages when you have no useful queries to make is to call PQconsumeInput(),
then check PQnotifies(). You can use select(2) to wait for backend data to
arrive, thereby using no CPU power unless there is something to do. Note that
this will work OK whether you use PQsendQuery/PQgetResult or plain old PQexec
for queries. You should, however, remember to check PQnotifies() after each
PQgetResult or PQexec to see if any notifications came in during the
processing of the query.
.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
These functions should be executed only after obtaining a PGRES_COPY_OUT
or PGRES_COPY_IN result object from PQexec or PQgetResult.
.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 two characters \*(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 two characters \*(lq\\.\*(rq
on a final line
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 char(16), d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3\ethello world\et4.5\en");
PQputline(conn,"4\etgoodbye world\et7.11\en");
\&...
PQputline(conn,"\e\e.\en");
PQendcopy(conn);
.fi
.PP
When using PQgetResult, the application should respond to
a PGRES_COPY_OUT result by executing PQgetline repeatedly,
followed by PQendcopy after the terminator line is seen.
It should then return to the PQgetResult loop until PQgetResult
returns NULL. Similarly a PGRES_COPY_IN result is processed
by a series of PQputline calls followed by PQendcopy, then
return to the PQgetResult loop. This arrangement will ensure that
a copy in or copy out command embedded in a series of SQL commands
will be executed correctly.
Older applications are likely to submit a copy in or copy out
via PQexec and assume that the transaction is done after PQendcopy.
This will work correctly only if the copy in/out is the only
SQL command in the query string.
.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 "LIBPQ Control Functions"
.PP
.B PQsetNoticeProcessor
.IP
Control reporting of notice and warning messages generated by libpq.
.nf
void PQsetNoticeProcessor (PGconn * conn,
void (*noticeProcessor) (void * arg, const char * message),
void * arg)
.fi
By default, libpq prints "notice" messages from the backend on stderr,
as well as a few error messages that it generates by itself.
This behavior can be overridden by supplying a callback function that
does something else with the messages. The callback function is passed
the text of the error message (which includes a trailing newline), plus
a void pointer that is the same one passed to PQsetNoticeProcessor.
(This pointer can be used to access application-specific state if needed.)
The default notice processor is simply
.nf
static void
defaultNoticeProcessor(void * arg, const char * message)
{
fprintf(stderr, "%s", message);
}
.fi
To use a special notice processor, call PQsetNoticeProcessor just after
any creation of a new PGconn object.
.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 authentication method is now
determined entirely by the DBA (see pga_hba.conf(5)). The following
routines no longer have any effect and should not be used.
.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 rejected.
.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 (!res || 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 (!res || 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 (!res || 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);
/* commit the transaction */
res = PQexec(conn, "COMMIT");
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
*
* Start this program, then from psql in another window do
* NOTIFY TBL2;
*
* Or, if you want to get fancy, try this:
* 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);
*
* and 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 (!res || 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)
{
/* wait a little bit between checks;
* waiting with select() would be more efficient.
*/
sleep(1);
/* collect any asynchronous backend messages */
PQconsumeInput(conn);
/* check for asynchronous notify messages */
while ((notify = PQnotifies(conn)) != NULL) {
fprintf(stderr,
"ASYNC NOTIFY of '%s' from backend pid '%d' received\\n",
notify->relname, notify->be_pid);
free(notify);
}
}
/* 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 (!res || 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 (!res || 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 (!res || 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);
/* commit the transaction */
res = PQexec(conn, "COMMIT");
PQclear(res);
/* close the connection to the database and cleanup */
PQfinish(conn);
}
.fi
src/man/listen.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/listen.l,v 1.9 1998/10/08 01:16:17 tgl Exp $
.TH "LISTEN" SQL 03/12/94 PostgreSQL PostgreSQL
.SH NAME
listen - listen for notification on a relation
.SH SYNOPSIS
.nf
\fBlisten\fR class_name
.fi
.SH DESCRIPTION
This man page is obsolete. More complete and reliable info is
available in the User's Guide reference page for LISTEN.
.PP
.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 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.
.PP
Note that
.IR class_name
needs not to be a valid class name but can be any ascii string up to 32
characters long. It must however be eclosed in double-quotes if it is
not valid as class name.
.SH "SEE ALSO"
create_rule(l),
notify(l),
select(l),
unlisten(l),
libpq.
.SH BUGS
The
.IR psql(1)
command does not poll for asynchronous events.
src/man/load.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/load.l,v 1.4 1998/07/25 00:17:30 momjian Exp $
.TH LOAD SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
load - 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.
src/man/lock.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/lock.l,v 1.9 1999/06/09 03:51:40 vadim Exp $
.TH LOCK SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
lock - Explicit lock of a table inside a transaction
.SH SYNOPSIS
.nf
\fBlock\fR [\fBtable\fR] classname
\fBlock\fR [\fBtable\fR] classname \fBin\fR [\fBrow\fR|\fBaccess\fR] {\fBshare\fR|\fBexclusive\fR} \fBmode\fR
\fBlock\fR [\fBtable\fR] classname \fBin\fR \fBshare row exclusive\fR \fBmode\fR
.fi
.SH DESCRIPTION
Available lock modes from least restrictive to most restrictive:
.PP
\fBACCESS SHARE MODE\fR
\fBNote\fR: this lock mode is acquired automatically over tables being
\queried. \fBPostgres\fR releases automatically acquired
ACCESS SHARE locks after statement is done.
This is the least restrictive lock mode which conflicts with ACCESS EXCLUSIVE
mode only. It's intended to protect table being queried from concurrent
\fBALTER TABLE\fR, \fBDROP TABLE\fR and
\fBVACUUM\fR statements over the same table.
\fBROW SHARE MODE\fR
\fBNote\fR: Automatically acquired by SELECT FOR UPDATE statement.
Conflicts with EXCLUSIVE and ACCESS EXCLUSIVE lock modes.
\fBROW EXCLUSIVE MODE\fR
\fBNote\fR: Automatically acquired by UPDATE, DELETE, INSERT statements.
Conflicts with SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE and ACCESS EXCLUSIVE
modes. Generally means that a transaction updated/inserted some tuples in a
table.
\fBSHARE MODE\fR
\fBNote\fR: Automatically acquired by CREATE INDEX statement.
Conflicts with ROW EXCLUSIVE, SHARE ROW EXCLUSIVE, EXCLUSIVE and ACCESS
EXCLUSIVE modes. This mode protects a table against concurrent updates.
\fBSHARE ROW EXCLUSIVE MODE\fR
Conflicts with ROW EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE and
ACCESS EXCLUSIVE modes. This mode is more restrictive than SHARE mode
because of only one transaction at time can hold this lock.
\fBEXCLUSIVE MODE\fR
Conflicts with ROW SHARE, ROW EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE,
EXCLUSIVE and ACCESS EXCLUSIVE modes. This mode is yet more restrictive than
SHARE ROW EXCLUSIVE one - it blocks concurrent SELECT FOR UPDATE queries.
\fBACCESS EXCLUSIVE MODE\fR
\fBNote\fR: Automatically acquired by ALTER TABLE, DROP TABLE, VACUUM
statements.
This is the most restrictive lock mode which conflicts with all other
lock modes and protects locked table from any concurrent operations.
\fBNote\fR: This lock mode is also acquired by first form of LOCK TABLE
(i.e. without explicit lock mode option).
.SH USAGE
.BR Postgres
always uses less restrictive lock modes ever possible. LOCK TABLE statement
provided for cases when you might need in more restrictive locking.
.PP
For example, application run transaction at READ COMMITTED isolation level
and need to ensure existance data in a table for duration of transaction. To
achieve this you could use SHARE lock mode over table before querying. This
will protect data from concurrent changes and provide your further read
operations over table with data in their real current state, because of
SHARE lock mode conflicts with ROW EXCLUSIVE one, acquired by writers, and
your LOCK TABLE table IN SHARE MODE statement will wait untill concurrent
write operations (if any) commit/rollback. (Note that to read data in their
real current state running transaction at SERIALIZABLE isolation level you
have to execute LOCK TABLE statement before execution any DML statement,
when transaction defines what concurrent changes will be visible to
herself).
If, in addition to requirements above, transaction is going to change data
in a table then SHARE ROW EXCLUSIVE lock mode should be acquired to prevent
deadlock conditions when two concurrent transactions would lock table in
SHARE mode and than would try to change data in this table, both
(implicitly) acquiring ROW EXCLUSIVE lock mode that conflicts with
concurrent SHARE lock.
Following deadlock issue (when two transaction wait one another)
touched above, you should follow two general rules to prevent
deadlock conditions:
\fB1. Transactions have to acquire locks on the same objects in the same order.\fR
For example, if one application updates row R1 and than updates row R2 (in
the same transaction) then second application shouldn't update row R2 if
it's going update row R1 later (in single transaction). Instead, it should
update R1 and R2 rows in the same order as first application.
\fB2. Transactions should acquire two conflicting lock modes only if one of
them is self-conflicting (i.e. may be held by one transaction at time only)
and should acquire most restrictive mode first.\fR
Example for this rule is described above when told about using
SHARE ROW EXCLUSIVE mode instead of SHARE one.
\fBNote\fR: \fBPostgres\fR does detect deadlocks and will rollback one of
waiting transactions to resolve the deadlock.
.SH COMPATIBILITY
LOCK TABLE statement is a \fBPostgres\fR language extension.
Except for ACCESS SHARE/EXCLUSIVE lock modes, all other \fBPostgres\fR lock
modes and LOCK TABLE statement syntax are compatible with \fBOracle\fR
ones.
.SH EXAMPLES
.nf
--
-- SHARE lock primary key table when going to perform
-- insert into foreign key table.
--
BEGIN WORK;
LOCK TABLE films IN SHARE MODE;
SELECT id FROM films
WHERE name = 'Star Wars: Episode I - The Phantom Menace';
--
-- Do ROLLBACK if record was not returned
--
INSERT INTO films_user_comments VALUES
(_id_, 'GREAT! I was waiting it so long!');
COMMIT WORK;
--
-- SHARE ROW EXCLUSIVE lock primary key table when going to perform
-- delete operation.
--
BEGIN WORK;
LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE;
DELETE FROM films_user_comments WHERE id IN
(SELECT id FROM films WHERE rating < 5);
DELETE FROM films WHERE rating < 5;
COMMIT WORK;
.SH "SEE ALSO"
begin(l),
commit(l),
set(l),
select(l).
src/man/move.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/move.l,v 1.3 1998/03/23 15:09:41 momjian Exp $
.TH MOVE SQL 01/23/93 PostgreSQL PostgreSQL
.SH NAME
move - move cursor position
.SH SYNOPSIS
.nf
\fBmove\fR [ (\fBforward\fR | \fBbackward\fR) ] [ ( number | \fBall\fR) ] [\fBin\fR cursor_name]
.fi
.SH DESCRIPTION
.BR Move
allows a user to move cursor position for specified number of instances.
Move works like
.IR fetch
command: it fetches instances, but put them nowhere.
.SH EXAMPLE
.nf
--
--set up and use a cursor
--
begin work;
declare mycursor cursor for
select * from pg-user;
--
--Move for 5 instances in the cursor FOO
--
move 5 in FOO;
--
--Fetch 6th instance in the cursor FOO
--
fetch 1 in FOO;
--
--close
--
close foo;
commit;
.fi
.SH "SEE ALSO"
begin(l),
commit(l),
close(l),
fetch(l),
select(l).
src/man/notify.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/notify.l,v 1.6 1998/10/08 01:16:18 tgl Exp $
.TH "NOTIFY" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
notify - signal all frontends and backends listening on a class
.SH SYNOPSIS
.nf
\fBnotify\fR class_name
.fi
.SH DESCRIPTION
This man page is obsolete. More complete and reliable info is
available in the User's Guide reference page for NOTIFY.
.PP
.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
In fact,
.IR class_name
need not be the name of an SQL class at all. It is best thought of
as a condition name that the application programmer selects.
.PP
This event notification is performed through the Libpq protocol
and frontend application interface. The application program
must 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(3).
src/man/pg_dump.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_dump.1,v 1.17 1999/05/27 16:29:05 momjian Exp $
.TH PG_DUMP UNIX 7/15/98 PostgreSQL PostgreSQL
.SH NAME
pg_dump - dumps out a Postgres database into a script file
.SH SYNOPSIS
.BR pg_dump
[\c
.BR "-a"
]
[\c
.BR "-c"
]
[\c
.BR "-d"
]
[\c
.BR "-D"
]
[\c
.BR "-f"
filename
]
[\c
.BR "-h"
hostname
]
[\c
.BR "-n"
]
[\c
.BR "-o"
]
[\c
.BR "-p"
port]
[\c
.BR "-s"
]
[\c
.BR "-t"
table]
[\c
.BR "-u"
]
[\c
.BR "-v"
]
[\c
.BR "-x"
]
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 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
postgreSQL 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.
.PP
pg_dump understands the following options:
.TP
.BR "-a" ""
Dump out only the data, no schema
.TP
.BR "-c" ""
Clean(drop) schema prior to create
.TP
.BR "-d" ""
Dump data as proper insert strings
.TP
.BR "-D" ""
Dump data as inserts with attribute names
.TP
.BR "-f" " filename"
Specifies the output file
.TP
.BR "-h" " hostname"
Specifies the server host name
.TP
.BR "-n" ""
Suppress most double quotes around identifiers.
.TP
.BR "-o" ""
Dump object id's (oids)
.TP
.BR "-p" " port"
Specifies the server port number
.TP
.BR "-s" ""
Dump out only the schema, no data
.TP
.BR "-t" " table"
Dump for this table only
.TP
.BR "-u"
Use password authentication. Prompts for username and password
.TP
.BR "-v" ""
Specifies verbose mode
.TP
.BR "-x" ""
Prevent dumping of ACLs (grant/revoke commands) and table ownership information
.PP
If dbname is not supplied, then the DATABASE environment variable value is used.
.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 "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.
.SH EXAMPLES
.nf
To dump a database:
pg_dump >db.out
To reload it:
psql -e database <db.out
.SH "SEE ALSO"
copy(l).
src/man/pg_dumpall.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_dumpall.1,v 1.5 1998/06/24 13:21:28 momjian Exp $
.TH pg_dumpall UNIX 1/20/96 PostgreSQL PostgreSQL
.SH NAME
pg_dumpall - dumps out all Postgres databases into a script file
.SH SYNOPSIS
.BR pg_dumpall
[pg_dump options]
.SH DESCRIPTION
.IR "pg_dumpall"
is a utility for dumping out all Postgres databases into one file.
It also dumps the pg_shadow table, which is global to all databases.
pg_dumpall creates each dumped database before loading.
pg_dumpall takes all pg_dump options, but \fB-f\fR and \fBdbname\fR
should not be used.
.SH EXAMPLES
.nf
To dump all databases (you can use pg_dump options):
pg_dumpall -o >db.out
To reload into a fresh installation (you can use psql options):
psql -e template1 <db.out
.fi
.SH "SEE ALSO"
pg_dump(1).
src/man/pg_hba.conf.5 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_hba.conf.5,v 1.7 1998/10/14 02:54:37 momjian Exp $
.TH pg_hba.conf 5 1/26/98 PostgreSQL PostgreSQL
.SH NAME
$PGDATA/pg_hba.conf
.SH DESCRIPTION
"Host-based access control" is the name for the basic controls PostgreSQL
exercises on what clients are allowed to access a database and how
the users on those clients must authenticate themselves.
.PP
Each database system contains a file named "pg_hba.conf", in its $PGDATA
directory, that controls who can connect to each database.
.PP
Every client that wants to access to a database
.IR must
be covered by one of
the entries in pg_hba.conf. Otherwise all attempted connections from that
client will be rejected with a "User authentication failed" error message.
.PP
The general format of the pg_hba.conf file is of a set of records, one per
line. Blank lines and lines beginning with '#' are ignored. A record is
made up of a number of fields which are separated by spaces and/or tabs.
.PP
Connections from clients can be made using UNIX domain sockets or Internet
domain sockets (ie. TCP/IP). Connections made using UNIX domain sockets
are controlled using records of the following format.
.PP
local <database> <authentication method>
.PP
<database> specifies the database that this record applies to. The value
.IR all
specifies that it applies to all databases. <authentication method>
specifies the method a user must use to authenticate themselves when
connecting to that database using UNIX domain sockets. The different methods
are described below.
.PP
Connections made using Internet domain sockets are controlled using records
of the following format.
.PP
host <database> <TCP/IP address> <TCP/IP mask> <authentication method>
.PP
The <TCP/IP mask> is logically anded to both the specified <TCP/IP address>
and the TCP/IP address
of the connecting client. If the two values that result are equal then the
record is used for this connection. If a connection matches more than one
record then the earliest one in the file is used. Both the <TCP/IP address>
and the <TCP/IP mask> are specified in dotted decimal notation.
.PP
If a connection fails to match any record then the
.IR reject
authentication method is applied (see below).
.SH "AUTHENTICATION METHODS"
The following authentication methods are supported for both UNIX and TCP/IP
domain sockets.
.PP
.IR trust
- the connection is allowed unconditionally.
.PP
.IR reject
- the connection is rejected unconditionally.
.PP
.IR crypt
- the client is asked for a password for the user. This is sent encrypted
(using crypt(3)) and compared against the password held in the pg_shadow table.
If the passwords match, the connection is allowed.
.PP
.IR password
- the client is asked for a password for the user. This is sent in clear
and compared against the password held in the pg_shadow table.
If the passwords match, the connection is allowed. An optional password file
may be specified after the
.IR password
keyword which is used to match the supplied password rather than the pg_shadow
table. See pg_passwd(1).
.PP
The following authentication methods are supported for TCP/IP
domain sockets only.
.PP
.IR krb4
- Kerberos V4 is used to authenticate the user.
.PP
.IR krb5
- Kerberos V5 is used to authenticate the user.
.PP
.IR ident
- the ident server on the client is used to authenticate the user (RFC 1413).
An optional map name may be specified after the
.IR ident
keyword which allows ident user names to be mapped onto PostgreSQL user names.
Maps are held in the file $PGDATA/pg_ident.conf.
.SH EXAMPLES
# Trust any connection via UNIX domain sockets.
local trust
# Trust any connection via TCP/IP from this machine.
host all 127.0.0.1 255.255.255.255 trust
# We don't like this machine.
host all 192.168.0.10 255.255.255.0 reject
# This machine can't encrypt so we ask for passwords in clear.
host all 192.168.0.3 255.255.255.0 password
# The rest of this group of machines should provide encrypted passwords.
host all 192.168.0.0 255.255.255.0 crypt
src/man/pg_passwd.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_passwd.1,v 1.4 1998/06/24 13:21:28 momjian Exp $
.TH PG_PASSWD UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
pg_passwd - manipulate the flat password file
.SH SYNOPSIS
.BR "pg_passwd password_file"
.SH DESCRIPTION
.IR Pg_passwd
is a tool to manipulate the
flat password file functionality of PostgreSQL.
Specify the password file in the same style of Ident authentication in
.IR $PGDATA/pg_hba.conf :
.nf
host unv 133.65.96.250 255.255.255.255 password passwd
.fi
The above line allows access from 133.65.96.250 using the passwords listed
in
.IR $PGDATA/passwd .
The format of the password file follows those of
.IR /etc/passwd
and
.IR /etc/shadow .
The first field is the user name, and the second field
is the encrypted password.
The rest is completely ignored.
Thus the following three sample lines specify the same user and password pair:
.nf
pg_guest:/nB7.w5Auq.BY:10031::::::
pg_guest:/nB7.w5Auq.BY:93001:930::/home/guest:/bin/tcsh
pg_guest:/nB7.w5Auq.BY:93001
.fi
Supply the password file to the pg_passwd command.
In the case described above, after
.IR cd "'ing"
to $PGDATA, the following command execution specify
the new password for pg_guest:
.nf
% pg_passwd passwd
Username: pg_guest
Password:
Re-enter password:
.fi
where the
.IR Password:
and
.IR "Re-enter password:"
prompts require the same password input which are not displayed
on the terminal.
The original password file is renamed to
.BR "passwd.bk" .
.PP
.BR "Psql authentication"
uses the
.BR -u
option.
The following lines show the sample usage of the option:
.nf
% psql -h hyalos -u unv
Username: pg_guest
Password:
Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
type \\? for help on slash commands
type \\q to quit
type \\g or terminate with semicolon to execute query
You are currently connected to the database: unv
unv=>
.fi
.BI "Perl5 authentication"
uses the new style of the Pg.pm like this:
.nf
$conn = Pg::connectdb("host=hyalos dbname=unv
user=pg_guest password=xxxxxxx");
.fi
For more details, refer to
.IR src/pgsql_perl5/Pg.pm .
.PP
.BR "Pg{tcl,tk}sh authentication"
uses the
.IR pg_connect
command with the
.IR -conninfo
option thus:
.nf
% set conn [pg_connect -conninfo \\
"host=hyalos dbname=unv \\
user=pg_guest password=xxxxxxx "]
.fi
Use can list all of the keys for the option by executing the following
command:
.nf
% puts [ pg_conndefaults]
.fi
.SH FILES
.TP 5n
$PGDATA/pg_hba.conf
The Host Based Authentication file
.SH "SEE ALSO"
psql(1).
src/man/pg_upgrade.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/pg_upgrade.1,v 1.5 1998/10/25 02:47:38 momjian Exp $
.TH pg_upgrade UNIX 1/20/96 PostgreSQL PostgreSQL
.SH NAME
pg_upgrade - allows upgrade from a previous release without reloading data
.SH SYNOPSIS
.BR pg_upgrade
[-f input_file] old_data_dir
.SH DESCRIPTION
.IR "pg_upgrade"
is a utility for upgrading from a previous PostgreSQL release
without reloading all the data.
First, to be safe, back up your data directory.
Then, use:
.nf
pg_dumpall -s -z >db.out
.fi
to dump out your old database definitions without any data.
Stop the postmaster and all backends.
.PP
Then rename (using
.IR mv )
your old pgsql /data directory to /data.old and do a
.IR "make install"
to install the new binaries.
Run
.IR initdb
to create a new
.IR template1
database containing the system tables for the new release.
Start the new postmaster,
.IR cd
to the pgsql main directory, and type:
.nf
pg_upgrade -f db.out data.old
.fi
The system will do some checking to make sure everything is properly
configured, and run your
.IR db.out
script to create all the databases and tables you had, but with no data.
It will then move the data files from /data.old into the proper
.IR /data
directory.
You can then check out the data.
You can delete the
.IR /data.old
directory when you are finished.
.SH "SEE ALSO"
pg_dumpall(1).
src/man/postgres.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/postgres.1,v 1.16 1999/05/22 17:47:47 tgl Exp $
.TH POSTGRESQL UNIX 05/19/99 PostgreSQL PostgreSQL
.SH NAME
postgres - the Postgres backend server
.SH SYNOPSIS
.BR "postgres"
[\c
.BR "-B"
n_buffers]
[\c
.BR "-C"
]
[\c
.BR "-D"
data_directory]
[\c
.BR "-E"
]
[\c
.BR "-F"
]
[\c
.BR "-O"
]
[\c
.BR "-Q"
]
[\c
.BR "-S kbytes"
]
[\c
.BR "-d"
debug_level]
[\c
.BR "-e"
]
[\c
.BR "-o"
output_file]
[\c
.BR "-s"
]
[\c
.BR "-v protocol"
]
[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
Some of the switches explained in this man page can be passed to the backend
through the "database options" field of a connection request, and thus can be
set for a particular backend without going to the trouble of restarting the
postmaster. This is particularly handy for debugging-related switches.
.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
.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 buffers, where each buffer is 8k bytes
(or whatever BLCKSZ is set to in config.h).
.TP
.BR "-C"
Do not show server version number.
.TP
.BR "-D" " data_directory"
This option specifies the pathname of the directory that contains the
database system data (the tables, the catalogs, etc.). If you don't
specify this option, Postgres uses the value of the PGDATA environment
variable. You must either specify a -D option or set PGDATA.
The data directory pathname for a database system is normally determined when
the database system is created with
.IR initdb ,
with a --pgdata option to
.IR initdb .
.TP
.BR "-E"
Echo all queries.
.TP
.BR "-F"
Disable 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 "-O"
Override restrictions, so system table structures can be modified(pg_*).
.TP
.BR "-Q"
Specifies \*(lqquiet\*(rq mode.
.TP
.BR "-S" " kbytes"
Specifies the amount of memory to be used by internal sorts and hashes
before resorting to temporary disk files. The value is specified in
kilobytes, and defaults to 512 kilobytes. Note that for a complex query,
several sorts and/or hashes might be running in parallel, and each one
will be allowed to use as much as -S kilobytes before it starts to put
data into temporary files.
.TP
.BR "-e"
The
.IR "-e"
option controls how dates are input to and output from the database.
.IP
If the
.IR "-e"
option is supplied, then all dates passed to and from the frontend
processes will be assumed to be in
.IR "European"
format ie.
.IR "DD-MM-YYYY"
otherwise dates are input and output in
.IR "American"
format ie.
.IR "MM-DD-YYYY"
.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.
.TP
.BR "-v" " protocol"
Specifies the number of the frontend/backend protocol to be used for this
particular session.
.SH "DEVELOPER 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 "-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.
(Neither sequential scans nor nested-loop joins can be disabled completely;
the -fs and -fn options simply discourage the optimizer from using those
plan types if it has any other alternative.)
.TP
.BR "-i"
Prevents query execution, but shows the plan tree.
.TP
.BR "-p" " databasename"
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. Switches following -p are restricted to those
considered "secure".
.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.
src/man/postmaster.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/postmaster.1,v 1.17 1999/05/22 17:47:48 tgl Exp $
.TH POSTMASTER UNIX 05/19/99 PostgreSQL PostgreSQL
.SH "NAME"
postmaster - run the Postgres postmaster
.SH "SYNOPSIS"
.BR "postmaster"
[\c
.BR "-B"
n_buffers]
[\c
.BR "-D"
data_dir]
[\c
.BR "-N"
n_backends]
.br
.in +5n
[\c
.BR "-S" \c
]
[\c
.BR "-a"
system]
[\c
.BR "-b"
backend_pathname]
[\c
.BR "-d"
[debug_level]]
[\c
.BR "-i" \c
]
[\c
.BR "-n" \c
]
[\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 SysV 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.
.PP
.BR "Only one postmaster should be running at a time in a given
Postgres installation."
Here, an installation means a database directory and postmaster port number.
You can run more than one postmaster on a machine only if each one has a
separate directory and port number.
.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 buffers, where each buffer is 8k bytes
(or whatever BLCKSZ is set to in config.h).
.TP
.BR "-D" " data_dir"
Specifies the directory to use as the root of the tree of database
directories. If -D is not given, the default data directory name is
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 "-N" " n_backends"
.IR "n_backends"
is the maximum number of backend server processes that this postmaster
is allowed to start. In the stock configuration, this value defaults
to 32, and can be set as high as 1024 if your system will support that
many processes. Both the default and upper limit values can be altered
when building Postgres (see src/include/config.h).
.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"
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 .
This option no longer has any effect! The pg_hba.conf configuration
file now controls authentication.
.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).
This option is also obsolete, since the postmaster and backend are now
a single executable --- the postmaster forks a backend but does not do
an exec.
.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 "-i"
This enables TCP/IP or Internet domain socket communication.
Without this option, only local Unix domain socket communication is
possible.
.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 TCP/IP port or local Unix domain socket file extension
on which the
.IR postmaster
is to listen for connections from frontend applications. Defaults to
the value of the
.SM PGPORT
environment variable, or if
.SM PGPORT
is not set, then the default value established when Postgres was
compiled (normally 5432). 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 1234 -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 directory 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 a kernel with particularly small shared memory
and/or semaphore limits, you may have to reconfigure your kernel to increase
its shared memory or semaphore parameters. (You may be able to postpone
reconfiguring your kernel by reducing -B to reduce Postgres' shared memory
consumption, or by reducing -N to reduce Postgres' semaphore consumption.)
.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.
src/man/psql.1 deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/psql.1,v 1.30 1999/03/30 05:14:03 ishii Exp $
.TH PSQL UNIX 1/20/96 PostgreSQL PostgreSQL
.SH NAME
psql - 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 "-E"
]
[\c
.BR "-f"
filename]
[\c
.BR "-F"
separator]
[\c
.BR "-h"
hostname]
[\c
.BR "-H"
]
[\c
.BR "-l"
]
[\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 "-T"
table-options
]
[\c
.BR "-u"
]
[\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.
.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
When
.IR "psql"
starts, it reads SQL commands from
.IR "/etc/psqlrc"
and then from
.IR "$(HOME)/.psqlrc"
This allows SQL commands like
.IR SET
which can be used to set the date style to be run at the start of
evry session.
.PP
.IR "psql"
understands the following command-line options:
.TP
.BR "-a" " system"
Specifies an authentication system
.IR "system"
to use in connecting to the
.IR postmaster
process. This option no longer has any effect.
.TP
.BR "-A"
Turn off fill justification when printing out table elements.
.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 "-E" " "
Echo the actual query generated by \ed and other backslash commands
.TP
.BR "-f" " filename"
Use the file
.IR "filename"
as the source of queries instead of reading queries interactively.
.TP
.BR "-F" " separator"
Use
.IR "separator"
as the field separator.
The default is "|".
.TP
.BR "-h" " hostname"
Specifies the hostname of the machine on which the
.IR postmaster
is running.
Without this option, communication is performed using
local Unix domain sockets.
.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 "-o" " filename"
Put all output into filename
.TP
.BR "-p" " port"
Specifies the TCP/IP port or local Unix domain socket file
extension 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 column names.
This is useful with the
.BR -c
option in shell scripts.
.TP
.BR "-T" " table-options"
Allows you to specify options to be placed within the <table ...> tag
for
.SM HTML3.0
tabular output. For example
.BR border
will give you tables with borders.
.TP
.BR "-u"
Asks the user for the user name and password before connecting to the database.
If the database does not require password authentication then these are
ignored. If the option is not used (and the PGPASSWORD environment variable
is not set) and the database requires password authentication, then the
connection will fail. The user name is ignored anyway.
.TP
.BR "-x"
Turns on extended row format mode. When enabled each row will have its column
names printed on the left with the column values printed on the right.
This is useful for rows which are otherwise too long to fit into
one screen line. HTML row 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 POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
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"
Anything you enter in psql that begins with an unquoted backslash is a psql
command. Anything else is SQL and simply goes into the current query buffer
(and once you have at least one complete query, it gets automatically
submitted to the backend). Psql commands are also called slash commands.
.PP
The format of a psql command is the backslash, followed immediately by
a command verb, then any arguments. The arguments are separated from the
command verb and each other by any number of white space characters.
.PP
With single character command verbs, you don't actually need to separate the
command verb from the argument with white space, for historical reasons.
You should anyway.
.IP "\ea"
Toggle field alignment when printing out table elements.
.IP "\eC \fIcaption\fR"
Set the HTML3.0 table caption.
.IP "\econnect \fIdbname\fR \fIusername\fR"
Establish a connection to a new database. The previous connection is closed.
.IP "\ecopy \fItable\fR {FROM | TO} \fIfilename\fR"
Perform a frontend copy. This is an operation that runs a SQL COPY command,
but instead of the backend reading or writing a specified file, and
consequently requiring special user privilege, psql reads or writes the
file and routes the data to or from the backend. The default TAB
delimiter is used.
.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 "\eda"
List aggregates.
.IP "\edd object"
List the description of the table, table.column, type, operator, or aggregate.
.IP "\edf"
List functions.
.IP "\edi"
List only indexes.
.IP "\edo"
List operators.
.IP "\eds"
List only sequences.
.IP "\edS"
List system tables and indexes.
.IP "\edt"
List only tables.
.IP "\edT"
List types.
.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 old 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 column name headings and row count (defaults to on).
.IP "\eT"
Set html3.0 <table ...> options.
.IP "\ex"
Toggles extended row format mode. When enabled each row will have its column
names printed on the left with the column values printed on the right.
This is useful for rows which are otherwise too long to fit into
one screen line. HTML row output mode supports this flag too.
.IP "\ew [\fIfilename\fR]"
Outputs current query buffer to
.IR filename .
.IP "\ez"
Produces a list of all tables in database with their appropriate ACLs
(grant/revoke permissions) listed.
.IP "\e! [\fIcommand\fR]"
Escape to shell or execute
.IR command.
.IP \e?
Get help information about the \e commands.
.SH "ENVIRONMENT VARIABLES"
There are some environment variables which can be used in liu of
command line arguments; these are detailed below.
Additionally, the Postgres frontend library used by the psql application
looks for other optional environment variables to configure, for example,
the style of date/time representation and the local time zone. Refer
to libpq(3) for more details.
.PP
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
Setting PGHOST to a non-zero-length string causes TCP/IP communication
to be used, rather than the default local Unix domain sockets.
.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.
.SH "RETURN VALUE"
.IR psql
returns 0 to the shell on successful completion of all queries,
1 for errors, 2 for abrupt disconnection from the backend.
.IR psql
will also return 1 if the connection to a database could not be made for
any reason.
.SH "SEE ALSO"
libpq(3),
postgres(1),
postmaster(1).
src/man/reset.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/reset.l,v 1.5 1998/10/14 02:36:43 momjian Exp $
.TH RESET SQL 05/14/97 PostgreSQL PostgreSQL
.SH NAME
reset - restore run-time parameters for session to default values
.SH SYNOPSIS
.nf
\fBreset\fR variable
.fi
.SH DESCRIPTION
.BR Reset
will display the current configuration parameters for
.IR variable
during a session.
.PP
The session can be configured using
.IR set(l),
and values can be displayed using
.IR show(l).
Parameters and values are case-insensitive.
.PP
See
.IR set(l)
for more information on available variables.
.SH EXAMPLES
.nf
tgl=> reset DateStyle;
RESET VARIABLE
tgl=> reset GEQO;
RESET VARIABLE
.fi
.SH "SEE ALSO"
set(l),
show(l).
.SH BUGS
TBD
src/man/revoke.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/revoke.l,v 1.4 1998/06/24 13:21:29 momjian Exp $
.TH REVOKE SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
revoke - 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).
src/man/rollback.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/rollback.l,v 1.4 1998/03/23 15:09:43 momjian Exp $
.TH ROLLBACK SQL 01/20/96 PostgreSQL PostgreSQL
.\" XXX This .XA has to go after the .TH so that the index page number goes
.\" in the right place...
.SH NAME
rollback - 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),
commit(l).
src/man/select.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/select.l,v 1.13 1999/06/03 19:52:09 momjian Exp $
.TH SELECT SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
select - retrieve instances from a class
.SH SYNOPSIS
.nf
\fBselect\fR [distinct [on attr_name]]
expression1 [\fBas\fR attr_name-1]
{, expression-1 [\fBas\fR attr_name-i]}
[\fBinto\fR [\fBtemp\fR] [\fBtable\fR] classname]
[\fBfrom\fR from-list]
[\fBwhere\fR where-clause]
[\fBgroup by\fR attr_name1 {, attr_name-i....}]
[\fBhaving\fR having-clause]
[ { \fBunion {all}\fR | \fBintersect\fR | \fBexcept\fR } \fBselect\fR ...]
[\fBorder by\fR attr_name1 [\fBasc\fR | \fBdesc\fR] [\fBusing op1\fR] {, attr_namei...}]
[\fBfor update\fR [\fBof\fR class_name...]]
[\fBlimit\fR count [\fBoffset\fR|, count]]
.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.
The
.BR "for update"
allows the select statement to perform exclusive locking of selected rows.
The
.BR "limit/offset"
allows control over which rows are returned by the query.
.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
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.
src/man/set.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/set.l,v 1.23 1999/06/17 15:16:06 momjian Exp $
.TH SET SQL 05/14/97 PostgreSQL PostgreSQL
.SH NAME
set - set run-time parameters for session
.SH SYNOPSIS
.nf
\fBset\fR variable \fBto\fR 'value1[,value2 ...]'
.fi
.SH DESCRIPTION
.BR Set
will modify configuration parameters for
.IR variable
during a session.
.PP
Current values can be obtained using
.IR show(l),
and values can be restored to the defaults using
.IR reset(l).
Parameters and values are case-insensitive.
Note that the value field is always specified as a string, so
is enclosed in single-quotes.
.PP
.IR DATESTYLE
determines the output format for the date and time data types.
.ce 1
\fBDateStyle Values\fR
.if n .ta 5 +15 +40
.if t .ta 0.5i +1.5i +3.0i
.in 0
.nf
ISO - use ISO 8601-style dates and times
SQL - use Oracle/Ingres-style dates and times
Postgres - use traditional Postgres format
European - use dd/mm/yyyy for numeric date representations.
NonEuropean - use mm/dd/yyyy for numeric date representations.
US - same as 'NonEuropean'
default - restores the default values ('US,Postgres')
.fi
.PP
.IR COST_HEAP
sets the cost uses for heap scans by the optimizer.
.PP
.IR COST_INDEX
sets the cost uses for index scans by the optimizer.
.PP
.IR GEQO
enables or disables the genetic optimizer algorithm. This algorithm is
.IR on
by default, which used GEQO for statements of eleven or more tables.
Set the
.IR Programmer's Guide
for more information.
.ce 1
\fBGEQO Values\fR
.if n .ta 5 +15 +40
.if t .ta 0.5i +1.5i +3.0i
.in 0
.nf
on - use for statements with 8 or more tables
on=10 - use for statements with 10 or more tables
off - do not use the genetic optimizer
.fi
.PP
.IR KSQO
enables or disables a workaround for memory exhaustion in queries with many
.B OR
clauses.
The default is disabled.
.PP
.IR TIMEZONE
sets your timezone.
.PP
\fITRANSACTION ISOLATION LEVEL\fR sets the current transaction's isolation
level to \fI SERIALIZABLE\fR or \fIREAD COMMITTED\fR. \fISERIALIZABLE\fR
means that the current transaction queries will read only rows committed
before first DML statement (SELECT/INSERT/DELETE/UPDATE/FETCH/COPY_TO) was
executed in this transaction. \fIREAD COMMITTED\fR means that the current
transaction queries will read only rows committed before a query began.
\fIREAD COMMITTED\fR is the default. \fBNote\fR: SQL92 standard requires
\fISERIALIZABLE\fR to be the default isolation level.
.PP
.IR CLIENT_ENCODING|NAMES
sets the character set encoding of the client. Only available if multi-byte
is enabled at configure time.
.PP
.IR SERVER_ENCODING
sets the character set encoding of the server. Only available if multi-byte
is enabled at configure time.
.SH EXAMPLES
.nf
--
--Set the style of date to ISO
--
set DateStyle to 'ISO'
.fi
.PP
.nf
--
--Set the style of date to SQL with European conventions
--
set DateStyle to 'SQL,European'
.fi
.PP
.nf
--
--Use GEQO for statements with 4 or more tables
--
set GEQO to 'on=4'
--
--Turn off the genetic optimizer
--
set GEQO to 'off'
.fi
.SH "SEE ALSO"
reset(l),
show(l).
src/man/show.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/show.l,v 1.5 1998/10/14 02:36:45 momjian Exp $
.TH SHOW SQL 05/14/97 PostgreSQL PostgreSQL
.SH NAME
show - show run-time parameters for session
.SH SYNOPSIS
.nf
\fBshow\fR variable
.fi
.SH DESCRIPTION
.BR Show
will display the current configuration parameters for
.IR variable
during a session.
.PP
The session can be configured using
.IR set(l),
and values can be restored to the defaults using
.IR reset(l).
Parameters and values are case-insensitive.
.PP
See
.IR set(l)
for more information on available variables.
.SH EXAMPLES
.nf
tgl=> show DateStyle;
NOTICE:DateStyle is Postgres with US (NonEuropean) conventions
SHOW VARIABLE
tgl=> show GEQO;
NOTICE:GEQO is ON
SHOW VARIABLE
.fi
.SH "SEE ALSO"
reset(l),
set(l).
.SH BUGS
TBD
src/man/sql.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/sql.l,v 1.13 1998/07/16 15:54:39 momjian Exp $
.TH INTRODUCTION SQL 11/5/95 PostgreSQL PostgreSQL
.SH "Section 4 - 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. We also support double-slashes as comments, e.g.:
.nf
-- This is a standard SQL comment
// And this is another supported comment style, like C++
.fi
We also support C-style comments, e.g.:
.nf
/* multi
line
comment */
.fi
.SH "Names"
.IR Names
in SQL are sequences of less than NAMEDATALEN alphanumeric characters,
starting with an alphabetic character. By default, NAMEDATALEN is set
to 32, 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
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 "Xmin, cmin, xmax"
and
.IR cmax
stand respectively for 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 and command identifiers are 32 bit quantities.
Transactions are assigned sequentially starting at 512.
.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 pgbuiltin(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 "pgbuiltin" "(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 (name)
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 [*]
.fi
The
.IR "from expression"
defines one or more instance variables to range over the class
indicated in
.IR class_reference .
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 "SEE ALSO"
insert(l),
delete(l),
execute(l),
update(l),
select(l),
psql(1).
src/man/update.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/update.l,v 1.5 1998/06/23 17:52:38 momjian Exp $
.TH UPDATE SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
update - 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).
src/man/vacuum.l deleted 100644 → 0
View file @ d0a19198
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/vacuum.l,v 1.9 1998/03/25 01:54:53 momjian Exp $
.TH VACUUM SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME
vacuum - vacuum a database
.SH SYNOPSIS
.nf
\fBvacuum [verbose] [analyze] [\fPtable\fB]\fP
\fBvacuum [verbose] analyze [\fPtable [(column,...)]\fB]\fP
.fi
.SH DESCRIPTION
.BR Vacuum
is the Postgres vacuum cleaner. It opens every class in the database,
cleans out records from rolled back 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
\fBverbose\fP prints a detailed vacuum activity report for each table.
.PP
\fBanalyze\fP also updates column statistics used by the optimizer to
determine the most efficient way to execute a query.
The statistics represent the disbursion of the data in each column.
This information is valuable when several execution paths are possible.
.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
If the server crashes during a vacuum command, chances are it will leave
a lock file hanging around. Attempts to re-run the vacuum command
result in an error message about the creation of a lock file. If you
are sure vacuum is not running, remove the pg_vlock file in your
database directory(i.e. data/base/dbname/pg_vlock).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment