begriffs open source - ai-pg/blob - full-docs/txt/sql-release-savepoint.txt

   1
   2 RELEASE SAVEPOINT
   3
   4    RELEASE SAVEPOINT — release a previously defined savepoint
   5
   6 Synopsis
   7
   8 RELEASE [ SAVEPOINT ] savepoint_name
   9
  10 Description
  11
  12    RELEASE SAVEPOINT releases the named savepoint and all active
  13    savepoints that were created after the named savepoint, and frees their
  14    resources. All changes made since the creation of the savepoint that
  15    didn't already get rolled back are merged into the transaction or
  16    savepoint that was active when the named savepoint was created. Changes
  17    made after RELEASE SAVEPOINT will also be part of this active
  18    transaction or savepoint.
  19
  20 Parameters
  21
  22    savepoint_name
  23           The name of the savepoint to release.
  24
  25 Notes
  26
  27    Specifying a savepoint name that was not previously defined is an
  28    error.
  29
  30    It is not possible to release a savepoint when the transaction is in an
  31    aborted state; to do that, use ROLLBACK TO SAVEPOINT.
  32
  33    If multiple savepoints have the same name, only the most recently
  34    defined unreleased one is released. Repeated commands will release
  35    progressively older savepoints.
  36
  37 Examples
  38
  39    To establish and later release a savepoint:
  40 BEGIN;
  41     INSERT INTO table1 VALUES (3);
  42     SAVEPOINT my_savepoint;
  43     INSERT INTO table1 VALUES (4);
  44     RELEASE SAVEPOINT my_savepoint;
  45 COMMIT;
  46
  47    The above transaction will insert both 3 and 4.
  48
  49    A more complex example with multiple nested subtransactions:
  50 BEGIN;
  51     INSERT INTO table1 VALUES (1);
  52     SAVEPOINT sp1;
  53     INSERT INTO table1 VALUES (2);
  54     SAVEPOINT sp2;
  55     INSERT INTO table1 VALUES (3);
  56     RELEASE SAVEPOINT sp2;
  57     INSERT INTO table1 VALUES (4))); -- generates an error
  58
  59    In this example, the application requests the release of the savepoint
  60    sp2, which inserted 3. This changes the insert's transaction context to
  61    sp1. When the statement attempting to insert value 4 generates an
  62    error, the insertion of 2 and 4 are lost because they are in the same,
  63    now-rolled back savepoint, and value 3 is in the same transaction
  64    context. The application can now only choose one of these two commands,
  65    since all other commands will be ignored:
  66 ROLLBACK;
  67 ROLLBACK TO SAVEPOINT sp1;
  68
  69    Choosing ROLLBACK will abort everything, including value 1, whereas
  70    ROLLBACK TO SAVEPOINT sp1 will retain value 1 and allow the transaction
  71    to continue.
  72
  73 Compatibility
  74
  75    This command conforms to the SQL standard. The standard specifies that
  76    the key word SAVEPOINT is mandatory, but PostgreSQL allows it to be
  77    omitted.
  78
  79 See Also
  80
  81    BEGIN, COMMIT, ROLLBACK, ROLLBACK TO SAVEPOINT, SAVEPOINT