Adding upstream version 15.4.upstream/15.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 161 insertions, 0 deletions

diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml
new file mode 100644
index 0000000..016b021
--- /dev/null
+++ b/doc/src/sgml/ref/begin.sgml
@@ -0,0 +1,161 @@
+<!--
+doc/src/sgml/ref/begin.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="sql-begin">
+ <indexterm zone="sql-begin">
+  <primary>BEGIN</primary>
+ </indexterm>
+
+ <refmeta>
+  <refentrytitle>BEGIN</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>BEGIN</refname>
+  <refpurpose>start a transaction block</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+<synopsis>
+BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</replaceable> [, ...] ]
+
+<phrase>where <replaceable class="parameter">transaction_mode</replaceable> is one of:</phrase>
+
+    ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
+    READ WRITE | READ ONLY
+    [ NOT ] DEFERRABLE
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <command>BEGIN</command> initiates a transaction block, that is,
+   all statements after a <command>BEGIN</command> command will be
+   executed in a single transaction until an explicit <link
+   linkend="sql-commit"><command>COMMIT</command></link> or <link
+   linkend="sql-rollback"><command>ROLLBACK</command></link> is given.
+   By default (without <command>BEGIN</command>),
+   <productname>PostgreSQL</productname> executes
+   transactions in <quote>autocommit</quote> mode, that is, each
+   statement is executed in its own transaction and a commit is
+   implicitly performed at the end of the statement (if execution was
+   successful, otherwise a rollback is done).
+  </para>
+
+  <para>
+   Statements are executed more quickly in a transaction block, because
+   transaction start/commit requires significant CPU and disk
+   activity. Execution of multiple statements inside a transaction is
+   also useful to ensure consistency when making several related changes:
+   other sessions will be unable to see the intermediate states
+   wherein not all the related updates have been done.
+  </para>
+
+  <para>
+   If the isolation level, read/write mode, or deferrable mode is specified, the new
+   transaction has those characteristics, as if
+   <link linkend="sql-set-transaction"><command>SET TRANSACTION</command></link>
+   was executed.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><literal>WORK</literal></term>
+    <term><literal>TRANSACTION</literal></term>
+    <listitem>
+     <para>
+      Optional key words. They have no effect.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   Refer to <xref linkend="sql-set-transaction"/> for information on the meaning
+   of the other parameters to this statement.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <link linkend="sql-start-transaction"><command>START TRANSACTION</command></link> has the same functionality
+   as <command>BEGIN</command>.
+  </para>
+
+  <para>
+   Use <link linkend="sql-commit"><command>COMMIT</command></link> or
+   <link linkend="sql-rollback"><command>ROLLBACK</command></link>
+   to terminate a transaction block.
+  </para>
+
+  <para>
+   Issuing <command>BEGIN</command> when already inside a transaction block will
+   provoke a warning message.  The state of the transaction is not affected.
+   To nest transactions within a transaction block, use savepoints
+   (see <xref linkend="sql-savepoint"/>).
+  </para>
+
+  <para>
+   For reasons of backwards compatibility, the commas between successive
+   <replaceable class="parameter">transaction_modes</replaceable> can be
+   omitted.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+  <para>
+   To begin a transaction block:
+
+<programlisting>
+BEGIN;
+</programlisting></para>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <para>
+   <command>BEGIN</command> is a <productname>PostgreSQL</productname>
+   language extension.  It is equivalent to the SQL-standard command
+   <link linkend="sql-start-transaction"><command>START TRANSACTION</command></link>, whose reference page
+   contains additional compatibility information.
+  </para>
+
+  <para>
+   The <literal>DEFERRABLE</literal>
+   <replaceable class="parameter">transaction_mode</replaceable>
+   is a <productname>PostgreSQL</productname> language extension.
+  </para>
+
+  <para>
+   Incidentally, the <literal>BEGIN</literal> key word is used for a
+   different purpose in embedded SQL. You are advised to be careful
+   about the transaction semantics when porting database applications.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-commit"/></member>
+   <member><xref linkend="sql-rollback"/></member>
+   <member><xref linkend="sql-start-transaction"/></member>
+   <member><xref linkend="sql-savepoint"/></member>
+  </simplelist>
+ </refsect1>
+</refentry>