Skip to content

Commit d010514

Browse files
agentzhagentzh
committed
doc: added Table of Contents.
1 parent e9decee commit d010514

File tree

1 file changed

+88
-0
lines changed

1 file changed

+88
-0
lines changed

‎README.markdown

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,40 @@ Name
33

44
lua-resty-mysql - Lua MySQL client driver for ngx_lua based on the cosocket API
55

6+
Table of Contents
7+
=================
8+
9+
* [Name](#name)
10+
* [Status](#status)
11+
* [Description](#description)
12+
* [Synopsis](#synopsis)
13+
* [Methods](#methods)
14+
* [new](#new)
15+
* [connect](#connect)
16+
* [set_timeout](#set_timeout)
17+
* [set_keepalive](#set_keepalive)
18+
* [get_reused_times](#get_reused_times)
19+
* [close](#close)
20+
* [send_query](#send_query)
21+
* [read_result](#read_result)
22+
* [query](#query)
23+
* [server_ver](#server_ver)
24+
* [set_compact_arrays](#set_compact_arrays)
25+
* [SQL Literal Quoting](#sql-literal-quoting)
26+
* [Multi-Resultset Support](#multi-resultset-support)
27+
* [Debugging](#debugging)
28+
* [Automatic Error Logging](#automatic-error-logging)
29+
* [Limitations](#limitations)
30+
* [Installation](#installation)
31+
* [Community](#community)
32+
* [English Mailing List](#english-mailing-list)
33+
* [Chinese Mailing List](#chinese-mailing-list)
34+
* [Bugs and Patches](#bugs-and-patches)
35+
* [TODO](#todo)
36+
* [Author](#author)
37+
* [Copyright and License](#copyright-and-license)
38+
* [See Also](#see-also)
39+
640
Status
741
======
842

@@ -127,15 +161,21 @@ Synopsis
127161
}
128162
```
129163

164+
[Back to TOC](#table-of-contents)
165+
130166
Methods
131167
=======
132168

169+
[Back to TOC](#table-of-contents)
170+
133171
new
134172
---
135173
`syntax: db, err = mysql:new()`
136174

137175
Creates a MySQL connection object. In case of failures, returns `nil` and a string describing the error.
138176

177+
[Back to TOC](#table-of-contents)
178+
139179
connect
140180
-------
141181
`syntax: ok, err = db:connect(options)`
@@ -165,12 +205,16 @@ The `options` argument is a Lua table holding the following keys:
165205

166206
Before actually resolving the host name and connecting to the remote backend, this method will always look up the connection pool for matched idle connections created by previous calls of this method.
167207

208+
[Back to TOC](#table-of-contents)
209+
168210
set_timeout
169211
----------
170212
`syntax: db:set_timeout(time)`
171213

172214
Sets the timeout (in ms) protection for subsequent operations, including the `connect` method.
173215

216+
[Back to TOC](#table-of-contents)
217+
174218
set_keepalive
175219
------------
176220
`syntax: ok, err = db:set_keepalive(max_idle_timeout, pool_size)`
@@ -183,6 +227,8 @@ In case of success, returns `1`. In case of errors, returns `nil` with a string
183227

184228
Only call this method in the place you would have called the `close` method instead. Calling this method will immediately turn the current `resty.mysql` object into the `closed` state. Any subsequent operations other than `connect()` on the current objet will return the `closed` error.
185229

230+
[Back to TOC](#table-of-contents)
231+
186232
get_reused_times
187233
----------------
188234
`syntax: times, err = db:get_reused_times()`
@@ -191,6 +237,8 @@ This method returns the (successfully) reused times for the current connection.
191237

192238
If the current connection does not come from the built-in connection pool, then this method always returns `0`, that is, the connection has never been reused (yet). If the connection comes from the connection pool, then the return value is always non-zero. So this method can also be used to determine if the current connection comes from the pool.
193239

240+
[Back to TOC](#table-of-contents)
241+
194242
close
195243
-----
196244
`syntax: ok, err = db:close()`
@@ -199,6 +247,8 @@ Closes the current mysql connection and returns the status.
199247

200248
In case of success, returns `1`. In case of errors, returns `nil` with a string describing the error.
201249

250+
[Back to TOC](#table-of-contents)
251+
202252
send_query
203253
----------
204254
`syntax: bytes, err = db:send_query(query)`
@@ -209,6 +259,8 @@ Returns the bytes successfully sent out in success and otherwise returns `nil` a
209259

210260
You should use the [read_result](#read_result) method to read the MySQL replies afterwards.
211261

262+
[Back to TOC](#table-of-contents)
263+
212264
read_result
213265
-----------
214266
`syntax: res, err, errno, sqlstate = db:read_result()`
@@ -247,6 +299,8 @@ In case of errors, this method returns at most 4 values: `nil`, `err`, `errcode`
247299
The optional argument `est_nrows` can be used to specify an approximate number of rows for the result set. This value can be used
248300
to pre-allocate space in the resulting Lua table for the result set. By default, it takes the value 4.
249301

302+
[Back to TOC](#table-of-contents)
303+
250304
query
251305
-----
252306
`syntax: res, err, errcode, sqlstate = db:query(query)`
@@ -257,6 +311,8 @@ This is a shortcut for combining the [send_query](#send_query) call and the firs
257311

258312
You should always check if the `err` return value is `again` in case of success because this method will only call [read_result](#read_result) only once for you. See also [Multi-Resultset Support](#multi-resultset-support).
259313

314+
[Back to TOC](#table-of-contents)
315+
260316
server_ver
261317
----------
262318
`syntax: str = db:server_ver()`
@@ -265,6 +321,8 @@ Returns the MySQL server version string, like `"5.1.64"`.
265321

266322
You should only call this method after successfully connecting to a MySQL server, otherwise `nil` will be returned.
267323

324+
[Back to TOC](#table-of-contents)
325+
268326
set_compact_arrays
269327
------------------
270328
`syntax: db:set_compact_arrays(boolean)`
@@ -273,6 +331,8 @@ Sets whether to use the "compact-arrays" structure for the resultsets returned b
273331

274332
This method was first introduced in the `v0.09` release.
275333

334+
[Back to TOC](#table-of-contents)
335+
276336
SQL Literal Quoting
277337
===================
278338

@@ -286,6 +346,8 @@ Here is an example:
286346
local sql = "select * from users where name = " .. quoted_name
287347
```
288348

349+
[Back to TOC](#table-of-contents)
350+
289351
Multi-Resultset Support
290352
=======================
291353

@@ -343,6 +405,8 @@ This code snippet will produce the following response body data:
343405
result #2: [{"2":"2"}]
344406
result #3: [{"3":"3"}]
345407

408+
[Back to TOC](#table-of-contents)
409+
346410
Debugging
347411
=========
348412

@@ -357,6 +421,8 @@ It is usually convenient to use the [lua-cjson](http://www.kyne.com.au/~mark/sof
357421
end
358422
```
359423

424+
[Back to TOC](#table-of-contents)
425+
360426
Automatic Error Logging
361427
=======================
362428

@@ -368,6 +434,8 @@ handling in your own Lua code, then you are recommended to disable this automati
368434
lua_socket_log_errors off;
369435
```
370436

437+
[Back to TOC](#table-of-contents)
438+
371439
Limitations
372440
===========
373441

@@ -382,6 +450,8 @@ You should always initiate `resty.mysql` objects in function local
382450
variables or in the `ngx.ctx` table. These places all have their own data copies for
383451
each request.
384452

453+
[Back to TOC](#table-of-contents)
454+
385455
Installation
386456
============
387457

@@ -410,19 +480,27 @@ tree to ngx_lua's LUA_PATH search path, as in
410480
Ensure that the system account running your Nginx ''worker'' proceses have
411481
enough permission to read the `.lua` file.
412482

483+
[Back to TOC](#table-of-contents)
484+
413485
Community
414486
=========
415487

488+
[Back to TOC](#table-of-contents)
489+
416490
English Mailing List
417491
--------------------
418492

419493
The [openresty-en](https://groups.google.com/group/openresty-en) mailing list is for English speakers.
420494

495+
[Back to TOC](#table-of-contents)
496+
421497
Chinese Mailing List
422498
--------------------
423499

424500
The [openresty](https://groups.google.com/group/openresty) mailing list is for Chinese speakers.
425501

502+
[Back to TOC](#table-of-contents)
503+
426504
Bugs and Patches
427505
================
428506

@@ -431,6 +509,8 @@ Please submit bug reports, wishlists, or patches by
431509
1. creating a ticket on the [GitHub Issue Tracker](http://github.com/agentzh/lua-resty-mysql/issues),
432510
1. or posting to the [OpenResty community](http://wiki.nginx.org/HttpLuaModule#Community).
433511

512+
[Back to TOC](#table-of-contents)
513+
434514
TODO
435515
====
436516

@@ -440,11 +520,15 @@ TODO
440520
* implement MySQL server prepare and execute packets.
441521
* implement the data compression support in the protocol.
442522

523+
[Back to TOC](#table-of-contents)
524+
443525
Author
444526
======
445527

446528
Yichun "agentzh" Zhang (章亦春) <[email protected]>, CloudFlare Inc.
447529

530+
[Back to TOC](#table-of-contents)
531+
448532
Copyright and License
449533
=====================
450534

@@ -462,6 +546,8 @@ Redistribution and use in source and binary forms, with or without modification,
462546

463547
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
464548

549+
[Back to TOC](#table-of-contents)
550+
465551
See Also
466552
========
467553
* the ngx_lua module: http://wiki.nginx.org/HttpLuaModule
@@ -470,3 +556,5 @@ See Also
470556
* the [lua-resty-redis](https://github.com/agentzh/lua-resty-redis) library
471557
* the ngx_drizzle module: http://wiki.nginx.org/HttpDrizzleModule
472558

559+
[Back to TOC](#table-of-contents)
560+

0 commit comments

Comments
 (0)