diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-10-19 10:37:11 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-10-19 10:38:53 +0300 |
commit | f74d13d7cd6c41f79a7efdea9364559ddc2bf438 (patch) | |
tree | fbfb65684c7fda6ecc40c95fc8e88e006e9ac2fa | |
parent | 405eeb454e6420ecef3ba0803c7033df414f33f1 (diff) | |
download | vmod-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.am | 2 | ||||
-rw-r--r-- | README | 9 | ||||
-rw-r--r-- | configure.ac | 3 | ||||
-rw-r--r-- | doc/Makefile.am | 17 | ||||
-rw-r--r-- | doc/vmod-sql.3 | 270 | ||||
-rw-r--r-- | doc/vmod_sql.3 | 1 |
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 | |||
@@ -17,3 +17,3 @@ ACLOCAL_AMFLAGS = -I m4 | |||
17 | 17 | ||
18 | SUBDIRS = src #doc tests | 18 | SUBDIRS = src doc #tests |
19 | 19 | ||
@@ -41,8 +41,5 @@ Finally, run the following command as root: | |||
41 | 41 | ||
42 | A complete documentation in manpage and texinfo formats is shipped with | 42 | The manual page vmod-sql(3) will be available after successful install. |
43 | the package, in the directory doc/. To read it without installing the | 43 | To read it without actually installing the module, run |
44 | package 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 | ||
46 | documentation can be accessed by running `info vmod-sql' and the manpage, | ||
47 | by `man vmod-sql'. | ||
48 | 45 | ||
diff --git a/configure.ac b/configure.ac index 7518483..a56b2e6 100644 --- a/configure.ac +++ b/configure.ac | |||
@@ -179,7 +179,6 @@ build_mysql=$build_mysql]) | |||
179 | 179 | ||
180 | |||
181 | dnl FIXME: tests/Makefile | 180 | dnl FIXME: tests/Makefile |
182 | dnl FIXME: doc/Makefile | ||
183 | AC_CONFIG_FILES([ | 181 | AC_CONFIG_FILES([ |
184 | Makefile | 182 | Makefile |
183 | doc/Makefile | ||
185 | src/Makefile | 184 | src/Makefile |
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 | |||
17 | 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 @@ | |||
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 | ||
18 | vmod-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 | ||
40 | provides functions for accessing SQL databases from | ||
41 | .B Varnish | ||
42 | configuration files. It supports | ||
43 | .B MySQL | ||
44 | and | ||
45 | .BR PostgreSQL . | ||
46 | .PP | ||
47 | Connection to a database is initiated by | ||
48 | .B sql.connect | ||
49 | function, which returns integer value, called | ||
50 | .BR "connection descriptor" " (" cd ). | ||
51 | This descriptor is passed as the first argument to the rest of | ||
52 | the module's functions to identify the connection. | ||
53 | .PP | ||
54 | The first argument to | ||
55 | .B sql.connect | ||
56 | specifies the database type to use. The valid values are \fBmysql\fR | ||
57 | (for \fBMySQL\fR) and \fBpgsql\fR (for \fBPostgreSQL\fR). | ||
58 | .PP | ||
59 | The | ||
60 | .I params | ||
61 | argument configures the connection. It is a list of | ||
62 | \fINAME\fB=\fIVALUE\fR assignments separated with semicolons. | ||
63 | The \fIVALUE\fR can be any sequence of characters, excepting white space | ||
64 | and semicolon. If any of these have to appear in it, they must either | ||
65 | be escaped by prepending them with a backslash, or the entire | ||
66 | \fIVALUE\fR must be enclosed in a pair of (single or double) quotes. | ||
67 | The 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 | ||
84 | Any other character following a backslash is output verbatim. | ||
85 | .sp | ||
86 | The valid parameters are: | ||
87 | .TP | ||
88 | \fBdebug\fR=\fIN\fR | ||
89 | Set debugging level. \fIN\fR is a decimal number. | ||
90 | .TP | ||
91 | \fBserver\fR=\fIHOST\fR | ||
92 | Name or IP address of the database server to connect to. If not | ||
93 | defined, localhost (\fB127.0.0.1\fR) is assumed. For \fBMySQL\fR | ||
94 | databases, if \fIHOST\fR begins with a slash (\fB/\fR), its value is | ||
95 | taken to be the full pathname of the local UNIX socket to connect to. | ||
96 | .TP | ||
97 | \fBport\fR=\fINUM\fR | ||
98 | Port number on the \fBserver\fR to connect to. Default is \fB3306\fR | ||
99 | for \fBMySQL\fR and \fB5432\fR for \fBPostgres\fR. | ||
100 | .TP | ||
101 | \fBdatabase=\fINAME\fR | ||
102 | The database name. | ||
103 | .TP | ||
104 | \fBconfig\fR=\fIFILE\fR | ||
105 | (\fBMySQL\fR-specific) Read credentials from the \fBMySQL\fR options | ||
106 | file \fIFILE\fR. | ||
107 | .TP | ||
108 | \fBgroup\fR=\fINAME\fR | ||
109 | (\fBMySQL\fR-specific) Read credentials from section \fINAME\fR of the | ||
110 | options file supplied with the \fBconfig\fR parameter. Default | ||
111 | section name is \fBclient\fR. | ||
112 | .TP | ||
113 | \fBcacert\fR=\fIFILE\fR | ||
114 | Use secure connection to the database server via SSL. The \fIFILE\fR | ||
115 | is 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 | ||
121 | Database user name. | ||
122 | .TP | ||
123 | \fBpassword\fR=\fISTRING\fR | ||
124 | Password to access the database. | ||
125 | .PP | ||
126 | Up to 16 connections can be opened simultaneously (see the | ||
127 | .B BUGS | ||
128 | section). | ||
129 | .PP | ||
130 | On error, the function returns -1. On success, the returned | ||
131 | descriptor will be the lowest-numbered descriptor not currently | ||
132 | open for any connection. | ||
133 | .PP | ||
134 | The function | ||
135 | .B sql.connect0 | ||
136 | is equivalent to | ||
137 | .BR sql.connect , | ||
138 | but succeeds only if the connection is assigned the descriptor | ||
139 | \fB0\fR. This function is provided as a shortcut to use when only | ||
140 | one database connection is needed. | ||
141 | .PP | ||
142 | The function | ||
143 | .B sql.disconnect | ||
144 | closes an existing database connection identified by descriptor | ||
145 | .BR cd . | ||
146 | .PP | ||
147 | The function | ||
148 | .B sql.query | ||
149 | performs a database query given as its first argument. The second | ||
150 | argument is a list of variable assignments separated with | ||
151 | semicolons, similarly to the \fIparams\fR argument described above. | ||
152 | Each assignment has the form \fINAME\fB=\fIVALUE\fR. | ||
153 | .PP | ||
154 | Before being executed, the query is expanded by replacing each | ||
155 | occurrence of \fB$\fINAME\fR construct (a \fBvariable reference\fR) | ||
156 | with the corresponding \fIVALUE\fR from the \fIparams\fR argument. | ||
157 | Similarly to the shell syntax, the variable reference can be written | ||
158 | as \fB${\fINAME\fB}\fR. This latter form can be used in contexts | ||
159 | where the variable name is immediately followed by another letter, to | ||
160 | prevent it from being counted as a part of the name. | ||
161 | .PP | ||
162 | Each expanded reference is then escaped to prevent SQL injection. | ||
163 | .PP | ||
164 | The function returns \fBTRUE\fR on success. | ||
165 | .PP | ||
166 | The result of the most recently executed query can be examined | ||
167 | using the following functions: | ||
168 | .TP | ||
169 | .BI "INT sql.ntuples(INT " cd ");" | ||
170 | Returns the number of tuples (rows) returned by the query. | ||
171 | .TP | ||
172 | .BI "INT sql.nfields(INT " cd ");" | ||
173 | Returns the number of fields in each tuple returned by the query. | ||
174 | .TP | ||
175 | .BI "INT sql.affected(INT " cd ");" | ||