Vmod-dbrw
	Database-driven rewrites for Varnish Cache	Sergey Poznyakoff

• Main
• Downloads
• Documentation

3 Configuration

function: void config (string dbtype, string params, string query)

This function configures the module and provides it with the data necessary to connect and use the database. It is normally called from the vcl_recv subroutine.

Arguments:

dbtype

Type of the database to use. Valid values are ‘mysql’ and ‘pgsql’.

params

Database connection parameters. This is a list of ‘name=value’ assignments separated by semicolons. The value part can be any sequence of characters, excepting white space and semicolon. If value contains any of these, they either must be escaped by prepending them with a backslash, or the entire value must be enclosed in a pair of (single or double) quotes. The following escape sequences are allowed for use in value:

Sequence	Replaced by
\a	Audible bell character (ASCII 7)
\b	Backspace character (ASCII 8)
\f	Form-feed character (ASCII 12)
\n	Newline character (ASCII 10)
\r	Carriage return character (ASCII 13)
\t	Horizontal tabulation character (ASCII 9)
\v	Vertical tabulation character (ASCII 11)

Table 3.1: Backslash escapes

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:

‘debug=n’

Set debugging level. Argument is a decimal number.

‘server=host’

Name or IP address of the database server to connect to. If not defined, localhost (‘127.0.0.1’) is assumed. For MySQL databases, if host begins with a slash, its value is taken to be the full pathname of the local UNIX socket to connect to.

‘port=n’

Port number on the ‘server’ to connect to. Default is ‘3306’ for MySQL and 5432 for Postgres.

‘database=name’

The name of the database to use.

‘config=filename’

(MySQL-specific) Read database access credentials and other parameters from the MySQL options file filename.

‘group=name’

(MySQL-specific) Read credentials from section name of the options file supplied with the config parameter. Default section name is ‘client’.

‘cacert=filename’

Use secure connection to the database server via SSL. The filename argument is a full pathname of the certificate authority file.

‘timeout=n’

Sets idle timeout for a single connection. The connection will be closed and opened again if the module is to use it after n or more seconds since its last use. Set ‘timeout=-1’ to disable idle timeout (session will remain open until the SQL server closes it). Set ‘timeout=0’ to close the connection after each request (not recommended).

The default depends on the selected SQL backend. For MySQL, it equals the value of the ‘wait_timeout’ global variable. For PostgreSQL, it is ‘-1’.

‘options=string’

(Postgres-specific) Connection options.

‘user=name’

Database user name.

‘password=string’

Password to access the database.

query

The SQL query to use. It can contain variable references ($name or ${name}), which will be expanded to the actual value of the name argument to the function rewrite. See Expansions, for details.

The example below configures vmod-dbrw to use MySQL database ‘rewrite’, with the user name ‘varnish’ and password ‘guessme’.

import dbrw;

sub vcl_recv {
    dbrw.config("mysql",
           "database=rewrite;user=varnish;password=guessme",
           {"SELECT dest
                FROM redirects
               WHERE host='$host'
                AND url='$url'"});
}

3.1 Expansions

The ‘query’ argument to the dbrw.config function normally contains variable references. A variable reference has the form ‘$variable’ or ‘${variable}’, where variable is the variable name. When the dbrw.rewrite function (see Rewrite) is called, each such reference is expanded to the actual value of 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 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.

${variable:-word}

Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.

${variable:=word}

Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.

${variable:?word}

Display Error if Null or Unset. If variable is null or unset, the expansion of word (or a message to that effect if word is not present) is output to the current logging channel. Otherwise, the value of variable is substituted.

${variable:+word}

Use Alternate Value. If variable is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

After expanding variables, the query undergoes command expansion. Syntactically, a command invocation is

$(cmd args)

where cmd is the command name, and 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 cmd with the supplied arguments.

As of version 2.7 of vmod-dbrw, only one function is declared:

Command: urlprefixes uri

Expands to comma-separated list of path prefixes contained in uri, starting from the longest one (uri itself, with eventual query part stripped off). Single ‘/’ is not included in the list. Each list item is quoted. The expansion can be used in the ‘IN ()’ SQL conditional.

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