path: root/doc/vmod-sql.3
Side-by-side diff
Diffstat (limited to 'doc/vmod-sql.3') (more/less context) (ignore whitespace changes)
1 files changed, 270 insertions, 0 deletions
diff --git a/doc/vmod-sql.3 b/doc/vmod-sql.3
new file mode 100644
index 0000000..28dc2d4
--- a/dev/null
+++ b/doc/vmod-sql.3
@@ -0,0 +1,270 @@
+.\" This file is part of Vmod-sql -*- nroff -*-
+.\" Copyright (C) 2013 Sergey Poznyakoff
+.\" Vmod-sql is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\" Vmod-sql is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" GNU General Public License for more details.
+.\" You should have received a copy of the GNU General Public License
+.\" along with vmod-sql. If not, see <>.
+.TH VMOD-SQL 1 "October 19, 2013" "VMOD-SQL" "User Reference"
+vmod-sql \- SQL access for Varnish Cache
+.B import sql;
+.BI "INT sql.connect(STRING " dbtype ", STRING " params ");"
+.BI "VOID sql.connect_init(STRING " dbtype ", STRING " params ");"
+.BI "BOOL sql.query(INT " cd ", STRING " query ", STRING " params ");"
+.BI "STRING sql.result(INT " cd ", INT " row ", INT " col ");"
+.BI "INT sql.affected(INT " cd ");"
+.BI "VOID sql.disconnect(INT " cd ");"
+.BI "INT sql.ntuples(INT " cd ");"
+.BI "INT sql.nfields(INT " cd ");"
+.B Vmod-sql
+provides functions for accessing SQL databases from
+.B Varnish
+configuration files. It supports
+.BR PostgreSQL .
+Connection to a database is initiated by
+.B sql.connect
+function, which returns integer value, called
+.BR "connection descriptor" " (" cd ).
+This descriptor is passed as the first argument to the rest of
+the module's functions to identify the connection.
+The first argument to
+.B sql.connect
+specifies the database type to use. The valid values are \fBmysql\fR
+(for \fBMySQL\fR) and \fBpgsql\fR (for \fBPostgreSQL\fR).
+.I params
+argument configures the connection. It is a list of
+\fINAME\fB=\fIVALUE\fR assignments separated with semicolons.
+The \fIVALUE\fR can be any sequence of characters, excepting white space
+and semicolon. If any of these have to appear in it, they must either
+be escaped by prepending them with a backslash, or the entire
+\fIVALUE\fR must be enclosed in a pair of (single or double) quotes.
+The following \fBescape sequences\fR are allowed for use in \fIVALUE\fR:
+.ta 8n 18n 42n
+ Sequence Expansion ASCII
+ \fB\\\\\fR \fB\\\fR 134
+ \fB\\"\fR \fB"\fR 042
+ \fB\\a\fR audible bell 007
+ \fB\\b\fR backspace 010
+ \fB\\f\fR form-feed 014
+ \fB\\n\fR new line 012
+ \fB\\r\fR charriage return 015
+ \fB\\t\fR horizontal tabulation 011
+ \fB\\v\fR vertical tabulation 013
+Any other character following a backslash is output verbatim.
+The valid parameters are:
+Set debugging level. \fIN\fR is a decimal number.
+Name or IP address of the database server to connect to. If not
+defined, localhost (\fB127.0.0.1\fR) is assumed. For \fBMySQL\fR
+databases, if \fIHOST\fR begins with a slash (\fB/\fR), its value is
+taken to be the full pathname of the local UNIX socket to connect to.
+Port number on the \fBserver\fR to connect to. Default is \fB3306\fR
+for \fBMySQL\fR and \fB5432\fR for \fBPostgres\fR.
+The database name.
+(\fBMySQL\fR-specific) Read credentials from the \fBMySQL\fR options
+file \fIFILE\fR.
+(\fBMySQL\fR-specific) Read credentials from section \fINAME\fR of the
+options file supplied with the \fBconfig\fR parameter. Default
+section name is \fBclient\fR.
+Use secure connection to the database server via SSL. The \fIFILE\fR
+is a full pathname to the certificate authority file.
+(\fBPostgres\fR-specific) Connection options.
+Database user name.
+Password to access the database.
+Up to 16 connections can be opened simultaneously (see the
+On error, the function returns -1. On success, the returned
+descriptor will be the lowest-numbered descriptor not currently
+open for any connection.
+The function
+.B sql.connect0
+is equivalent to
+.BR sql.connect ,
+but succeeds only if the connection is assigned the descriptor
+\fB0\fR. This function is provided as a shortcut to use when only
+one database connection is needed.
+The function
+.B sql.disconnect
+closes an existing database connection identified by descriptor
+.BR cd .
+The function
+.B sql.query
+performs a database query given as its first argument. The second
+argument is a list of variable assignments separated with
+semicolons, similarly to the \fIparams\fR argument described above.
+Each assignment has the form \fINAME\fB=\fIVALUE\fR.
+Before being executed, the query is expanded by replacing each
+occurrence of \fB$\fINAME\fR construct (a \fBvariable reference\fR)
+with the corresponding \fIVALUE\fR from the \fIparams\fR argument.
+Similarly to the shell syntax, the variable reference can be written
+as \fB${\fINAME\fB}\fR. This latter form can be used in contexts
+where the variable name is immediately followed by another letter, to
+prevent it from being counted as a part of the name.
+Each expanded reference is then escaped to prevent SQL injection.
+The function returns \fBTRUE\fR on success.
+The result of the most recently executed query can be examined
+using the following functions:
+.BI "INT sql.ntuples(INT " cd ");"
+Returns the number of tuples (rows) returned by the query.
+.BI "INT sql.nfields(INT " cd ");"
+Returns the number of fields in each tuple returned by the query.
+.BI "INT sql.affected(INT " cd ");"
+If the most recent query updated the database, returns the number of
+affected rows.
+The values returned by the most recent query can be retrieved
+using the
+.B sql.result
+function. The desired value is identified by the row and column
+number (both 0-based).
+The following \fBvcl\fR fragment can be used to keep a statistics
+of visits for each URL:
+vcl_init {
+ sql.connect0("mysql", "config=/etc/db.cnf");
+vcl_recv {
+ if (sql.query(0,
+ {"UPDATE counter SET count=count+1
+ WHERE url='$url'"},
+ "url=" + req.url)) {
+ sql.query(0,
+ "INSERT INTO counter values ('$url', 1)",
+ "url=" + req.url)
+ }
+.\" The MANCGI variable is set by man.cgi script on Ulysses.
+.\" The file contains the default DOWNLOAD section
+.\" for man-based doc pages.
+.if "\V[MANCGI]"WEBDOC" \{\
+. ds package vmod-sql
+. ds version 1.0
+. so
+.BR vmod-dbrw (3),
+.BR vcl (7),
+.BR varnishd (1).
+Complete documentation for
+.B vmod-sql
+in various formats is
+.URL "available online" .
+.el \{\
+The full documentation for
+.B vmod-sql
+is maintained as a Texinfo
+manual. If the
+.B info
+program and
+.B vmod-sql
+module are properly installed at your site, the command
+.PP +4
+.B info vmod-sql
+should give you access to the complete manual.
+Maximum number of simultaneously opened connections is limited to 16.
+To change this value, define \fBMAXCONN\fR when configuring the
+package, e.g.:
+./configure CPPFLAGS=-DMAXCONN=32
+Sergey Poznyakoff
+Report bugs to <>.
+Copyright \(co 2013 Sergey Poznyakoff
+License GPLv3+: GNU GPL version 3 or later <>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:

Return to:

Send suggestions and report system problems to the System administrator.