Overview (vmod-dbrw User Manual)

2 Overview

Rewrite rules are stored in a MySQL or PostgreSQL database. The vmod-dbrw module does not impose any restrictions on its schema. It only needs to know the SQL query which is to be used to retrieve data. This query is supplied to the module, along with the credentials for accessing the database, by calling the config function in the vcl_recv subroutine of the Varnish configuration file.

Once the module is configured, the rewrite function can be called in the appropriate place of the Varnish configuration file. Its argument is a list of variable assignments separated by semicolons, each assignment having the form name=value. When called, rewrite expands the SQL query registered with the prior call to config by replacing each $name construct (a variable reference) with the corresponding value from its argument. Similarly to the shell syntax, the variable reference can also be written as ${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. Special syntax is available for substituting default values and invoking built-in functions during the expansion of the query. See Expansions, for a detailed description of these.

Having undergone expansions, the query is sent to the database server. If the query returns no records or if an error occured, rewrite returns empty string. In case of error, it also sets the HTTP header ‘X-VMOD-DBRW-Error: 1’. It can be used in VLC code to provide a special handling for such failures.

The returned set of records (if non-empty) is processed depending on the number of fields it contains.

If the returned set has one or two columns, only the first tuple is used and rewrite returns the value of its first column.

Otherwise, if the returned set has three or more columns, the regular expression matching is performed. For the purpose of this discussion, let’s refer to the columns as follows: result, regexp, value and flags. The flags column is optional. Any surplus columns are ignored.

For each returned tuple, the value column undergoes variable expansion, using the same algorithm as when preparing the query, and the resulting string is matched with the regexp column, which is treated as an extended POSIX regular expression. If the value matches the expression, the result column is expanded by replacing backreferences: each occurrence of $digit (where digit stands for a decimal digit from ‘0’ through ‘9’) is replaced by the contents of the digits parenthesized subexpression in regexp. For compatibility with the traditional usage, the \digit notation is also allowed. The resulting value is then returned to the caller.

Optional flags column is a comma-separated list of flags that control the matching algorithm.

‘NC’
‘nocase’: Treat regexp as case-insensitive regular expression.
‘case’: Treat regexp as case-sensitive (default).
‘eq’: Use exact string matching.
‘QSA’
‘qsappend’: Treat the resulting value as URL; append any query string from the original value to it.
‘QSD’
‘qsdiscard’: Treat the resulting value as URL; discard any query string attached to the original value.
‘redirect=code’
‘R=code’: On success, set the ‘X-VMOD-DBRW-Status’ header to code, which must be a valid HTTP status code.
‘regex’: Use regular expression matching. This is the default. This flag is provided for completeness sake, as a counterpart of ‘eq’.

If regexp or value is NULL, strict matching is assumed (see strict matching).

If flags is NULL, it is ignored.

This document was generated on April 9, 2020 using makeinfo.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Vmod-dbrw

Database-driven rewrites for Varnish Cache

2 Overview