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
@@ -3,7 +3,7 @@ See the end of file for copying conditions.
3 3
4Please send vmod-dbrw bug reports to <gray@gnu.org> 4Please send vmod-dbrw bug reports to <gray@gnu.org>
5 5
6Version 2.2.91 (Git) 6Version 2.3, 2018-12-08
7 7
8* SQL idle timeout 8* SQL idle timeout
9 9
diff --git a/configure.ac b/configure.ac
index 1212a37..420041e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -14,7 +14,7 @@
14# You should have received a copy of the GNU General Public License 14# You should have received a copy of the GNU General Public License
15# along with vmod-dbrw. If not, see <http://www.gnu.org/licenses/>. 15# along with vmod-dbrw. If not, see <http://www.gnu.org/licenses/>.
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])
19AC_CONFIG_MACRO_DIR([m4]) 19AC_CONFIG_MACRO_DIR([m4])
20AC_CONFIG_SRCDIR(src/vmod_dbrw.vcc) 20AC_CONFIG_SRCDIR(src/vmod_dbrw.vcc)
@@ -43,7 +43,7 @@ AC_PROG_MAKE_SET
43AC_HEADER_STDC 43AC_HEADER_STDC
44AC_CHECK_HEADERS([sys/stdlib.h]) 44AC_CHECK_HEADERS([sys/stdlib.h])
45 45
46AM_VARNISHAPI([4.1],[5.1]) 46AM_VARNISHAPI([4.1],[5.2.1])
47 47
48########### 48###########
49 # Check for SQL support 49 # 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 {
298.\" for man-based doc pages. 298.\" for man-based doc pages.
299.if "\V[MANCGI]"WEBDOC" \{\ 299.if "\V[MANCGI]"WEBDOC" \{\
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
303\} 303\}
304.SH "SEE ALSO" 304.SH "SEE ALSO"
@@ -334,7 +334,7 @@ Sergey Poznyakoff
334.SH "BUG REPORTS" 334.SH "BUG REPORTS"
335Report bugs to <gray@gnu.org>. 335Report 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
339.na 339.na
340License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 340License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
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.
118 118
119Once the module is configured, the @code{rewrite} function can be called 119Once 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,
123@code{rewrite} expands the SQL query registered with the prior call to 123@code{rewrite} expands the SQL query registered with the prior call to
124@code{config} by replacing each @code{$@var{name}} 124@code{config} by replacing each @code{$@var{name}}
@@ -127,11 +127,14 @@ construct (a @dfn{variable reference}) with the corresponding
127variable reference can also be written as @code{$@{@var{name}@}}. 127variable reference can also be written as @code{$@{@var{name}@}}.
128This latter form can be used in contexts where the variable reference is 128This 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
136@cindex result interpretation 139@cindex result interpretation
137@anchor{result interpretation} 140@anchor{result interpretation}
@@ -155,7 +158,7 @@ treated as an extended POSIX regular expression. If the value matches
155the expression, the @var{result} column is expanded by replacing 158the expression, the @var{result} column is expanded by replacing
156@dfn{backreferences}: each occurrence of @code{$@var{digit}} (where 159@dfn{backreferences}: each occurrence of @code{$@var{digit}} (where
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
160usage, the @code{\@var{digit}} notation is also allowed. The 163usage, the @code{\@var{digit}} notation is also allowed. The
161resulting value is then returned to the caller. 164resulting value is then returned to the caller.
@@ -234,12 +237,12 @@ Type of the database to use. Valid values are @samp{mysql} and
234 237
235@item params 238@item params
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}:
244 247
245@cindex escape sequences 248@cindex escape sequences
@@ -247,7 +250,7 @@ The following @dfn{escape sequences} are allowed for use in
247@float Table, backslash-interpretation 250@float Table, backslash-interpretation
248@caption{Backslash escapes} 251@caption{Backslash escapes}
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)
252@item \b @tab Backspace character (@acronym{ASCII} 8) 255@item \b @tab Backspace character (@acronym{ASCII} 8)
253@item \f @tab Form-feed character (@acronym{ASCII} 12) 256@item \f @tab Form-feed character (@acronym{ASCII} 12)
@@ -258,8 +261,8 @@ The following @dfn{escape sequences} are allowed for use in
258@end multitable 261@end multitable
259@end float 262@end float
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
264Valid parameters are: 267Valid parameters are:
265 268
@@ -344,15 +347,15 @@ Password to access the database.
344@kindex query 347@kindex query
345@cindex database query 348@cindex database query
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
352@end deftypefn 355@end deftypefn
353 356
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
357@example 360@example
358@group 361@group
@@ -369,13 +372,92 @@ sub vcl_recv @{
369@end group 372@end group
370@end example 373@end example
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
373@chapter Writing Queries 454@chapter Writing Queries
374@cindex query 455@cindex query
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
380Suppose that you plan to use @command{vmod-dbrw} to implement 462Suppose that you plan to use @command{vmod-dbrw} to implement
381redirection rules based on strict matching (@pxref{strict matching}). 463redirection rules based on strict matching (@pxref{strict matching}).
@@ -399,8 +481,8 @@ The columns and their purpose are:
399 481
400@table @asis 482@table @asis
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
405@item host 487@item host
406Host part of the incoming request. 488Host part of the incoming request.
@@ -412,9 +494,9 @@ URL part of the incoming request.
412Destination URL to redirect to. 494Destination URL to redirect to.
413@end table 495@end table
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
419@example 501@example
420SELECT dest FROM redirects WHERE host='$host' AND url='$url' 502SELECT 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
424actual host and URL parts of the incoming request. 506actual host and URL parts of the incoming request.
425 507
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
433The following is an example table structure: 516The following is an example table structure:
434 517
@@ -539,7 +622,7 @@ function parses this string and builds a symbol table.
539@item Variable expansion 622@item Variable expansion
540 623
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
544undefined variable is considered an error. 627undefined variable is considered an error.
545 628
@@ -591,8 +674,8 @@ sub vcl_recv @{
591@end group 674@end group
592@end example 675@end example
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
597@vindex X-VMOD-DBRW-Status 680@vindex X-VMOD-DBRW-Status
598@cindex vcl_synth 681@cindex vcl_synth

Return to:

Send suggestions and report system problems to the System administrator.