1DBI::Gofer::Execute(3)User Contributed Perl DocumentationDBI::Gofer::Execute(3)
2
6 DBI::Gofer::Execute - Executes Gofer requests and returns Gofer
7 responses
8
10 $executor = DBI::Gofer::Execute->new( { ...config... });
11 $response = $executor->execute_request( $request );
13
15 Accepts a DBI::Gofer::Request object, executes the requested DBI method
16 calls, and returns a DBI::Gofer::Response object.
17 Any error, including any internal 'fatal' errors are caught and
19 converted into a DBI::Gofer::Response object.
20 This module is usually invoked by a 'server-side' Gofer transport
22 module. They usually have names in the ""DBI::Gofer::Transport::*""
23 namespace. Examples include: DBI::Gofer::Transport::stream and
24 DBI::Gofer::Transport::mod_perl.
25
27 check_request_sub
28 If defined, it must be a reference to a subroutine that will 'check'
29 the request. It is passed the request object and the executor as its
30 only arguments.
31 The subroutine can either return the original request object or die
33 with a suitable error message (which will be turned into a Gofer
34 response).
35 It can also construct and return a new request that should be executed
37 instead of the original request.
38 check_response_sub
40 If defined, it must be a reference to a subroutine that will 'check'
41 the response. It is passed the response object, the executor, and the
42 request object. The sub may alter the response object and return
43 undef, or return a new response object.
44 This mechanism can be used to, for example, terminate the service if
46 specific database errors are seen.
47 forced_connect_dsn
49 If set, this DSN is always used instead of the one in the request.
50 default_connect_dsn
52 If set, this DSN is used if "forced_connect_dsn" is not set and the
53 request does not contain a DSN itself.
54 forced_connect_attributes
56 A reference to a hash of connect() attributes. Individual attributes in
57 "forced_connect_attributes" will take precedence over corresponding
58 attributes in the request.
59 default_connect_attributes
61 A reference to a hash of connect() attributes. Individual attributes in
62 the request take precedence over corresponding attributes in
63 "default_connect_attributes".
64 max_cached_dbh_per_drh
66 If set, the loaded drivers will be checked to ensure they don't have
67 more than this number of cached connections. There is no default value.
68 This limit is not enforced for every request.
69 max_cached_sth_per_dbh
71 If set, all the cached statement handles will be cleared once the
72 number of cached statement handles rises above this limit. The default
73 is 1000.
74 forced_single_resultset
76 If true, then only the first result set will be fetched and returned in
77 the response.
78 forced_response_attributes
80 A reference to a data structure that can specify extra attributes to be
81 returned in responses.
82 forced_response_attributes => {
84 DriverName => {
85 dbh => [ qw(dbh_attrib_name) ],
86 sth => [ qw(sth_attrib_name) ],
87 },
88 },
89 This can be useful in cases where the driver has not implemented the
91 private_attribute_info() method and DBI::Gofer::Execute's own fallback
92 list of private attributes doesn't include the driver or attributes you
93 need.
94 track_recent
96 If set, specifies the number of recent requests and responses that
97 should be kept by the update_stats() method for diagnostics. See
98 DBI::Gofer::Transport::mod_perl.
99 Note that this setting can significantly increase memory use. Use with
101 caution.
102 forced_gofer_random
104 Enable forced random failures and/or delays for testing. See
105 "DBI_GOFER_RANDOM" below.
106
108 Gofer needs to know about any driver-private attributes that should
109 have their values sent back to the client.
110 If the driver doesn't support private_attribute_info() method, and very
112 few do, then the module fallsback to using some hard-coded details, if
113 available, for the driver being used. Currently hard-coded details are
114 available for the mysql, Pg, Sybase, and SQLite drivers.
115
117 DBD::Gofer, DBD::Execute and related packages are well tested by
118 executing the DBI test suite with DBI_AUTOPROXY configured to route all
119 DBI calls via DBD::Gofer.
120 Because Gofer includes timeout and 'retry on error' mechanisms there is
122 a need for some way to trigger delays and/or errors. This can be done
123 via the "forced_gofer_random" configuration item, or else the
124 DBI_GOFER_RANDOM environment variable.
125 DBI_GOFER_RANDOM
127 The value of the "forced_gofer_random" configuration item (or else the
128 DBI_GOFER_RANDOM environment variable) is treated as a series of tokens
129 separated by commas.
130 The tokens can be one of three types:
132 fail=R%
134 Set the current failure rate to R where R is a percentage. The
135 value R can be floating point, e.g., "fail=0.05%". Negative values
136 for R have special meaning, see below.
137 err=N
139 Sets the current failure err value to N (instead of the DBI's
140 default 'standard err value' of 2000000000). This is useful when
141 you want to simulate a specific error.
142 delayN=R%
144 Set the current random delay rate to R where R is a percentage, and
145 set the current delay duration to N seconds. The values of R and N
146 can be floating point, e.g., "delay0.5=0.2%". Negative values for
147 R have special meaning, see below.
148 If R is an odd number (R % 2 == 1) then a message is logged via
150 warn() which will be returned to, and echoed at, the client.
151 methodname
153 Applies the current fail, err, and delay values to the named
154 method. If neither a fail nor delay have been set yet then a
155 warning is generated.
156 For example:
158 $executor = DBI::Gofer::Execute->new( {
160 forced_gofer_random => "fail=0.01%,do,delay60=1%,execute",
161 });
162 will cause the do() method to fail for 0.01% of calls, and the
164 execute() method to fail 0.01% of calls and be delayed by 60 seconds on
165 1% of calls.
166 If the percentage value ("R") is negative then instead of the failures
168 being triggered randomly (via the rand() function) they are triggered
169 via a sequence number. In other words ""fail=-20%"" will mean every
170 fifth call will fail. Each method has a distinct sequence number.
171
173 Tim Bunce, <http://www.tim.bunce.name>
174
176 Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.
177 This module is free software; you can redistribute it and/or modify it
179 under the same terms as Perl itself. See perlartistic.
180perl v5.36.0 2022-07-22 DBI::Gofer::Execute(3)