diff options
-rw-r--r-- | NEWS | 2 | ||||
-rw-r--r-- | configure.ac | 4 | ||||
-rw-r--r-- | doc/vmod-dbrw.3 | 4 | ||||
-rw-r--r-- | doc/vmod-dbrw.texi | 153 |
4 files changed, 123 insertions, 40 deletions
@@ -5,3 +5,3 @@ Please send vmod-dbrw bug reports to <gray@gnu.org> | |||
5 | 5 | ||
6 | Version 2.2.91 (Git) | 6 | Version 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 @@ | |||
16 | AC_PREREQ(2.69) | 16 | AC_PREREQ(2.69) |
17 | AC_INIT([vmod-dbrw], 2.2.91, [gray@gnu.org]) | 17 | AC_INIT([vmod-dbrw], 2.3, [gray@gnu.org]) |
18 | AC_CONFIG_AUX_DIR([build-aux]) | 18 | AC_CONFIG_AUX_DIR([build-aux]) |
@@ -45,3 +45,3 @@ AC_CHECK_HEADERS([sys/stdlib.h]) | |||
45 | 45 | ||
46 | AM_VARNISHAPI([4.1],[5.1]) | 46 | AM_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 |
337 | Copyright \(co 2013-2014 Sergey Poznyakoff | 337 | Copyright \(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 | |||
120 | in the appropriate place of the Varnish configuration file. Its argument | 120 | in the appropriate place of the Varnish configuration file. Its argument |
121 | is a list of variable assignments separated with semicolons, each | 121 | is a list of variable assignments separated by semicolons, each |
122 | assignment having the form @code{@var{name}=@var{value}}. When called, | 122 | assignment 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 | |||
129 | immediately followed by a letter, digit or underscore, to prevent it | 129 | immediately followed by a letter, digit or underscore, to prevent it |
130 | from being counted as a part of the name. | 130 | from being counted as a part of the name. Special syntax is available |
131 | for substituting default values and invoking built-in functions during | ||
132 | the expansion of the query. @xref{Expansions}, for a detailed | ||
133 | description of these. | ||
131 | 134 | ||
132 | The expanded query is then sent to the database server. If it returns | 135 | Having undergone expansions, the query is sent to the database server. |
133 | a non-empty set, it is further handled depending on the number of | 136 | The returned set of records (if non-empty) is processed depending on the |
134 | fields it contains. | 137 | number 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}) |
158 | is replaced with the contents of the @var{digit}s parenthesized | 161 | is replaced by the contents of the @var{digit}s parenthesized |
159 | subexpression in @var{regexp}. For compatibility with the traditional | 162 | subexpression in @var{regexp}. For compatibility with the traditional |
@@ -236,8 +239,8 @@ Type of the database to use. Valid values are @samp{mysql} and | |||
236 | Database connection parameters. This is a list of | 239 | Database 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. |
238 | The @var{value} part can be any sequence of characters, excepting | 241 | The @var{value} part can be any sequence of characters, excepting |
239 | white space and semicolon. If any of these is to appear in it, they | 242 | white space and semicolon. If @var{value} contains any of these, they |
240 | must either be escaped by prepending them with a backslash, or the | 243 | either must be escaped by prepending them with a backslash, or the |
241 | entire @var{value} enclosed in a pair of (single or double) quotes. | 244 | entire @var{value} must be enclosed in a pair of (single or double) |
242 | The following @dfn{escape sequences} are allowed for use in | 245 | quotes. 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 | ||
261 | If a backslash is followed by a symbol other than listed above, it | 264 | If a backslash is immediately followed by a symbol not listed in the |
262 | is removed and the symbol following it is reproduced verbatim. | 265 | above 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 |
347 | The SQL query to use. It can contain variable references in the | 350 | The 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 |
349 | with the actual value of the @var{name} argument to the function | 352 | to 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 | |||
354 | The example below configures @command{vmod-dbrw} to use MySQL database | 357 | The 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 | ||
385 | normally contains variable references. A variable reference has the | ||
386 | form @samp{$@var{variable}} or @samp{$@{@var{variable}@}}, where | ||
387 | @var{variable} is the variable name. When the @code{dbrw.rewrite} | ||
388 | function (@pxref{Rewrite}) is called, each such reference is expanded | ||
389 | to the actual value of @var{variable} passed in the argument to that | ||
390 | function. | ||
391 | |||
392 | The two forms are entirely equivalent. The form with curly braces is | ||
393 | normally used if the variable name is immediately followed by an | ||
394 | alphanumeric symbol, which will otherwise be considered a part of it. | ||
395 | This form also allows for specifying the action to take if the | ||
396 | variable is undefined or expands to an empty value. | ||
397 | |||
398 | During variable expansion, the forms below cause @code{dbrw.rewrite} | ||
399 | to test for a variable that is unset or null (i.e., whose value is an | ||
400 | empty string). Omitting the colon results in a test only for a | ||
401 | variable 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 | ||
406 | of @var{word} is substituted. Otherwise, the value of @var{variable} is | ||
407 | substituted. | ||
408 | |||
409 | @item $@{@var{variable}:=@var{word}@} | ||
410 | @dfn{Assign Default Values}. If @var{variable} is unset or null, the | ||
411 | expansion 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, | ||
416 | the expansion of @var{word} (or a message to that effect if @var{word} is | ||
417 | not present) is output to the current logging channel. Otherwise, the | ||
418 | value 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 | ||
422 | substituted, otherwise the expansion of @var{word} is substituted. | ||
423 | @end table | ||
424 | |||
425 | @cindex command expansion | ||
426 | @cindex expansion, command | ||
427 | After expanding variables, the query undergoes @dfn{command | ||
428 | expansion}. Syntactically, a command invocation is | ||
429 | |||
430 | @example | ||
431 | $(@var{cmd} @var{args}) | ||
432 | @end example | ||
433 | |||
434 | @noindent | ||
435 | where @var{cmd} is the command name, and @var{args} is a list of | ||
436 | arguments separated by whitespace. Arguments can in turn contain | ||
437 | variable and command references. | ||
438 | |||
439 | During command expansion, each invocation is replaced by the result of | ||
440 | the call to function @var{cmd} with the supplied arguments. | ||
441 | |||
442 | As of version @value{VERSION} of @command{vmod-dbrw}, only one | ||
443 | function is declared: | ||
444 | |||
445 | @deffn {Command} urlprefixes @var{uri} | ||
446 | Expands to comma-separated list of path prefixes contained in | ||
447 | @var{uri}, starting from the longest one (@var{uri} itself, with | ||
448 | eventual query part stripped off). Single @samp{/} is not included in | ||
449 | the 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 @{ | |||
375 | The query supplied to the @code{config} function depends on the | 456 | The query supplied to the @code{config} function depends on the |
376 | database schema and on the kind of matching required. To ensure the | 457 | database schema and on the desired kind of matching (e.g. exact |
377 | best performance of the module it is important to design the database | 458 | vs. wildcard). To ensure the best performance of the module it is |
378 | and the query so that the database look up be as fast as possible. | 459 | important to design the schema and the query so that the database |
460 | look up be as fast as possible. | ||
379 | 461 | ||
@@ -401,4 +483,4 @@ The columns and their purpose are: | |||
401 | @item id | 483 | @item id |
402 | An integer uniquely identifying the row. It is convenient for | 484 | An integer uniquely identifying the row. It is useful for |
403 | managing the table (e.g. deleting the row). | 485 | table management purposes (e.g. deleting the row). |
404 | 486 | ||
@@ -414,5 +496,5 @@ Destination URL to redirect to. | |||
414 | 496 | ||
415 | The rewrite function is to look for a row that has @samp{host} and | 497 | The 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 |
417 | URL in the @samp{dest} column. The corresponding query is: | 499 | the 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. | |||
426 | Handling regular expression matches is a bit trickier. Your query | 508 | Handling regular expression matches is a bit trickier. Your query |
427 | should first return the rows that could match the request. Then the | 509 | should first return such rows that could possibly match the request. |
428 | @command{vmod-dbrw} engine will do the rest, by iterating over them | 510 | Then the @command{vmod-dbrw} engine will do the rest, by iterating |
429 | and finding the one that actually does. It will iterate over the rows | 511 | over the returned set and finding the row that actually matches the |
430 | in the order they were returned by the database server, so it might be | 512 | request. It will iterate over the rows in the order they were |
431 | necessary to sort them by some criterion beforehand. | 513 | returned by the database server, so it might be necessary to sort them |
514 | by some criterion beforehand. | ||
432 | 515 | ||
@@ -541,3 +624,3 @@ function parses this string and builds a symbol table. | |||
541 | Using the symbol table built in the previous stage, each occurrence of | 624 | Using the symbol table built in the previous stage, each occurrence of |