diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/advanced.sgml 03pgproc/doc/src/sgml/advanced.sgml
*** 00orig/doc/src/sgml/advanced.sgml 2004-04-14 16:45:53.000000000 -0400
--- 03pgproc/doc/src/sgml/advanced.sgml 2004-07-26 22:39:01.689881464 -0400
***************
*** 257,262 ****
--- 257,310 ----
you are using.
+
+
+ It's possible to control the statements in a transaction in a more
+ granular fashion through the use of savepoints. Savepoints
+ allow you to selectively discard parts of the transaction, while
+ committing the rest. This is done be defining a savepoint with
+ SAVEPOINT, to which you can later roll back using
+ ROLLBACK TO. All statements between defining the savepoint
+ and rolling back to it will have no effect on the final transaction.
+
+
+
+ After rolling back to a savepoint, it continues to be defined, so you can
+ roll back to it several times. Conversely, if you are sure you won't need
+ to roll back to a particular savepoint again, it can be released, so the
+ system can free some resources. Keep in mind that releasing a savepoint
+ will automatically release all savepoints that were defined after it.
+
+
+
+ Remembering the bank database, suppose we debit $100.00 from Alice's
+ account, and credit Bob's account, only to find later that we wanted to
+ credit Wally's account. We could do it using savepoints like
+
+
+ BEGIN;
+ UPDATE accounts SET balance = balance - 100.00
+ WHERE name = 'Alice';
+ SAVEPOINT my_savepoint;
+ UPDATE accounts SET balance = balance + 100.00
+ WHERE name = 'Bob';
+ -- oops ... forget that and use Wally's account
+ ROLLBACK TO my_savepoint;
+ UPDATE accounts SET balance = balance + 100.00
+ WHERE name = 'Wally';
+ COMMIT;
+
+
+
+
+ This example is, of course, oversimplified, but there's a lot of control
+ to be had over a transaction block through the use of savepoints.
+ Moreover, ROLLBACK TO is the only way to regain control of a
+ transaction block that was automatically put on aborted state by the
+ system for some reason, short of rolling it back completely and starting
+ again.
+
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/ref/allfiles.sgml 03pgproc/doc/src/sgml/ref/allfiles.sgml
*** 00orig/doc/src/sgml/ref/allfiles.sgml 2004-06-26 00:28:45.000000000 -0400
--- 03pgproc/doc/src/sgml/ref/allfiles.sgml 2004-07-26 18:27:47.000000000 -0400
***************
*** 88,96 ****
--- 88,99 ----
+
+
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/ref/begin.sgml 03pgproc/doc/src/sgml/ref/begin.sgml
*** 00orig/doc/src/sgml/ref/begin.sgml 2004-01-11 06:24:17.000000000 -0300
--- 03pgproc/doc/src/sgml/ref/begin.sgml 2004-07-26 18:49:53.000000000 -0400
***************
*** 145,150 ****
--- 145,151 ----
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/ref/release.sgml 03pgproc/doc/src/sgml/ref/release.sgml
*** 00orig/doc/src/sgml/ref/release.sgml 1969-12-31 21:00:00.000000000 -0300
--- 03pgproc/doc/src/sgml/ref/release.sgml 2004-07-26 19:07:17.000000000 -0400
***************
*** 0 ****
--- 1,138 ----
+
+
+
+
+ RELEASE
+ SQL - Language Statements
+
+
+
+ RELEASE
+ destroy a previously defined savepoint
+
+
+
+ RELEASE
+
+
+
+ savepoints
+ releasing
+
+
+
+
+ RELEASE savepoint_name
+
+
+
+
+ Description
+
+
+ RELEASE destroys a previously defined savepoint
+ in the current transaction.
+
+
+
+ Destroying a savepoint makes it—and all savepoints established after
+ it was established—unavailable as rollback points,
+ but it has no other user visible behavior. It does not undo the
+ effects of command executed after the savepoint was established.
+ To do that, see .
+
+
+
+ RELEASE also destroys all savepoints that were established
+ after the named savepoint was established.
+
+
+
+ Parameters
+
+
+
+ savepoint_name
+
+
+ The name of the savepoint to destroy.
+
+
+
+
+
+
+
+ Notes
+
+
+ Specifying a savepoint name that was not previously defined raises
+ an exception.
+
+
+
+ It is not possible to release a savepoint when the transaction is in
+ aborted state.
+
+
+
+ If multiple savepoints have the same name, only the one that was last
+ defined is released.
+
+
+
+
+
+ Examples
+
+
+ To establish and later destroy a savepoint:
+
+ BEGIN;
+ INSERT INTO table VALUES (3);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table VALUES (4);
+ RELEASE my_savepoint;
+ COMMIT;
+
+
+
+ Compatibility
+
+
+ RELEASE is fully conforming to the SQL standard.
+
+
+
+
+ See Also
+
+
+
+
+
+
+
+
+
+
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/ref/rollback.sgml 03pgproc/doc/src/sgml/ref/rollback.sgml
*** 00orig/doc/src/sgml/ref/rollback.sgml 2003-11-29 16:51:39.000000000 -0300
--- 03pgproc/doc/src/sgml/ref/rollback.sgml 2004-07-26 18:49:30.000000000 -0400
***************
*** 90,95 ****
--- 90,96 ----
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/ref/rollback_to.sgml 03pgproc/doc/src/sgml/ref/rollback_to.sgml
*** 00orig/doc/src/sgml/ref/rollback_to.sgml 1969-12-31 21:00:00.000000000 -0300
--- 03pgproc/doc/src/sgml/ref/rollback_to.sgml 2004-07-26 22:31:24.566374800 -0400
***************
*** 0 ****
--- 1,158 ----
+
+
+
+
+ ROLLBACK TO
+ SQL - Language Statements
+
+
+
+ ROLLBACK TO
+ roll back to a savepoint
+
+
+
+ ROLLBACK TO
+
+
+
+ savepoints
+ rolling back
+
+
+
+
+ ROLLBACK TO savepoint_name
+
+
+
+
+ Description
+
+
+ Roll back all commands that were executed and destroy all savepoints that
+ were created after the savepoint was established. The savepoint is
+ automatically established again.
+
+
+
+ Parameters
+
+
+
+ savepoint_name
+
+
+ The savepoint to roll back to.
+
+
+
+
+
+
+
+ Notes
+
+
+ Use to
+ destroy a savepoint without discarding the effects of commands executed
+ after it was established.
+
+
+
+ Specifying a savepoint name that has not been established causes an
+ exception to be raised.
+
+
+
+ Cursors have somewhat non-transactional behavior with respect to
+ savepoints. Any cursor that is opened inside the savepoint is not closed
+ when the savepoint is rolled back. If a cursor is affected by a
+ FETCH command inside a savepoint that is later rolled
+ back, the cursor position remains at the position that FETCH
+ left it pointing to (that is, FETCH is not rolled back).
+ A cursor whose execution causes a transaction to abort is put in a
+ can't-execute state, so while the transaction can be restored using
+ ROLLBACK TO, the cursor no longer can be used.
+
+
+
+
+ Examples
+
+
+ To undo the effects of the commands executed after my_savepoint
+ was established, and establish my_savepoint again:
+
+ ROLLBACK TO my_savepoint;
+
+
+
+
+ Cursor positions are not affected by savepoint rollback:
+
+ BEGIN;
+
+ DECLARE foo CURSOR FOR SELECT 1 UNION SELECT 2;
+
+ SAVEPOINT foo;
+
+ FETCH 1 FROM foo;
+ ?column?
+ ----------
+ 1
+
+ ROLLBACK TO foo;
+
+ FETCH 1 FROM foo;
+ ?column?
+ ----------
+ 2
+
+ COMMIT;
+
+
+
+
+
+
+
+ Compatibility
+
+
+ This command is fully SQL standard conforming.
+
+
+
+
+ See Also
+
+
+
+
+
+
+
+
+
+
+
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/ref/savepoint.sgml 03pgproc/doc/src/sgml/ref/savepoint.sgml
*** 00orig/doc/src/sgml/ref/savepoint.sgml 1969-12-31 21:00:00.000000000 -0300
--- 03pgproc/doc/src/sgml/ref/savepoint.sgml 2004-07-26 19:07:40.000000000 -0400
***************
*** 0 ****
--- 1,153 ----
+
+
+
+
+ SAVEPOINT
+ SQL - Language Statements
+
+
+
+ SAVEPOINT
+ define a new savepoint within the current transaction
+
+
+
+ SAVEPOINT
+
+
+
+ savepoints
+ defining
+
+
+
+
+ SAVEPOINT savepoint_name
+
+
+
+
+ Description
+
+
+ SAVEPOINT establishes a new savepoint within
+ the current transaction.
+
+
+
+
+
+ Parameters
+
+
+
+ savepoint_name
+
+
+ The name to give to the new savepoint.
+
+
+
+
+
+
+
+ Notes
+
+
+ A savepoint is a special mark inside a transaction that allows all commands
+ that are executed after it was established to be rolled back.
+ Alternatively, a savepoint can be destroyed so that it isn't a possible
+ rollback destination anymore. In this case, all commands that were executed after
+ the savepoint was established are preserved.
+
+
+
+ Use to
+ rollback to a savepoint. Use to destroy a savepoint, keeping
+ the effects of commands executed after it was established.
+
+
+
+ Savepoints can only be established when inside a transaction block.
+ Issuing SAVEPOINT when not inside a transaction block
+ will cause an exception to be raised.
+
+
+
+ There can be multiple savepoints defined within a transaction.
+
+
+
+
+ Examples
+
+
+ To establish a savepoint and undo the effects of all commands executed
+ after it was established, keeping only the first inserted value
+ in the table:
+
+ BEGIN;
+ INSERT INTO table VALUES (1);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table VALUES (2);
+ ROLLBACK TO my_savepoint;
+ COMMIT;
+
+
+
+
+ To establish and later destroy a savepoint, keeping both values in the table:
+
+ BEGIN;
+ INSERT INTO table VALUES (3);
+ SAVEPOINT my_savepoint;
+ INSERT INTO table VALUES (4);
+ RELEASE my_savepoint;
+ COMMIT;
+
+
+
+ Compatibility
+
+
+ SQL requires a savepoint to be automatically destroyed when another savepoint
+ with the same name is established. In PostgreSQL, the old
+ savepoint is kept, though only the last one will be used when rolling back or
+ releasing. Other than that, SAVEPOINT is fully SQL conforming.
+
+
+
+
+ See Also
+
+
+
+
+
+
+
+
+
+
+
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/ref/start_transaction.sgml 03pgproc/doc/src/sgml/ref/start_transaction.sgml
*** 00orig/doc/src/sgml/ref/start_transaction.sgml 2004-01-11 02:46:58.000000000 -0300
--- 03pgproc/doc/src/sgml/ref/start_transaction.sgml 2004-07-26 18:50:12.000000000 -0400
***************
*** 66,71 ****
--- 66,72 ----
+
diff -Ncr --exclude-from=diff-ignore 00orig/doc/src/sgml/reference.sgml 03pgproc/doc/src/sgml/reference.sgml
*** 00orig/doc/src/sgml/reference.sgml 2004-06-26 00:28:44.000000000 -0400
--- 03pgproc/doc/src/sgml/reference.sgml 2004-07-26 19:13:02.000000000 -0400
***************
*** 120,128 ****
--- 120,131 ----
¬ify;
&prepare;
&reindex;
+ &releaseSavepoint;
&reset;
&revoke;
&rollback;
+ &rollbackTo;
+ &savepoint;
&select;
&selectInto;
&set;