reference_transaction.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 the_geom = ST_Translate(the_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 &lt;rowid_col&gt; 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>