1 package FS::Misc::Savepoint;
7 use vars qw( @ISA @EXPORT @EXPORT_OK );
9 @EXPORT = qw( savepoint_create savepoint_release savepoint_rollback );
11 use FS::UID qw( dbh );
16 FS::Misc::Savepoint - Provides methods for SQL Savepoints
20 use FS::Misc::Savepoint;
22 # Only valid within a transaction
23 local $FS::UID::AutoCommit = 0;
25 savepoint_create( 'savepoint_label' );
27 my $error_msg = do_some_things();
30 savepoint_rollback_and_release( 'savepoint_label' );
32 savepoint_release( 'savepoint_label' );
38 Provides methods for SQL Savepoints
40 Using a savepoint allows for a partial roll-back of SQL statements without
41 forcing a rollback of the entire enclosing transaction.
47 =item savepoint_create LABEL
49 =item savepoint_create { label => LABEL, dbh => DBH }
51 Executes SQL to create a savepoint named LABEL.
53 Savepoints cannot work while AutoCommit is enabled.
55 Savepoint labels must be valid sql identifiers. If your choice of label
56 would not make a valid column name, it probably will not make a valid label.
58 Savepoint labels must be unique within the transaction.
62 sub savepoint_create {
63 my %param = _parse_params( @_ );
65 $param{dbh}->do("SAVEPOINT $param{label}")
66 or die $param{dbh}->errstr;
69 =item savepoint_release LABEL
71 =item savepoint_release { label => LABEL, dbh => DBH }
73 Release the savepoint - preserves the SQL statements issued since the
74 savepoint was created, but does not commit the transaction.
76 The savepoint label is freed for future use.
80 sub savepoint_release {
81 my %param = _parse_params( @_ );
83 $param{dbh}->do("RELEASE SAVEPOINT $param{label}")
84 or die $param{dbh}->errstr;
87 =item savepoint_rollback LABEL
89 =item savepoint_rollback { label => LABEL, dbh => DBH }
91 Roll back the savepoint - forgets all SQL statements issues since the
92 savepoint was created, but does not commit or roll back the transaction.
94 The savepoint still exists. Additional statements may be executed,
95 and savepoint_rollback called again.
99 sub savepoint_rollback {
100 my %param = _parse_params( @_ );
102 $param{dbh}->do("ROLLBACK TO SAVEPOINT $param{label}")
103 or die $param{dbh}->errstr;
106 =item savepoint_rollback_and_release LABEL
108 =item savepoint_rollback_and_release { label => LABEL, dbh => DBH }
110 Rollback and release the savepoint
114 sub savepoint_rollback_and_release {
115 savepoint_rollback( @_ );
116 savepoint_release( @_ );
121 =head1 METHODS - Internal
127 Create %params from function input
129 Basic savepoint label validation
131 Complain when trying to use savepoints without disabling AutoCommit
136 my %param = ref $_[0] ? %{ $_[0] } : ( label => $_[0] );
139 # Savepoints may be any valid SQL identifier up to 64 characters
140 $param{label} =~ /^\w+$/
142 'Invalid savepont label(%s) - use only numbers, letters, _',
146 croak sprintf( 'Savepoint(%s) failed - AutoCommit=1', $param{label} )
147 if $FS::UID::AutoCommit;