aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-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.
Please send vmod-dbrw bug reports to <gray@gnu.org>
-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 <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)
@@ -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 <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>
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

Return to:

Send suggestions and report system problems to the System administrator.