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
@@ -12,13 +12,13 @@
12# GNU General Public License for more details. 12# GNU General Public License for more details.
13# 13#
14# You should have received a copy of the GNU General Public License 14# You should have received a copy of the GNU General Public License
15# along with vmod-sql. If not, see <http://www.gnu.org/licenses/>. 15# along with vmod-sql. If not, see <http://www.gnu.org/licenses/>.
16ACLOCAL_AMFLAGS = -I m4 16ACLOCAL_AMFLAGS = -I m4
17 17
18SUBDIRS = src #doc tests 18SUBDIRS = src doc #tests
19 19
20AM_DISTCHECK_CONFIGURE_FLAGS=--without-vmoddir 20AM_DISTCHECK_CONFIGURE_FLAGS=--without-vmoddir
21 21
22EXTRA_DIST=git2chg.awk 22EXTRA_DIST=git2chg.awk
23 23
24.PHONY: ChangeLog 24.PHONY: ChangeLog
diff --git a/README b/README
index 95d5c29..f6f6d9c 100644
--- a/README
+++ b/README
@@ -36,18 +36,15 @@ This will build the module. After this step you can optionally run
36Finally, run the following command as root: 36Finally, run the following command as root:
37 37
38 make install 38 make install
39 39
40* Documentation 40* Documentation
41 41
42A complete documentation in manpage and texinfo formats is shipped with 42The manual page vmod-sql(3) will be available after successful install.
43the package, in the directory doc/. To read it without installing the 43To read it without actually installing the module, run
44package run `info -f doc/vmod-sql.info', or, to view the manpage: 44`man src/vmod-sql.3'.
45`man ./doc/vmod-sql.3'. After successful installation, the
46documentation can be accessed by running `info vmod-sql' and the manpage,
47by `man vmod-sql'.
48 45
49An online copy of the documentation is available from 46An online copy of the documentation is available from
50http://www.gnu.org.ua/software/vmod-sql. 47http://www.gnu.org.ua/software/vmod-sql.
51 48
52* Bug reporting 49* Bug reporting
53 50
diff --git a/configure.ac b/configure.ac
index 7518483..a56b2e6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -174,15 +174,14 @@ case "$res" in
174 AC_MSG_ERROR([Nothing to build?]) 174 AC_MSG_ERROR([Nothing to build?])
175esac 175esac
176],[ 176],[
177build_pgsql=$build_pgsql 177build_pgsql=$build_pgsql
178build_mysql=$build_mysql]) 178build_mysql=$build_mysql])
179 179
180
181dnl FIXME: tests/Makefile 180dnl FIXME: tests/Makefile
182dnl FIXME: doc/Makefile
183AC_CONFIG_FILES([ 181AC_CONFIG_FILES([
184 Makefile 182 Makefile
183 doc/Makefile
185 src/Makefile 184 src/Makefile
186]) 185])
187AC_OUTPUT 186AC_OUTPUT
188 187
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 @@
1# This file is part of vmod-sql
2# Copyright (C) 2013 Sergey Poznyakoff
3#
4# Vmod-sql is free software; you can redistribute it and/or modify
5# it under the terms of the GNU General Public License as published by
6# the Free Software Foundation; either version 3, or (at your option)
7# any later version.
8#
9# Vmod-sql is distributed in the hope that it will be useful,
10# but WITHOUT ANY WARRANTY; without even the implied warranty of
11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12# GNU General Public License for more details.
13#
14# You should have received a copy of the GNU General Public License
15# along with vmod-sql. If not, see <http://www.gnu.org/licenses/>.
16
17dist_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 @@
1.\" This file is part of Vmod-sql -*- nroff -*-
2.\" Copyright (C) 2013 Sergey Poznyakoff
3.\"
4.\" Vmod-sql is free software; you can redistribute it and/or modify
5.\" it under the terms of the GNU General Public License as published by
6.\" the Free Software Foundation; either version 3, or (at your option)
7.\" any later version.
8.\"
9.\" Vmod-sql is distributed in the hope that it will be useful,
10.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12.\" GNU General Public License for more details.
13.\"
14.\" You should have received a copy of the GNU General Public License
15.\" along with vmod-sql. If not, see <http://www.gnu.org/licenses/>.
16.TH VMOD-SQL 1 "October 19, 2013" "VMOD-SQL" "User Reference"
17.SH NAME
18vmod-sql \- SQL access for Varnish Cache
19.SH SYNOPSIS
20.B import sql;
21.PP
22.BI "INT sql.connect(STRING " dbtype ", STRING " params ");"
23.PP
24.BI "VOID sql.connect_init(STRING " dbtype ", STRING " params ");"
25.PP
26.BI "BOOL sql.query(INT " cd ", STRING " query ", STRING " params ");"
27.PP
28.BI "STRING sql.result(INT " cd ", INT " row ", INT " col ");"
29.PP
30.BI "INT sql.affected(INT " cd ");"
31.PP
32.BI "VOID sql.disconnect(INT " cd ");"
33.PP
34.BI "INT sql.ntuples(INT " cd ");"
35.PP
36.BI "INT sql.nfields(INT " cd ");"
37.PP
38.SH DESCRIPTION
39.B Vmod-sql
40provides functions for accessing SQL databases from
41.B Varnish
42configuration files. It supports
43.B MySQL
44and
45.BR PostgreSQL .
46.PP
47Connection to a database is initiated by
48.B sql.connect
49function, which returns integer value, called
50.BR "connection descriptor" " (" cd ).
51This descriptor is passed as the first argument to the rest of
52the module's functions to identify the connection.
53.PP
54The first argument to
55.B sql.connect
56specifies the database type to use. The valid values are \fBmysql\fR
57(for \fBMySQL\fR) and \fBpgsql\fR (for \fBPostgreSQL\fR).
58.PP
59The
60.I params
61argument configures the connection. It is a list of
62\fINAME\fB=\fIVALUE\fR assignments separated with semicolons.
63The \fIVALUE\fR can be any sequence of characters, excepting white space
64and semicolon. If any of these have to appear in it, they must either
65be escaped by prepending them with a backslash, or the entire
66\fIVALUE\fR must be enclosed in a pair of (single or double) quotes.
67The following \fBescape sequences\fR are allowed for use in \fIVALUE\fR:
68.PP
69.nf
70.ta 8n 18n 42n
71.ul
72 Sequence Expansion ASCII
73 \fB\\\\\fR \fB\\\fR 134
74 \fB\\"\fR \fB"\fR 042
75 \fB\\a\fR audible bell 007
76 \fB\\b\fR backspace 010
77 \fB\\f\fR form-feed 014
78 \fB\\n\fR new line 012
79 \fB\\r\fR charriage return 015
80 \fB\\t\fR horizontal tabulation 011
81 \fB\\v\fR vertical tabulation 013
82.fi
83.sp
84Any other character following a backslash is output verbatim.
85.sp
86The valid parameters are:
87.TP
88\fBdebug\fR=\fIN\fR
89Set debugging level. \fIN\fR is a decimal number.
90.TP
91\fBserver\fR=\fIHOST\fR
92Name or IP address of the database server to connect to. If not
93defined, localhost (\fB127.0.0.1\fR) is assumed. For \fBMySQL\fR
94databases, if \fIHOST\fR begins with a slash (\fB/\fR), its value is
95taken to be the full pathname of the local UNIX socket to connect to.
96.TP
97\fBport\fR=\fINUM\fR
98Port number on the \fBserver\fR to connect to. Default is \fB3306\fR
99for \fBMySQL\fR and \fB5432\fR for \fBPostgres\fR.
100.TP
101\fBdatabase=\fINAME\fR
102The database name.
103.TP
104\fBconfig\fR=\fIFILE\fR
105(\fBMySQL\fR-specific) Read credentials from the \fBMySQL\fR options
106file \fIFILE\fR.
107.TP
108\fBgroup\fR=\fINAME\fR
109(\fBMySQL\fR-specific) Read credentials from section \fINAME\fR of the
110options file supplied with the \fBconfig\fR parameter. Default
111section name is \fBclient\fR.
112.TP
113\fBcacert\fR=\fIFILE\fR
114Use secure connection to the database server via SSL. The \fIFILE\fR
115is a full pathname to the certificate authority file.
116.TP
117\fBoptions\fR=\fISTRING\fR
118(\fBPostgres\fR-specific) Connection options.
119.TP
120\fBuser\fR=\fINAME\fR
121Database user name.
122.TP
123\fBpassword\fR=\fISTRING\fR
124Password to access the database.
125.PP
126Up to 16 connections can be opened simultaneously (see the
127.B BUGS
128section).
129.PP
130On error, the function returns -1. On success, the returned
131descriptor will be the lowest-numbered descriptor not currently
132open for any connection.
133.PP
134The function
135.B sql.connect0
136is equivalent to
137.BR sql.connect ,