summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org>2018-12-08 21:02:39 (GMT)
committer Sergey Poznyakoff <gray@gnu.org>2018-12-08 21:02:39 (GMT)
commit691d208edcf53d48e2401340f1aec2adae8661c8 (patch) (unidiff)
tree5d5ffd0eead7833e107d57f7a6a2f9ccdb9755aa
parent602f4d93070ac0e762e0cbe3ef72ba792f9c4811 (diff)
downloadvmod-dbrw-691d208edcf53d48e2401340f1aec2adae8661c8.tar.gz
vmod-dbrw-691d208edcf53d48e2401340f1aec2adae8661c8.tar.bz2
Version 2.3release-2.3
* configure.ac: Bump version number. * NEWS: Describe new version. * doc/vmod-dbrw.3: Update version number. * doc/vmod-dbrw.texi: Document expansions.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--NEWS2
-rw-r--r--configure.ac4
-rw-r--r--doc/vmod-dbrw.34
-rw-r--r--doc/vmod-dbrw.texi153
4 files changed, 123 insertions, 40 deletions
diff --git a/NEWS b/NEWS
index c700564..3ee8124 100644
--- a/NEWS
+++ b/NEWS
@@ -5,3 +5,3 @@ Please send vmod-dbrw bug reports to <gray@gnu.org>
5 5
6Version 2.2.91 (Git) 6Version 2.3, 2018-12-08
7 7
diff --git a/configure.ac b/configure.ac
index 1212a37..420041e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -16,3 +16,3 @@
16AC_PREREQ(2.69) 16AC_PREREQ(2.69)
17AC_INIT([vmod-dbrw], 2.2.91, [gray@gnu.org]) 17AC_INIT([vmod-dbrw], 2.3, [gray@gnu.org])
18AC_CONFIG_AUX_DIR([build-aux]) 18AC_CONFIG_AUX_DIR([build-aux])
@@ -45,3 +45,3 @@ AC_CHECK_HEADERS([sys/stdlib.h])
45 45
46AM_VARNISHAPI([4.1],[5.1]) 46AM_VARNISHAPI([4.1],[5.2.1])
47 47
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
@@ -300,3 +300,3 @@ sub vcl_synth {
300 .ds package vmod-dbrw 300 .ds package vmod-dbrw
301 .ds version 1.0 301 .ds version 2.2.91
302 .so download.inc 302 .so download.inc
@@ -336,3 +336,3 @@ Report bugs to <gray@gnu.org>.
336.SH COPYRIGHT 336.SH COPYRIGHT
337Copyright \(co 2013-2014 Sergey Poznyakoff 337Copyright \(co 2013-2018 Sergey Poznyakoff
338.br 338.br
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
@@ -120,3 +120,3 @@ Once the module is configured, the @code{rewrite} function can be called
120in the appropriate place of the Varnish configuration file. Its argument 120in the appropriate place of the Varnish configuration file. Its argument
121is a list of variable assignments separated with semicolons, each 121is a list of variable assignments separated by semicolons, each
122assignment having the form @code{@var{name}=@var{value}}. When called, 122assignment having the form @code{@var{name}=@var{value}}. When called,
@@ -129,7 +129,10 @@ This latter form can be used in contexts where the variable reference is
129immediately followed by a letter, digit or underscore, to prevent it 129immediately followed by a letter, digit or underscore, to prevent it
130from being counted as a part of the name. 130from being counted as a part of the name. Special syntax is available
131for substituting default values and invoking built-in functions during
132the expansion of the query. @xref{Expansions}, for a detailed
133description of these.
131 134
132The expanded query is then sent to the database server. If it returns 135Having undergone expansions, the query is sent to the database server.
133a non-empty set, it is further handled depending on the number of 136The returned set of records (if non-empty) is processed depending on the
134fields it contains. 137number of fields it contains.
135 138
@@ -157,3 +160,3 @@ the expression, the @var{result} column is expanded by replacing
157@var{digit} stands for a decimal digit from @samp{0} through @samp{9}) 160@var{digit} stands for a decimal digit from @samp{0} through @samp{9})
158is replaced with the contents of the @var{digit}s parenthesized 161is replaced by the contents of the @var{digit}s parenthesized
159subexpression in @var{regexp}. For compatibility with the traditional 162subexpression in @var{regexp}. For compatibility with the traditional
@@ -236,8 +239,8 @@ Type of the database to use. Valid values are @samp{mysql} and
236Database connection parameters. This is a list of 239Database connection parameters. This is a list of
237@samp{@var{name}=@var{value}} assignments separated with semicolons. 240@samp{@var{name}=@var{value}} assignments separated by semicolons.
238The @var{value} part can be any sequence of characters, excepting 241The @var{value} part can be any sequence of characters, excepting
239white space and semicolon. If any of these is to appear in it, they 242white space and semicolon. If @var{value} contains any of these, they
240must either be escaped by prepending them with a backslash, or the 243either must be escaped by prepending them with a backslash, or the
241entire @var{value} enclosed in a pair of (single or double) quotes. 244entire @var{value} must be enclosed in a pair of (single or double)
242The following @dfn{escape sequences} are allowed for use in 245quotes. The following @dfn{escape sequences} are allowed for use in
243@var{value}: 246@var{value}:
@@ -249,3 +252,3 @@ The following @dfn{escape sequences} are allowed for use in
249@multitable @columnfractions 0.30 .5 252@multitable @columnfractions 0.30 .5
250@item Sequence @tab Replaced with 253@item Sequence @tab Replaced by
251@item \a @tab Audible bell character (@acronym{ASCII} 7) 254@item \a @tab Audible bell character (@acronym{ASCII} 7)
@@ -260,4 +263,4 @@ The following @dfn{escape sequences} are allowed for use in
260 263
261If a backslash is followed by a symbol other than listed above, it 264If a backslash is immediately followed by a symbol not listed in the
262is removed and the symbol following it is reproduced verbatim. 265above table, it is removed and the symbol is reproduced verbatim.
263 266
@@ -346,6 +349,6 @@ Password to access the database.
346@item query 349@item query
347The SQL query to use. It can contain variable references in the 350The SQL query to use. It can contain variable references
348(@code{$@var{name}} or @code{$@{@var{name}@}}), which will be replaced 351(@code{$@var{name}} or @code{$@{@var{name}@}}), which will be expanded
349with the actual value of the @var{name} argument to the function 352to the actual value of the @var{name} argument to the function
350@code{rewrite}. 353@code{rewrite}. @xref{Expansions}, for details.
351@end table 354@end table
@@ -354,3 +357,3 @@ with the actual value of the @var{name} argument to the function
354The example below configures @command{vmod-dbrw} to use MySQL database 357The example below configures @command{vmod-dbrw} to use MySQL database
355@samp{rewrite}, with the user name @samp{varnish} and password @var{guessme}. 358@samp{rewrite}, with the user name @samp{varnish} and password @samp{guessme}.
356 359
@@ -371,2 +374,80 @@ sub vcl_recv @{
371 374
375@menu
376* Expansions::
377@end menu
378
379@node Expansions
380@section Expansions
381@cindex expansions
382@cindex variable expansion
383@cindex expansion, variable
384 The @samp{query} argument to the @code{dbrw.config} function
385normally contains variable references. A variable reference has the
386form @samp{$@var{variable}} or @samp{$@{@var{variable}@}}, where
387@var{variable} is the variable name. When the @code{dbrw.rewrite}
388function (@pxref{Rewrite}) is called, each such reference is expanded
389to the actual value of @var{variable} passed in the argument to that
390function.
391
392The two forms are entirely equivalent. The form with curly braces is
393normally used if the variable name is immediately followed by an
394alphanumeric symbol, which will otherwise be considered a part of it.
395This form also allows for specifying the action to take if the
396variable is undefined or expands to an empty value.
397
398During variable expansion, the forms below cause @code{dbrw.rewrite}
399to test for a variable that is unset or null (i.e., whose value is an
400empty string). Omitting the colon results in a test only for a
401variable that is unset.
402
403@table @asis
404@item $@{@var{variable}:-@var{word}@}
405@dfn{Use Default Values}. If @var{variable} is unset or null, the expansion
406of @var{word} is substituted. Otherwise, the value of @var{variable} is
407substituted.
408
409@item $@{@var{variable}:=@var{word}@}
410@dfn{Assign Default Values}. If @var{variable} is unset or null, the
411expansion of @var{word} is assigned to variable. The value of
412@var{variable} is then substituted.
413
414@item $@{@var{variable}:?@var{word}@}
415@dfn{Display Error if Null or Unset}. If @var{variable} is null or unset,
416the expansion of @var{word} (or a message to that effect if @var{word} is
417not present) is output to the current logging channel. Otherwise, the
418value of @var{variable} is substituted.
419
420@item $@{@var{variable}:+@var{word}@}
421@dfn{Use Alternate Value}. If @var{variable} is null or unset, nothing is
422substituted, otherwise the expansion of @var{word} is substituted.
423@end table
424
425@cindex command expansion
426@cindex expansion, command
427After expanding variables, the query undergoes @dfn{command
428expansion}. Syntactically, a command invocation is
429
430@example
431$(@var{cmd} @var{args})
432@end example
433
434@noindent
435where @var{cmd} is the command name, and @var{args} is a list of
436arguments separated by whitespace. Arguments can in turn contain
437variable and command references.
438
439During command expansion, each invocation is replaced by the result of
440the call to function @var{cmd} with the supplied arguments.
441
442As of version @value{VERSION} of @command{vmod-dbrw}, only one
443function is declared:
444
445@deffn {Command} urlprefixes @var{uri}
446Expands to comma-separated list of path prefixes contained in
447@var{uri}, starting from the longest one (@var{uri} itself, with
448eventual query part stripped off). Single @samp{/} is not included in
449the list. Each list item is quoted. The expansion can be used in the
450@samp{IN ()} SQL conditional.
451@end deffn
452
372@node Query 453@node Query
@@ -375,5 +456,6 @@ sub vcl_recv @{
375The query supplied to the @code{config} function depends on the 456The query supplied to the @code{config} function depends on the
376database schema and on the kind of matching required. To ensure the 457database schema and on the desired kind of matching (e.g. exact
377best performance of the module it is important to design the database 458vs. wildcard). To ensure the best performance of the module it is
378and the query so that the database look up be as fast as possible. 459important to design the schema and the query so that the database
460look up be as fast as possible.
379 461
@@ -401,4 +483,4 @@ The columns and their purpose are:
401@item id 483@item id
402An integer uniquely identifying the row. It is convenient for 484An integer uniquely identifying the row. It is useful for
403managing the table (e.g. deleting the row). 485table management purposes (e.g. deleting the row).
404 486
@@ -414,5 +496,5 @@ Destination URL to redirect to.
414 496
415The rewrite function is to look for a row that has @samp{host} and 497The rewrite function looks up a row that has @samp{host} and
416@samp{url} matching the incoming request and to redirect it to the 498@samp{url} matching the incoming request and, if found, returns
417URL in the @samp{dest} column. The corresponding query is: 499the value of its @samp{dest} column. The corresponding query is:
418 500
@@ -426,7 +508,8 @@ actual host and URL parts of the incoming request.
426Handling regular expression matches is a bit trickier. Your query 508Handling regular expression matches is a bit trickier. Your query
427should first return the rows that could match the request. Then the 509should first return such rows that could possibly match the request.
428@command{vmod-dbrw} engine will do the rest, by iterating over them 510Then the @command{vmod-dbrw} engine will do the rest, by iterating
429and finding the one that actually does. It will iterate over the rows 511over the returned set and finding the row that actually matches the
430in the order they were returned by the database server, so it might be 512request. It will iterate over the rows in the order they were
431necessary to sort them by some criterion beforehand. 513returned by the database server, so it might be necessary to sort them
514by some criterion beforehand.
432 515
@@ -541,3 +624,3 @@ function parses this string and builds a symbol table.
541Using the symbol table built in the previous stage, each occurrence of 624Using the symbol table built in the previous stage, each occurrence of
542@code{$@var{name}} or @code{$@{@var{name}@}} is replaced with the actual 625@code{$@var{name}} or @code{$@{@var{name}@}} is replaced by the actual
543value of the variable @var{name} from the table. Expanding an 626value of the variable @var{name} from the table. Expanding an
@@ -593,4 +676,4 @@ sub vcl_recv @{
593 676
594Further handling of the 301 response should be performed in a traditional 677The @samp{synth} sub must be provided in order to construct
595way, e.g.: 678redirection responses:
596 679

Return to:

Send suggestions and report system problems to the System administrator.