1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
lem-postgres
============
About
-----
lem-postgres is a [PostgreSQL][] library for the [Lua Event Machine][lem].
It allows you to query PostgreSQL databases without blocking
other coroutines.
[lem]: https://github.com/esmil/lem
[postgresql]: http://www.postgresql.org/
Installation
------------
Get the source and do
make
make install
This installs the library under `/usr/local/lib/lua/5.1/`.
Use
make PREFIX=<your custom path> install
to install to `<your custom path>/lib/lua/5.1/`.
Usage
-----
Import the module using something like
local postgres = require 'lem.postgres'
This sets `postgres` to a table with a single function.
* __postgres.connect(conninfo)__
Connect to the database given by parameters in the `conninfo` string.
Returns a new database connection object on success,
or otherwise `nil` followed by an error message.
The metatable of database connection objects can be found under
__postgres.Connection__.
Database connection objects has the following methods.
* __db:close()__
Close the database connection.
Returns `true` on success or otherwise `nil, 'already closed'`,
if the connection was already closed.
* __db:reset()__
Reset the database connection.
Returns `true` on success or otherwise `nil` followed by an error message.
If another coroutine is using this database connection the error message
will be `'busy'`.
If the connection is closed the error message will be `'closed'`.
If another coroutine closes this connection while the reset is going on
the error message be `'interrupted'`.
* __db:exec(query, ...)__
Execute an SQL query. If the query string is parametized
(using $1, $2 etc.) the parameters must be given after the
query string.
If the query is a SELECT the result will be returned in a Lua table
with entries 1, 2, ... for each row.
Each row is again a Lua table with entries 1, 2, ... for each
returned column.
Returns `true` or the result of the SELECT statement on success,
or otherwise `nil` followed by an error message.
If another coroutine is using this database connection the error message
will be `'busy'`.
If the connection is closed the error message will be `'closed'`.
If another coroutine closes this connection while the reset is going on
the error message be `'interrupted'`.
* __db:prepare(name, query)__
Creates a prepared SQL statement under the given name.
Returns `true` on success or otherwise `nil` followed by an error message.
If another coroutine is using this database connection the error message
will be `'busy'`.
If the connection is closed the error message will be `'closed'`.
If another coroutine closes this connection while the reset is going on
the error message be `'interrupted'`.
* __db:run(name, ...)__
Runs the prepared statement given by the name. If the statement
is parameterized (using $1, $2 etc.) the parameters must be given
after the name of the statement.
If the prepared statement is a SELECT the result will be returned in
a Lua table with entries 1, 2, ... for each row.
Each row is again a Lua table with entries 1, 2, ... for each
returned column.
Returns `true` or the result of the SELECT statement on success,
or otherwise `nil` followed by an error message.
If another coroutine is using this database connection the error message
will be `'busy'`.
If the connection is closed the error message will be `'closed'`.
If another coroutine closes this connection while the reset is going on
the error message be `'interrupted'`.
* __db:put(line)__
This method should be called after a `COPY <table> FROM STDIN`-query.
Call it once for each row in the table.
Returns `true` on success or otherwise `nil` followed by an error message.
* __db:done([error])__
When all rows of a `COPY <table> FROM STDIN`-query have been sent to the
server, call this method to signal end of transmission.
If an error message is supplied this will signal an error to the server.
Returns `true` on success or otherwise `nil` followed by an error message.
Calling this method with an error argument will also cause it to return
`nil` followed by an error message.
* __db:get()__
Call this method to receive rows after a `COPY <table> TO STDIN`-query.
Returns one complete line as a Lua string or `true` to signal end of
transmission.
On error `nil` followed by an error message will be returned.
License
-------
lem-postgres is free software. It is distributed under the terms of the
[GNU General Public License][gpl].
[gpl]: http://www.fsf.org/licensing/licenses/gpl.html
Contact
-------
Please send bug reports, patches, feature requests, praise and general gossip
to me, Emil Renner Berthing <esmil@mailme.dk>.
|
