Adding upstream version 14.5.upstream/14.5upstream

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

1 files changed, 128 insertions, 0 deletions

diff --git a/doc/src/sgml/man7/BEGIN.7 b/doc/src/sgml/man7/BEGIN.7
new file mode 100644
index 0000000..2add919
--- /dev/null
+++ b/doc/src/sgml/man7/BEGIN.7
@@ -0,0 +1,128 @@
+'\" t
+.\"     Title: BEGIN
+.\"    Author: The PostgreSQL Global Development Group
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 2022
+.\"    Manual: PostgreSQL 14.5 Documentation
+.\"    Source: PostgreSQL 14.5
+.\"  Language: English
+.\"
+.TH "BEGIN" "7" "2022" "PostgreSQL 14.5" "PostgreSQL 14.5 Documentation"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+BEGIN \- start a transaction block
+.SH "SYNOPSIS"
+.sp
+.nf
+BEGIN [ WORK | TRANSACTION ] [ \fItransaction_mode\fR [, \&.\&.\&.] ]
+
+where \fItransaction_mode\fR is one of:
+
+    ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
+    READ WRITE | READ ONLY
+    [ NOT ] DEFERRABLE
+.fi
+.SH "DESCRIPTION"
+.PP
+\fBBEGIN\fR
+initiates a transaction block, that is, all statements after a
+\fBBEGIN\fR
+command will be executed in a single transaction until an explicit
+\fBCOMMIT\fR
+or
+\fBROLLBACK\fR
+is given\&. By default (without
+\fBBEGIN\fR),
+PostgreSQL
+executes transactions in
+\(lqautocommit\(rq
+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)\&.
+.PP
+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\&.
+.PP
+If the isolation level, read/write mode, or deferrable mode is specified, the new transaction has those characteristics, as if
+\fBSET TRANSACTION\fR
+was executed\&.
+.SH "PARAMETERS"
+.PP
+WORK
+.br
+TRANSACTION
+.RS 4
+Optional key words\&. They have no effect\&.
+.RE
+.PP
+Refer to
+SET TRANSACTION (\fBSET_TRANSACTION\fR(7))
+for information on the meaning of the other parameters to this statement\&.
+.SH "NOTES"
+.PP
+\fBSTART TRANSACTION\fR
+has the same functionality as
+\fBBEGIN\fR\&.
+.PP
+Use
+\fBCOMMIT\fR
+or
+\fBROLLBACK\fR
+to terminate a transaction block\&.
+.PP
+Issuing
+\fBBEGIN\fR
+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
+\fBSAVEPOINT\fR(7))\&.
+.PP
+For reasons of backwards compatibility, the commas between successive
+\fItransaction_modes\fR
+can be omitted\&.
+.SH "EXAMPLES"
+.PP
+To begin a transaction block:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+BEGIN;
+.fi
+.if n \{\
+.RE
+.\}
+.SH "COMPATIBILITY"
+.PP
+\fBBEGIN\fR
+is a
+PostgreSQL
+language extension\&. It is equivalent to the SQL\-standard command
+\fBSTART TRANSACTION\fR, whose reference page contains additional compatibility information\&.
+.PP
+The
+DEFERRABLE
+\fItransaction_mode\fR
+is a
+PostgreSQL
+language extension\&.
+.PP
+Incidentally, the
+BEGIN
+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\&.
+.SH "SEE ALSO"
+\fBCOMMIT\fR(7), \fBROLLBACK\fR(7), START TRANSACTION (\fBSTART_TRANSACTION\fR(7)), \fBSAVEPOINT\fR(7)