Skip to content

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

Add more new pages.

parent e57cfd81
Hide whitespace changes
Inline Side-by-side
Showing with 837 additions and 0 deletions
doc/src/sgml/ref/commands.sgml
View file @ e6c1fbab
...@@ -27,6 +27,11 @@ ...@@ -27,6 +27,11 @@
&declare; &declare;
&delete; &delete;
&dropFunction; &dropFunction;
&listen;
&load;
&lock;
&move;
&notify;
&reset; &reset;
&revoke; &revoke;
&rollback; &rollback;
......
doc/src/sgml/ref/listen.sgml 0 → 100644
View file @ e6c1fbab
<REFENTRY ID="SQL-LISTEN">
<REFMETA>
<REFENTRYTITLE>
LISTEN
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
LISTEN
</REFNAME>
<REFPURPOSE>
Listen for notification on a relation
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
LISTEN <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-LISTEN-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Table object used for notification.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-LISTEN-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
LISTEN
</TERM>
<LISTITEM>
<PARA>
Message returned upon successful completion of registration.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LISTEN-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
LISTEN is used to register the current backend as a listener on the relation
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>.
When the command
<command>NOTIFY <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE></command>
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.
<para>
This event notification is performed through the libpq protocol
and frontend application interface. The application program
must call the routine
<function>PQnotifies</function>
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.
<REFSECT2 ID="R2-SQL-LISTEN-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<para>
Note that <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
needs not to be a valid class name but can be any string valid as a name up to 32
characters long.
<para>
A restriction in some previous releases of
<productname>Postgres</productname> that a
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
which does not correspond to an actual table must be enclosed in double-quotes
is no longer present.
</REFSECT2>
<REFSECT1 ID="R1-SQL-LISTEN-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
postgres=> listen virtual;
LISTEN
postgres=> notify virtual;
NOTIFY
ASYNC NOTIFY of 'virtual' from backend pid '11239' received
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LISTEN-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-LISTEN-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no LISTEN statement in <acronym>SQL92</acronym>.
</REFENTRY>
doc/src/sgml/ref/load.sgml 0 → 100644
View file @ e6c1fbab
<REFENTRY ID="SQL-LOAD">
<REFMETA>
<REFENTRYTITLE>
LOAD
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
LOAD
</REFNAME>
<REFPURPOSE>
Dynamically loads an object file
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
LOAD '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-LOAD-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Object file for dynamic loading.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-LOAD-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
LOAD
</TERM>
<LISTITEM>
<PARA>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LOAD-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
Loads an object (or ".o") file into the
<productname>Postgres</productname> backend address space. Once a
file is loaded, all functions in that file can be accessed. This
function is used in support of ADT's.
<para>
If a file is not loaded using
<command>LOAD</command>,
the file will be loaded automatically the first time the
function is called by <productname>Postgres</productname>.
<command>LOAD</command>
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.
<REFSECT2 ID="R2-SQL-LOAD-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Functions in loaded object files should not call functions in other
object files loaded through the
<command>LOAD</command>
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 able 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.
<para>
Object files must be compiled to contain position independent code.
For example,
on DECstations you must use
<application>/bin/cc</application>
with the "-G 0" option when compiling object files to be
loaded.
<para>
Note that if you are porting <productname>Postgres</productname>
to a new platform, <command>LOAD</command>
will have to work in order to support ADTs.
</REFSECT2>
<REFSECT1 ID="R1-SQL-LOAD-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Load the file /usr/postgres/demo/circle.o
--
LOAD "/usr/postgres/demo/circle.o"
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOAD-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-LOAD-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no LOAD statement in <acronym>SQL92</acronym>.
</REFENTRY>
doc/src/sgml/ref/lock.sgml 0 → 100644
View file @ e6c1fbab
<REFENTRY ID="SQL-LOCK">
<REFMETA>
<REFENTRYTITLE>
LOCK
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
LOCK
</REFNAME>
<REFPURPOSE>
Explicit lock of a table inside a transaction
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
LOCK [TABLE] <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-LOCK-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The name of an existing table to lock.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-LOCK-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
DELETE 0
</TERM>
<LISTITEM>
<PARA>
Message returned on a successful lock.
<command>LOCK</command> is implemented as a
<command>DELETE FROM <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE></command>
which is guaranteed to not delete any rows.
<VARLISTENTRY>
<TERM>
ERROR <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>: Table does not exist.
</TERM>
<LISTITEM>
<PARA>
Message returned if table don't exist.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-LOCK-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
The LOCK statement locks in exclusive mode a table inside
a transaction. The classic use for this is
the case where you want to select some data, then
update it inside a transaction.
If you don't explicit lock a table using LOCK statement, it will be
implicit locked only at first UPDATE, INSERT or DELETE operation.
If you don't exclusive lock the table before the select, some
other user may also read the selected data, and try and do
their own update, causing a deadlock while you both wait
for the other to release the select-induced shared lock so
you can get an exclusive lock to do the update.
<para>
Another example of deadlock is where one user locks one
table, and another user locks a second table. While both
keep their existing locks, the first user tries to lock
the second user's table, and the second user tries to lock
the first user's table. Both users deadlock waiting for
the tables to become available. The only solution to this
is for both users to lock tables in the same order, so
user's lock acquisitions and requests to not form a deadlock.
<REFSECT2 ID="R2-SQL-LOCK-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
LOCK is a PostgreSQL language extension.
<para>
LOCK works only inside transactions.
<note>
<title>Bug</title>
<para>
If the locked table is dropped then it will be automatically
unlocked even if a transaction is still in progress.
</note>
</REFSECT2>
<REFSECT1 ID="R1-SQL-LOCK-2">
<TITLE>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
--Explicit locking to prevent deadlock:
--
BEGIN WORK;
LOCK films;
SELECT * FROM films;
UPDATE films SET len = INTERVAL '100 minute'
WHERE len = INTERVAL '117 minute';
COMMIT WORK;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-LOCK-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-LOCK-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>,
it uses SET TRANSACTION to specify
concurrency level on transactions.
</REFENTRY>
doc/src/sgml/ref/move.sgml 0 → 100644
View file @ e6c1fbab
<REFENTRY ID="SQL-MOVE">
<REFMETA>
<REFENTRYTITLE>
MOVE
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
MOVE
</REFNAME>
<REFPURPOSE>
Moves cursor position
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
MOVE [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] { [ <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> | ALL ] } IN <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-MOVE-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<variablelist>
<varlistentry>
<term>
FORWARD
</term>
<listitem>
<para>
Skip next row(s), it is assumed by default
if selector is omitted.
<varlistentry>
<term>
BACKWARD
</term>
<listitem>
<para>
Skip previous row(s).
</variablelist>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
An unsigned integer that specify how many rows to skip.
<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Skip all remaining rows.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
An open cursor's name.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-MOVE-2">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
MOVE
</TERM>
<LISTITEM>
<PARA>
Message returned if successfully.
<VARLISTENTRY>
<TERM>
NOTICE: PerformPortalFetch: portal <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> not found.
</TERM>
<LISTITEM>
<PARA>
If cursor is not declared.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-MOVE-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
MOVE allows a user to move cursor position for specified
number of rows. MOVE works like fetch command: it
fetches rows, but put them nowhere.
<REFSECT2 ID="R2-SQL-MOVE-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
MOVE is a <productname>Postgres</productname> language extension.
<para>
Refer to FETCH statements for further description
of valid arguments.
Refer to DECLARE statements to declare a cursor.
Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements
for further information about transactions.
</REFSECT2>
<REFSECT1 ID="R1-SQL-MOVE-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--set up and use a cursor:
--
BEGIN WORK;
DECLARE liahona CURSOR
FOR SELECT * FROM films;
--Skip first 5 rows:
--
MOVE FORWARD 5 IN liahona;
--Fetch 6th row in the cursor liahona:
--
FETCH 1 IN liahona;
code |title |did| date_prod|kind |len
-----+------+---+----------+----------+------
P_303|48 Hrs|103|1982-10-22|Action | 01:37
-- close the cursor liahona and commit work:
--
CLOSE liahona;
COMMIT WORK;
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-MOVE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-MOVE-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no SQL92 MOVE statement.
</REFENTRY>
doc/src/sgml/ref/notify.sgml 0 → 100644
View file @ e6c1fbab
<REFENTRY ID="SQL-NOTIFY">
<REFMETA>
<REFENTRYTITLE>
NOTIFY
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
NOTIFY
</REFNAME>
<REFPURPOSE>
Signals all frontends and backends listening on a class
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
NOTIFY <REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-NOTIFY-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">classname</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Table or arbitrary relation class used for notification.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-NOTIFY-2">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
NOTIFY
</TERM>
<LISTITEM>
<PARA>
Notification message from backend.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-NOTIFY-1">
<REFSECT1INFO>
<DATE>1998-09-01</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
NOTIFY is used to awaken all backends and consequently all
frontends that have executed <command>LISTEN</command> on
<replaceable class="parameter">classname</replaceable>.
This can be used either within an instance-level rule
as part of the action body or from a normal query.
<para>
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.
<para>
Notice that the mere fact that a 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 notify does is indicate that some backend wishes its peers to
examine <replaceable class="parameter">classname</replaceable>
in some application-specific way.
<para>
In fact, <replaceable class="parameter">classname</replaceable>
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.
<para>
This event notification is performed through the libpq protocol
and frontend application interface. The application program
must call the routine <function>PQnotifies</function> 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.
<REFSECT2 ID="R2-SQL-NOTIFY-3">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
</PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-NOTIFY-2">
<TITLE>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
-- Configure and execute a listen/notify sequence
-- from psql
postgres=> create table t (i int4);
postgres=> listen t;
LISTEN
postgres=> notify t;
NOTIFY
ASYNC NOTIFY of 't' from backend pid '10949' received
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-NOTIFY-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-NOTIFY-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no NOTIFY statement in <acronym>SQL92</acronym>.
</REFENTRY>
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