diff options
Diffstat (limited to 'doc/vmod-dbrw.texi')
-rw-r--r-- | doc/vmod-dbrw.texi | 38 |
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. |