vmod-dbrw User Manual (split by section):   Section:   Chapter:FastBack: Overview   Up: Top   FastForward: Query   Contents: Table of ContentsIndex: Concept Index

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:

SequenceReplaced by
\aAudible bell character (ASCII 7)
\bBackspace character (ASCII 8)
\fForm-feed character (ASCII 12)
\nNewline character (ASCII 10)
\rCarriage return character (ASCII 13)
\tHorizontal tabulation character (ASCII 9)
\vVertical 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'"});
}

vmod-dbrw User Manual (split by section):   Section:   Chapter:FastBack: Overview   Up: Top   FastForward: Query   Contents: Table of ContentsIndex: Concept Index