350 lines
9.6 KiB
XML
350 lines
9.6 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<sect1 id="Long_Transactions_Support">
|
|
<sect1info>
|
|
<abstract>
|
|
|
|
<para>These functions implement a row locking mechanism to support long transactions.
|
|
They are provided primarily for implementors of the
|
|
<ulink url="http://www.opengeospatial.org/standards/wfs">Web Feature Service</ulink> specification.</para>
|
|
|
|
</abstract>
|
|
</sect1info>
|
|
|
|
<title>Long Transaction Support</title>
|
|
|
|
<note>
|
|
<para>For the locking mechanism to operate correctly the <emphasis role="bold">serializable</emphasis>
|
|
<ulink url="http://www.postgresql.org/docs/current/static/transaction-iso.html">
|
|
transaction isolation level</ulink> must be used.</para>
|
|
</note>
|
|
|
|
|
|
<refentry id="AddAuth">
|
|
<refnamediv>
|
|
<refname>AddAuth</refname>
|
|
|
|
<refpurpose>Adds an authorization token to be used in the current transaction.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>AddAuth</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>auth_token</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Adds an authorization token to be used in the current transaction.</para>
|
|
|
|
<para>Adds the current transaction identifier
|
|
and authorization token to a temporary table called <varname>temp_lock_have_table</varname>.</para>
|
|
|
|
<para>Availability: 1.1.3</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
SELECT LockRow('towns', '353', 'priscilla');
|
|
BEGIN TRANSACTION;
|
|
SELECT AddAuth('joey');
|
|
UPDATE towns SET geom = ST_Translate(geom,2,2) WHERE gid = 353;
|
|
COMMIT;
|
|
|
|
|
|
---Error--
|
|
ERROR: UPDATE where "gid" = '353' requires authorization 'priscilla'
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="LockRow" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="CheckAuth">
|
|
<refnamediv>
|
|
<refname>CheckAuth</refname>
|
|
|
|
<refpurpose>Creates a trigger on a table to prevent/allow updates and deletes of rows based on authorization token.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>CheckAuth</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>a_schema_name</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>a_key_column_name</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>integer <function>CheckAuth</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>a_key_column_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Creates trigger on a table to prevent/allow updates and deletes of rows based on an authorization token.
|
|
Identify rows using <rowid_col> column.</para>
|
|
|
|
<para>If a_schema_name is not passed in, then searches for table in current schema.</para>
|
|
<note><para>If an authorization trigger already exists on this table function errors.</para>
|
|
<para>If Transaction support is not enabled, function throws an exception.</para>
|
|
</note>
|
|
|
|
<para>Availability: 1.1.3</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
SELECT CheckAuth('public', 'towns', 'gid');
|
|
result
|
|
------
|
|
0
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="EnableLongTransactions" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="DisableLongTransactions">
|
|
<refnamediv>
|
|
<refname>DisableLongTransactions</refname>
|
|
|
|
<refpurpose>Disables long transaction support.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>DisableLongTransactions</function></funcdef>
|
|
<paramdef></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Disables long transaction support. This function removes the
|
|
long transaction support metadata tables, and drops all triggers
|
|
attached to lock-checked tables.</para>
|
|
<para>Drops meta table called <varname>authorization_table</varname> and a view called <varname>authorized_tables</varname>
|
|
and all triggers called <varname>checkauthtrigger</varname></para>
|
|
|
|
<para>Availability: 1.1.3</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT DisableLongTransactions();
|
|
--result--
|
|
Long transactions support disabled
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="EnableLongTransactions" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="EnableLongTransactions">
|
|
<refnamediv>
|
|
<refname>EnableLongTransactions</refname>
|
|
|
|
<refpurpose>Enables long transaction support.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>EnableLongTransactions</function></funcdef>
|
|
<paramdef></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Enables long transaction support.
|
|
This function creates the
|
|
required metadata tables. It must be called once before using the
|
|
other functions in this section. Calling it twice is
|
|
harmless.</para>
|
|
<para>Creates a meta table called <varname>authorization_table</varname> and a view called <varname>authorized_tables</varname></para>
|
|
|
|
<para>Availability: 1.1.3</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT EnableLongTransactions();
|
|
--result--
|
|
Long transactions support enabled
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="DisableLongTransactions" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="LockRow">
|
|
<refnamediv>
|
|
<refname>LockRow</refname>
|
|
|
|
<refpurpose>Sets lock/authorization for a row in a table.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>LockRow</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>a_schema_name</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>a_row_key</parameter></paramdef>
|
|
<paramdef><type>text</type> <parameter>an_auth_token</parameter></paramdef>
|
|
<paramdef><type>timestamp</type> <parameter>expire_dt</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>integer <function>LockRow</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>a_row_key</parameter></paramdef>
|
|
<paramdef><type>text</type> <parameter>an_auth_token</parameter></paramdef>
|
|
<paramdef><type>timestamp</type> <parameter>expire_dt</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>integer <function>LockRow</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>a_table_name</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>a_row_key</parameter></paramdef>
|
|
<paramdef><type>text</type> <parameter>an_auth_token</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Sets lock/authorization for a specific row in a table.
|
|
<varname>an_auth_token</varname> is a text value.
|
|
<varname>expire_dt</varname> is a timestamp
|
|
which defaults to <emphasis>now() + 1 hour</emphasis>.
|
|
Returns 1 if lock has been assigned, 0
|
|
otherwise (i.e. row is already locked by another auth.)</para>
|
|
|
|
<para>Availability: 1.1.3</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT LockRow('public', 'towns', '2', 'joey');
|
|
LockRow
|
|
-------
|
|
1
|
|
|
|
--Joey has already locked the record and Priscilla is out of luck
|
|
SELECT LockRow('public', 'towns', '2', 'priscilla');
|
|
LockRow
|
|
-------
|
|
0
|
|
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="UnlockRows" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="UnlockRows">
|
|
<refnamediv>
|
|
<refname>UnlockRows</refname>
|
|
|
|
<refpurpose>Removes all locks held by an authorization token.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>UnlockRows</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>auth_token</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Removes all locks held by specified authorization token.
|
|
Returns the number of locks released.</para>
|
|
|
|
<para>Availability: 1.1.3</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
SELECT LockRow('towns', '353', 'priscilla');
|
|
SELECT LockRow('towns', '2', 'priscilla');
|
|
SELECT UnLockRows('priscilla');
|
|
UnLockRows
|
|
------------
|
|
2
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="LockRow" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|