aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2013-10-19 10:37:11 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2013-10-19 10:38:53 +0300
commitf74d13d7cd6c41f79a7efdea9364559ddc2bf438 (patch)
treefbfb65684c7fda6ecc40c95fc8e88e006e9ac2fa
parent405eeb454e6420ecef3ba0803c7033df414f33f1 (diff)
downloadvmod-sql-f74d13d7cd6c41f79a7efdea9364559ddc2bf438.tar.gz
vmod-sql-f74d13d7cd6c41f79a7efdea9364559ddc2bf438.tar.bz2
Add docs.release-1.0
* README: Update. * configure.ac: Update. * Makefile.am (SUBDIRS): Add doc. * doc/Makefile.am: New file. * doc/vmod-sql.3: New file. * doc/vmod_sql.3: New file.
-rw-r--r--Makefile.am2
-rw-r--r--README9
-rw-r--r--configure.ac3
-rw-r--r--doc/Makefile.am17
-rw-r--r--doc/vmod-sql.3270
-rw-r--r--doc/vmod_sql.31
6 files changed, 293 insertions, 9 deletions
diff --git a/Makefile.am b/Makefile.am
index d468b23..bb40beb 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -15,7 +15,7 @@
# along with vmod-sql. If not, see <http://www.gnu.org/licenses/>.
ACLOCAL_AMFLAGS = -I m4
-SUBDIRS = src #doc tests
+SUBDIRS = src doc #tests
AM_DISTCHECK_CONFIGURE_FLAGS=--without-vmoddir
diff --git a/README b/README
index 95d5c29..f6f6d9c 100644
--- a/README
+++ b/README
@@ -39,12 +39,9 @@ Finally, run the following command as root:
* Documentation
-A complete documentation in manpage and texinfo formats is shipped with
-the package, in the directory doc/. To read it without installing the
-package run `info -f doc/vmod-sql.info', or, to view the manpage:
-`man ./doc/vmod-sql.3'. After successful installation, the
-documentation can be accessed by running `info vmod-sql' and the manpage,
-by `man vmod-sql'.
+The manual page vmod-sql(3) will be available after successful install.
+To read it without actually installing the module, run
+`man src/vmod-sql.3'.
An online copy of the documentation is available from
http://www.gnu.org.ua/software/vmod-sql.
diff --git a/configure.ac b/configure.ac
index 7518483..a56b2e6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -177,11 +177,10 @@ esac
build_pgsql=$build_pgsql
build_mysql=$build_mysql])
-
dnl FIXME: tests/Makefile
-dnl FIXME: doc/Makefile
AC_CONFIG_FILES([
Makefile
+ doc/Makefile
src/Makefile
])
AC_OUTPUT
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..cce9417
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,17 @@
+# This file is part of vmod-sql
+# 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
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# 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 <http://www.gnu.org/licenses/>.
+
+dist_man_MANS = vmod-sql.3 vmod_sql.3
diff --git a/doc/vmod-sql.3 b/doc/vmod-sql.3
new file mode 100644
index 0000000..28dc2d4
--- /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
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" 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 <http://www.gnu.org/licenses/>.
+.TH VMOD-SQL 1 "October 19, 2013" "VMOD-SQL" "User Reference"
+.SH NAME
+vmod-sql \- SQL access for Varnish Cache
+.SH SYNOPSIS
+.B import sql;
+.PP
+.BI "INT sql.connect(STRING " dbtype ", STRING " params ");"
+.PP
+.BI "VOID sql.connect_init(STRING " dbtype ", STRING " params ");"
+.PP
+.BI "BOOL sql.query(INT " cd ", STRING " query ", STRING " params ");"
+.PP
+.BI "STRING sql.result(INT " cd ", INT " row ", INT " col ");"
+.PP
+.BI "INT sql.affected(INT " cd ");"
+.PP
+.BI "VOID sql.disconnect(INT " cd ");"
+.PP
+.BI "INT sql.ntuples(INT " cd ");"
+.PP
+.BI "INT sql.nfields(INT " cd ");"
+.PP
+.SH DESCRIPTION
+.B Vmod-sql
+provides functions for accessing SQL databases from
+.B Varnish
+configuration files. It supports
+.B MySQL
+and
+.BR PostgreSQL .
+.PP
+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.
+.PP
+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).
+.PP
+The
+.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:
+.PP
+.nf
+.ta 8n 18n 42n
+.ul
+ 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
+.fi
+.sp
+Any other character following a backslash is output verbatim.
+.sp
+The valid parameters are:
+.TP
+\fBdebug\fR=\fIN\fR
+Set debugging level. \fIN\fR is a decimal number.
+.TP
+\fBserver\fR=\fIHOST\fR
+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.
+.TP
+\fBport\fR=\fINUM\fR
+Port number on the \fBserver\fR to connect to. Default is \fB3306\fR
+for \fBMySQL\fR and \fB5432\fR for \fBPostgres\fR.
+.TP
+\fBdatabase=\fINAME\fR
+The database name.
+.TP
+\fBconfig\fR=\fIFILE\fR
+(\fBMySQL\fR-specific) Read credentials from the \fBMySQL\fR options
+file \fIFILE\fR.
+.TP
+\fBgroup\fR=\fINAME\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.
+.TP
+\fBcacert\fR=\fIFILE\fR
+Use secure connection to the database server via SSL. The \fIFILE\fR
+is a full pathname to the certificate authority file.
+.TP
+\fBoptions\fR=\fISTRING\fR
+(\fBPostgres\fR-specific) Connection options.
+.TP
+\fBuser\fR=\fINAME\fR
+Database user name.
+.TP
+\fBpassword\fR=\fISTRING\fR
+Password to access the database.
+.PP
+Up to 16 connections can be opened simultaneously (see the
+.B BUGS
+section).
+.PP
+On error, the function returns -1. On success, the returned
+descriptor will be the lowest-numbered descriptor not currently
+open for any connection.
+.PP
+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.
+.PP
+The function
+.B sql.disconnect
+closes an existing database connection identified by descriptor
+.BR cd .
+.PP
+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.
+.PP
+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.
+.PP
+Each expanded reference is then escaped to prevent SQL injection.
+.PP
+The function returns \fBTRUE\fR on success.
+.PP
+The result of the most recently executed query can be examined
+using the following functions:
+.TP
+.BI "INT sql.ntuples(INT " cd ");"
+Returns the number of tuples (rows) returned by the query.
+.TP
+.BI "INT sql.nfields(INT " cd ");"
+Returns the number of fields in each tuple returned by the query.
+.TP
+.BI "INT sql.affected(INT " cd ");"
+If the most recent query updated the database, returns the number of
+affected rows.
+.PP
+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).
+.PP
+.SH EXAMPLES
+The following \fBvcl\fR fragment can be used to keep a statistics
+of visits for each URL:
+.PP
+.EX
+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)
+ }
+}
+.EE
+.\" The MANCGI variable is set by man.cgi script on Ulysses.
+.\" The download.inc file contains the default DOWNLOAD section
+.\" for man-based doc pages.
+.if "\V[MANCGI]"WEBDOC" \{\
+. ds package vmod-sql
+. ds version 1.0
+. so download.inc
+\}
+.SH "SEE ALSO"
+.BR vmod-dbrw (3),
+.BR vcl (7),
+.BR varnishd (1).
+.PP
+.ie "\V[MANCGI]"WEBDOC" \{\
+Complete documentation for
+.B vmod-sql
+in various formats is
+.URL http://puszcza.gnu.org.ua/software/vmod-sql/manual.html "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
+.nf
+.in +4
+.B info vmod-sql
+.in
+.fi
+.PP
+should give you access to the complete manual.
+\}
+.SH BUGS
+Maximum number of simultaneously opened connections is limited to 16.
+To change this value, define \fBMAXCONN\fR when configuring the
+package, e.g.:
+.PP
+.EX
+./configure CPPFLAGS=-DMAXCONN=32
+.EE
+.PP
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2013 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+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:
diff --git a/doc/vmod_sql.3 b/doc/vmod_sql.3
new file mode 100644
index 0000000..ffdbe71
--- /dev/null
+++ b/doc/vmod_sql.3
@@ -0,0 +1 @@
+.so man3/vmod-sql.3

Return to:

Send suggestions and report system problems to the System administrator.