aboutsummaryrefslogtreecommitdiff
path: root/doc/vmod-dbrw.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/vmod-dbrw.texi')
-rw-r--r--doc/vmod-dbrw.texi38
1 files changed, 37 insertions, 1 deletions
diff --git a/doc/vmod-dbrw.texi b/doc/vmod-dbrw.texi
index 734dadb..6a987ed 100644
--- a/doc/vmod-dbrw.texi
+++ b/doc/vmod-dbrw.texi
@@ -123,25 +123,32 @@ assignment having the form @code{@var{name}=@var{value}}. When called,
@code{rewrite} expands the SQL query registered with the prior call to
@code{config} by replacing each @code{$@var{name}}
construct (a @dfn{variable reference}) with the corresponding
@var{value} from its argument. Similarly to the shell syntax, the
variable reference can also be written as @code{$@{@var{name}@}}.
This latter form can be used in contexts where the variable reference is
immediately followed by a letter, digit or underscore, to prevent it
from being counted as a part of the name. Special syntax is available
for substituting default values and invoking built-in functions during
the expansion of the query. @xref{Expansions}, for a detailed
description of these.
+@anchor{X-VMOD-DBRW-Error}
+@vindex X-VMOD-DBRW-Error
Having undergone expansions, the query is sent to the database server.
+If the query returns no records or if an error occured, @code{rewrite}
+returns empty string. In case of error, it also sets the HTTP header
+@samp{X-VMOD-DBRW-Error: 1}. It can be used in VLC code to provide a
+special handling for such failures.
+
The returned set of records (if non-empty) is processed depending on the
number of fields it contains.
@cindex result interpretation
@anchor{result interpretation}
@cindex strict matching
@anchor{strict matching}
If the returned set has one or two columns, only the first tuple is
used and @code{rewrite} returns the value of its first column.
@cindex regex matching
@anchor{regex matching}
@@ -157,41 +164,46 @@ the resulting string is matched with the @var{regexp} column, which is
treated as an extended POSIX regular expression. If the value matches
the expression, the @var{result} column is expanded by replacing
@dfn{backreferences}: each occurrence of @code{$@var{digit}} (where
@var{digit} stands for a decimal digit from @samp{0} through @samp{9})
is replaced by the contents of the @var{digit}s parenthesized
subexpression in @var{regexp}. For compatibility with the traditional
usage, the @code{\@var{digit}} notation is also allowed. The
resulting value is then returned to the caller.
@cindex flags
@anchor{flags}
Optional @var{flags} column is a comma-separated list of flags that
-modify regular expression handling:
+control the matching algorithm.
@table @samp
@kindex NC
@kindex nocase
@cindex regular expression, case-insensitive
@cindex case-insensitive regular expression
@item NC
@itemx nocase
Treat @var{regexp} as case-insensitive regular expression.
@kindex case
@cindex regular expression, case-sensitive
@cindex case-sensitive regular expression
@item case
Treat @var{regexp} as case-sensitive (default).
+@kindex eq
+@cindex exact matching
+@item eq
+Use exact string matching.
+
@kindex QSA
@kindex qsappend
@cindex query string handling
@cindex append query string
@item QSA
@itemx qsappend
Treat the resulting value as URL; append any query string from the
original @var{value} to it.
@kindex QSD
@kindex qsdiscard
@cindex query string handling
@@ -200,24 +212,30 @@ original @var{value} to it.
@itemx qsdiscard
Treat the resulting value as URL; discard any query string attached to
the original @var{value}.
@anchor{X-VMOD-DBRW-Status}
@vindex X-VMOD-DBRW-Status
@cindex redirection code
@cindex status code
@item redirect=@var{code}
@item R=@var{code}
On success, set the @samp{X-VMOD-DBRW-Status} header to @var{code},
which must be a valid HTTP status code.
+
+@kindex regex
+@cindex regular expression matching
+@item regex
+Use regular expression matching. This is the default. This flag is
+provided for completeness sake, as a counterpart of @samp{eq}.
@end table
If @var{regexp} or @var{value} is NULL, strict matching is assumed
(@pxref{strict matching}).
If @var{flags} is NULL, it is ignored.
@node Configuration
@chapter Configuration
@deftypefn {function} void config (string @var{dbtype}, string @var{params}, @
string @var{query})
@@ -692,24 +710,42 @@ sub vcl_synth @{
std.integer(req.http.X-VMOD-DBRW-Status, 301);
@}
return (deliver);
@}
@}
@end group
@end example
The @code{X-VMOD-DBRW-Status} header, if set, contains the status code to be
returned to the client (@pxref{X-VMOD-DBRW-Status}). Notice the use
of the @command{vmod_std} module to cast it to integer.
+If an error occured during the rewrite, it is recommended to not
+cache the response. This way the next request will call rewrite again
+and eventually complete the rewriting. This can be achieved using the
+following @code{vcl_backend_response} fragment:
+
+@example
+@group
+sub vcl_backend_response
+@{
+ if (bereq.http.X-VMOD-DBRW-Error == "1") @{
+ set beresp.uncacheable = true;
+ return (deliver);
+ @}
+@}
+@end group
+@end example
+
+
@node Reporting Bugs
@chapter How to Report a Bug
Email bug reports to @email{gray@@gnu.org}.
As the purpose of bug reporting is to improve software, please be
sure to include a detailed information when reporting a bug. The minimum
information needed is:
@itemize @bullet
@item Module version you use.
@item A description of the bug.

Return to:

Send suggestions and report system problems to the System administrator.