From 691d208edcf53d48e2401340f1aec2adae8661c8 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sat, 8 Dec 2018 23:02:39 +0200 Subject: Version 2.3 * configure.ac: Bump version number. * NEWS: Describe new version. * doc/vmod-dbrw.3: Update version number. * doc/vmod-dbrw.texi: Document expansions. --- NEWS | 2 +- configure.ac | 4 +- doc/vmod-dbrw.3 | 4 +- doc/vmod-dbrw.texi | 153 +++++++++++++++++++++++++++++++++++++++++------------ 4 files changed, 123 insertions(+), 40 deletions(-) diff --git a/NEWS b/NEWS index c700564..3ee8124 100644 --- a/NEWS +++ b/NEWS @@ -3,7 +3,7 @@ See the end of file for copying conditions. Please send vmod-dbrw bug reports to -Version 2.2.91 (Git) +Version 2.3, 2018-12-08 * SQL idle timeout diff --git a/configure.ac b/configure.ac index 1212a37..420041e 100644 --- a/configure.ac +++ b/configure.ac @@ -14,7 +14,7 @@ # You should have received a copy of the GNU General Public License # along with vmod-dbrw. If not, see . AC_PREREQ(2.69) -AC_INIT([vmod-dbrw], 2.2.91, [gray@gnu.org]) +AC_INIT([vmod-dbrw], 2.3, [gray@gnu.org]) AC_CONFIG_AUX_DIR([build-aux]) AC_CONFIG_MACRO_DIR([m4]) AC_CONFIG_SRCDIR(src/vmod_dbrw.vcc) @@ -43,7 +43,7 @@ AC_PROG_MAKE_SET AC_HEADER_STDC AC_CHECK_HEADERS([sys/stdlib.h]) -AM_VARNISHAPI([4.1],[5.1]) +AM_VARNISHAPI([4.1],[5.2.1]) ########### # Check for SQL support diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3 index 4760b6b..21d15e2 100644 --- a/doc/vmod-dbrw.3 +++ b/doc/vmod-dbrw.3 @@ -298,7 +298,7 @@ sub vcl_synth { .\" for man-based doc pages. .if "\V[MANCGI]"WEBDOC" \{\ . ds package vmod-dbrw -. ds version 1.0 +. ds version 2.2.91 . so download.inc \} .SH "SEE ALSO" @@ -334,7 +334,7 @@ Sergey Poznyakoff .SH "BUG REPORTS" Report bugs to . .SH COPYRIGHT -Copyright \(co 2013-2014 Sergey Poznyakoff +Copyright \(co 2013-2018 Sergey Poznyakoff .br .na License GPLv3+: GNU GPL version 3 or later diff --git a/doc/vmod-dbrw.texi b/doc/vmod-dbrw.texi index 31b15d1..734dadb 100644 --- a/doc/vmod-dbrw.texi +++ b/doc/vmod-dbrw.texi @@ -118,7 +118,7 @@ configuration file. Once the module is configured, the @code{rewrite} function can be called in the appropriate place of the Varnish configuration file. Its argument -is a list of variable assignments separated with semicolons, each +is a list of variable assignments separated by semicolons, each 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}} @@ -127,11 +127,14 @@ construct (a @dfn{variable reference}) with the corresponding 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. +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. -The expanded query is then sent to the database server. If it returns -a non-empty set, it is further handled depending on the number of -fields it contains. +Having undergone expansions, the query is sent to the database server. +The returned set of records (if non-empty) is processed depending on the +number of fields it contains. @cindex result interpretation @anchor{result interpretation} @@ -155,7 +158,7 @@ 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 with the contents of the @var{digit}s parenthesized +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. @@ -234,12 +237,12 @@ Type of the database to use. Valid values are @samp{mysql} and @item params Database connection parameters. This is a list of -@samp{@var{name}=@var{value}} assignments separated with semicolons. +@samp{@var{name}=@var{value}} assignments separated by semicolons. The @var{value} part can be any sequence of characters, excepting -white space and semicolon. If any of these is to appear in it, they -must either be escaped by prepending them with a backslash, or the -entire @var{value} enclosed in a pair of (single or double) quotes. -The following @dfn{escape sequences} are allowed for use in +white space and semicolon. If @var{value} contains any of these, they +either must be escaped by prepending them with a backslash, or the +entire @var{value} must be enclosed in a pair of (single or double) +quotes. The following @dfn{escape sequences} are allowed for use in @var{value}: @cindex escape sequences @@ -247,7 +250,7 @@ The following @dfn{escape sequences} are allowed for use in @float Table, backslash-interpretation @caption{Backslash escapes} @multitable @columnfractions 0.30 .5 -@item Sequence @tab Replaced with +@item Sequence @tab Replaced by @item \a @tab Audible bell character (@acronym{ASCII} 7) @item \b @tab Backspace character (@acronym{ASCII} 8) @item \f @tab Form-feed character (@acronym{ASCII} 12) @@ -258,8 +261,8 @@ The following @dfn{escape sequences} are allowed for use in @end multitable @end float -If a backslash is followed by a symbol other than listed above, it -is removed and the symbol following it is reproduced verbatim. +If a backslash is immediately followed by a symbol not listed in the +above table, it is removed and the symbol is reproduced verbatim. Valid parameters are: @@ -344,15 +347,15 @@ Password to access the database. @kindex query @cindex database query @item query -The SQL query to use. It can contain variable references in the -(@code{$@var{name}} or @code{$@{@var{name}@}}), which will be replaced -with the actual value of the @var{name} argument to the function -@code{rewrite}. +The SQL query to use. It can contain variable references +(@code{$@var{name}} or @code{$@{@var{name}@}}), which will be expanded +to the actual value of the @var{name} argument to the function +@code{rewrite}. @xref{Expansions}, for details. @end table @end deftypefn The example below configures @command{vmod-dbrw} to use MySQL database -@samp{rewrite}, with the user name @samp{varnish} and password @var{guessme}. +@samp{rewrite}, with the user name @samp{varnish} and password @samp{guessme}. @example @group @@ -369,13 +372,92 @@ sub vcl_recv @{ @end group @end example +@menu +* Expansions:: +@end menu + +@node Expansions +@section Expansions +@cindex expansions +@cindex variable expansion +@cindex expansion, variable + The @samp{query} argument to the @code{dbrw.config} function +normally contains variable references. A variable reference has the +form @samp{$@var{variable}} or @samp{$@{@var{variable}@}}, where +@var{variable} is the variable name. When the @code{dbrw.rewrite} +function (@pxref{Rewrite}) is called, each such reference is expanded +to the actual value of @var{variable} passed in the argument to that +function. + +The two forms are entirely equivalent. The form with curly braces is +normally used if the variable name is immediately followed by an +alphanumeric symbol, which will otherwise be considered a part of it. +This form also allows for specifying the action to take if the +variable is undefined or expands to an empty value. + +During variable expansion, the forms below cause @code{dbrw.rewrite} +to test for a variable that is unset or null (i.e., whose value is an +empty string). Omitting the colon results in a test only for a +variable that is unset. + +@table @asis +@item $@{@var{variable}:-@var{word}@} +@dfn{Use Default Values}. If @var{variable} is unset or null, the expansion +of @var{word} is substituted. Otherwise, the value of @var{variable} is +substituted. + +@item $@{@var{variable}:=@var{word}@} +@dfn{Assign Default Values}. If @var{variable} is unset or null, the +expansion of @var{word} is assigned to variable. The value of +@var{variable} is then substituted. + +@item $@{@var{variable}:?@var{word}@} +@dfn{Display Error if Null or Unset}. If @var{variable} is null or unset, +the expansion of @var{word} (or a message to that effect if @var{word} is +not present) is output to the current logging channel. Otherwise, the +value of @var{variable} is substituted. + +@item $@{@var{variable}:+@var{word}@} +@dfn{Use Alternate Value}. If @var{variable} is null or unset, nothing is +substituted, otherwise the expansion of @var{word} is substituted. +@end table + +@cindex command expansion +@cindex expansion, command +After expanding variables, the query undergoes @dfn{command +expansion}. Syntactically, a command invocation is + +@example +$(@var{cmd} @var{args}) +@end example + +@noindent +where @var{cmd} is the command name, and @var{args} is a list of +arguments separated by whitespace. Arguments can in turn contain +variable and command references. + +During command expansion, each invocation is replaced by the result of +the call to function @var{cmd} with the supplied arguments. + +As of version @value{VERSION} of @command{vmod-dbrw}, only one +function is declared: + +@deffn {Command} urlprefixes @var{uri} +Expands to comma-separated list of path prefixes contained in +@var{uri}, starting from the longest one (@var{uri} itself, with +eventual query part stripped off). Single @samp{/} is not included in +the list. Each list item is quoted. The expansion can be used in the +@samp{IN ()} SQL conditional. +@end deffn + @node Query @chapter Writing Queries @cindex query The query supplied to the @code{config} function depends on the -database schema and on the kind of matching required. To ensure the -best performance of the module it is important to design the database -and the query so that the database look up be as fast as possible. +database schema and on the desired kind of matching (e.g. exact +vs. wildcard). To ensure the best performance of the module it is +important to design the schema and the query so that the database +look up be as fast as possible. Suppose that you plan to use @command{vmod-dbrw} to implement redirection rules based on strict matching (@pxref{strict matching}). @@ -399,8 +481,8 @@ The columns and their purpose are: @table @asis @item id -An integer uniquely identifying the row. It is convenient for -managing the table (e.g. deleting the row). +An integer uniquely identifying the row. It is useful for +table management purposes (e.g. deleting the row). @item host Host part of the incoming request. @@ -412,9 +494,9 @@ URL part of the incoming request. Destination URL to redirect to. @end table -The rewrite function is to look for a row that has @samp{host} and -@samp{url} matching the incoming request and to redirect it to the -URL in the @samp{dest} column. The corresponding query is: +The rewrite function looks up a row that has @samp{host} and +@samp{url} matching the incoming request and, if found, returns +the value of its @samp{dest} column. The corresponding query is: @example SELECT dest FROM redirects WHERE host='$host' AND url='$url' @@ -424,11 +506,12 @@ The variables @samp{host} and @samp{url} are supposed to contain the actual host and URL parts of the incoming request. Handling regular expression matches is a bit trickier. Your query -should first return the rows that could match the request. Then the -@command{vmod-dbrw} engine will do the rest, by iterating over them -and finding the one that actually does. It will iterate over the rows -in the order they were returned by the database server, so it might be -necessary to sort them by some criterion beforehand. +should first return such rows that could possibly match the request. +Then the @command{vmod-dbrw} engine will do the rest, by iterating +over the returned set and finding the row that actually matches the +request. It will iterate over the rows in the order they were +returned by the database server, so it might be necessary to sort them +by some criterion beforehand. The following is an example table structure: @@ -539,7 +622,7 @@ function parses this string and builds a symbol table. @item Variable expansion Using the symbol table built in the previous stage, each occurrence of -@code{$@var{name}} or @code{$@{@var{name}@}} is replaced with the actual +@code{$@var{name}} or @code{$@{@var{name}@}} is replaced by the actual value of the variable @var{name} from the table. Expanding an undefined variable is considered an error. @@ -591,8 +674,8 @@ sub vcl_recv @{ @end group @end example -Further handling of the 301 response should be performed in a traditional -way, e.g.: +The @samp{synth} sub must be provided in order to construct +redirection responses: @vindex X-VMOD-DBRW-Status @cindex vcl_synth -- cgit v1.2.1