diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2018-12-08 23:02:39 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2018-12-08 23:02:39 +0200 |
commit | 691d208edcf53d48e2401340f1aec2adae8661c8 (patch) | |
tree | 5d5ffd0eead7833e107d57f7a6a2f9ccdb9755aa | |
parent | 602f4d93070ac0e762e0cbe3ef72ba792f9c4811 (diff) | |
download | vmod-dbrw-release-2.3.tar.gz vmod-dbrw-release-2.3.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.
-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
@@ -1,12 +1,12 @@ vmod-dbrw -- history of user-visible changes. 2018-12-08 See the end of file for copying conditions. Please send vmod-dbrw bug reports to <gray@gnu.org> -Version 2.2.91 (Git) +Version 2.3, 2018-12-08 * SQL idle timeout For MySQL backend, the default connection idle timeout is set equal to the value of the MySQL variable 'wait_timeout'. For Postgres, default idle timeout is not yet implemented. diff --git a/configure.ac b/configure.ac index 1212a37..420041e 100644 --- a/configure.ac +++ b/configure.ac @@ -11,13 +11,13 @@ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with vmod-dbrw. If not, see <http://www.gnu.org/licenses/>. 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) AM_CONFIG_HEADER(config.h) AC_SUBST([AC_VMOD_BASENAME],[dbrw]) @@ -40,13 +40,13 @@ AC_PROG_LIBTOOL AC_PROG_MAKE_SET # Checks for header files. 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 build_mysql=probe build_pgsql=probe 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 @@ -295,13 +295,13 @@ sub vcl_synth { .EE .\" The MANCGI variable is set by man.cgi script on Ulysses. .\" The download.inc file contains the default DOWNLOAD section .\" 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" .BR vcl (7), .BR varnishd (1). .PP @@ -331,13 +331,13 @@ should give you access to the complete manual. \} .SH AUTHORS Sergey Poznyakoff .SH "BUG REPORTS" Report bugs to <gray@gnu.org>. .SH COPYRIGHT -Copyright \(co 2013-2014 Sergey Poznyakoff +Copyright \(co 2013-2018 Sergey Poznyakoff .br .na License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> .br .ad This is free software: you are free to change and redistribute it. 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 @@ -115,26 +115,29 @@ retrieve data. This query is supplied to the module, along with the credentials for accessing the database, by calling the @code{config} function in the @code{vcl_recv} subroutine of the Varnish 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}} 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. +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} @cindex strict matching @anchor{strict matching} If the returned set has one or two columns, only the first tuple is @@ -152,13 +155,13 @@ For each returned tuple, the @var{value} column undergoes variable expansion, using the same algorithm as when preparing the query, and 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 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. @cindex flags @anchor{flags} @@ -231,38 +234,38 @@ Arguments: @item dbtype Type of the database to use. Valid values are @samp{mysql} and @samp{pgsql}. @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 @cindex backslash interpretation @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) @item \n @tab Newline character (@acronym{ASCII} 10) @item \r @tab Carriage return character (@acronym{ASCII} 13) @item \t @tab Horizontal tabulation character (@acronym{ASCII} 9) @item \v @tab Vertical tabulation character (@acronym{ASCII} 11) @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: @table @samp @kindex debug @cindex debugging level @@ -341,21 +344,21 @@ Database user name. Password to access the database. @end table @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 import dbrw; sub vcl_recv @{ @@ -366,19 +369,98 @@ sub vcl_recv @{ WHERE host='$host' AND url='$url'"@}); @} @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}). The simplest database structure for this purpose (assuming MySQL) will be: @@ -396,42 +478,43 @@ CREATE TABLE redirects ( @noindent 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. @item url URL part of the incoming request. @item dest 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' @end example 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: @example @group CREATE TABLE rewrite ( @@ -536,13 +619,13 @@ The @var{args} parameter must be a list of @code{@var{name}=@var{value}} pairs separated by semicolons. The 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. @item Establishing the database connection Unless the connection has already been established by a prior call to @@ -588,14 +671,14 @@ sub vcl_recv @{ return(synth(301, "Redirect")); @} @} @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 @cindex vmod_std @example @group |