| rev |
line source |
|
jbe@23
|
1
|
|
jbe@23
|
2 --[[--
|
|
jbe@23
|
3 db_handle, -- database handle, or nil in case of error
|
|
jbe@23
|
4 errmsg, -- error message
|
|
jbe@404
|
5 db_error = -- error object
|
|
jbe@23
|
6 mondelefant.connect{
|
|
jbe@40
|
7 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq
|
|
jbe@23
|
8 host = host, -- hostname or directory with leading slash where Unix-domain socket resides
|
|
jbe@23
|
9 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported
|
|
jbe@23
|
10 port = port, -- TCP port or socket file name extension
|
|
jbe@23
|
11 dbname = dbname, -- name of database to connect with
|
|
jbe@23
|
12 user = user, -- login name
|
|
jbe@23
|
13 password = password, -- password
|
|
jbe@23
|
14 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite
|
|
jbe@23
|
15 ...
|
|
jbe@23
|
16 }
|
|
jbe@23
|
17
|
|
jbe@403
|
18 Opens a new database connection and returns a handle for that connection. You may chose to specify host, port, dbname, etc. as seperated arguments, or to use a "conninfo" string, which is directly passed to PostgreSQL's libpq. In the latter case, the "conninfo" string may also be passed directly as first argument to the connect function without supplying a table.
|
|
jbe@23
|
19
|
|
jbe@23
|
20 --]]--
|
|
jbe@23
|
21 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
22 -- static int mondelefant_connect(lua_State *L)
|
|
jbe@23
|
23 --//--
|
|
jbe@23
|
24
|
|
jbe@23
|
25
|
|
jbe@23
|
26 --[[--
|
|
jbe@393
|
27 <db_handle>.fd -- file descriptor of underlaying database connection
|
|
jbe@393
|
28
|
|
jbe@393
|
29 The file descriptor number of the underlaying database connection. This value may be used in conjunction with :wait(0) and a select/poll system call to wait for several events at once.
|
|
jbe@393
|
30
|
|
jbe@393
|
31 --]]--
|
|
jbe@393
|
32 -- set/unset in mondelefant_native.c in
|
|
jbe@393
|
33 -- static int mondelefant_connect(lua_State *L) and
|
|
jbe@393
|
34 -- static int mondelefant_close(lua_State *L)
|
|
jbe@393
|
35 --//--
|
|
jbe@393
|
36
|
|
jbe@393
|
37
|
|
jbe@393
|
38 --[[--
|
|
jbe@23
|
39 <db_handle>:close()
|
|
jbe@23
|
40
|
|
jbe@23
|
41 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.
|
|
jbe@23
|
42
|
|
jbe@23
|
43 --]]--
|
|
jbe@23
|
44 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
45 -- static int mondelefant_conn_close(lua_State *L)
|
|
jbe@23
|
46 --//--
|
|
jbe@23
|
47
|
|
jbe@23
|
48
|
|
jbe@23
|
49 --[[--
|
|
jbe@23
|
50 status = -- true, if database connection has no malfunction
|
|
jbe@23
|
51 <db_handle>:is_ok()
|
|
jbe@23
|
52
|
|
jbe@23
|
53 Returns false, if the database connection has a malfunction, otherwise true.
|
|
jbe@23
|
54
|
|
jbe@23
|
55 --]]--
|
|
jbe@23
|
56 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
57 -- static int mondelefant_conn_is_ok(lua_State *L)
|
|
jbe@23
|
58 --//--
|
|
jbe@23
|
59
|
|
jbe@23
|
60
|
|
jbe@23
|
61 --[[--
|
|
jbe@23
|
62 status = -- status string
|
|
jbe@23
|
63 <db_handle>:get_transaction_status()
|
|
jbe@23
|
64
|
|
jbe@23
|
65 Depending on the transaction status of the connection a string is returned:
|
|
jbe@23
|
66 - idle
|
|
jbe@23
|
67 - active
|
|
jbe@23
|
68 - intrans
|
|
jbe@23
|
69 - inerror
|
|
jbe@23
|
70 - unknown
|
|
jbe@23
|
71
|
|
jbe@23
|
72 --]]--
|
|
jbe@23
|
73 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
74 -- static int mondelefant_conn_get_transaction_status(lua_State *L)
|
|
jbe@23
|
75 --//--
|
|
jbe@23
|
76
|
|
jbe@23
|
77
|
|
jbe@23
|
78 --[[--
|
|
jbe@397
|
79 db_error, -- error object, or nil in case of success or timeout
|
|
jbe@397
|
80 channel, -- notification channel name, or nil in case of timeout or no pending notify
|
|
jbe@397
|
81 payload, -- notification payload string
|
|
jbe@397
|
82 pid = -- process ID of notifying server process
|
|
jbe@397
|
83 <db_handle>:try_wait(
|
|
jbe@397
|
84 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely
|
|
jbe@393
|
85 )
|
|
jbe@393
|
86
|
|
jbe@393
|
87 Waits for any NOTIFY event that is being LISTENed for. One or more LISTEN commands must have been sent previously with <db_handle>:query("LISTEN channel_name").
|
|
jbe@393
|
88
|
|
jbe@393
|
89 --]]--
|
|
jbe@393
|
90 -- implemented in mondelefant_native.c as
|
|
jbe@397
|
91 -- static int mondelefant_conn_try_wait(lua_State *L)
|
|
jbe@393
|
92 --//--
|
|
jbe@393
|
93
|
|
jbe@393
|
94
|
|
jbe@393
|
95 --[[--
|
|
jbe@440
|
96 db_list = -- database result being an empty list (or filled list)
|
|
jbe@440
|
97 <db_handle>:create_list(
|
|
jbe@440
|
98 tbl -- optional table to be converted to a filled list
|
|
jbe@440
|
99 )
|
|
jbe@23
|
100
|
|
jbe@440
|
101 Creates a database result representing a list. The used meta-table is "result_metatable". The attribute "_connection" is set to the database handle, and the attribute "_type" is set to "list". The attribute "_class" is initialized to the default class prototype "class_prototype" of the module.
|
|
jbe@23
|
102
|
|
jbe@23
|
103 --]]--
|
|
jbe@23
|
104 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
105 -- static int mondelefant_conn_create_list(lua_State *L)
|
|
jbe@23
|
106 --//--
|
|
jbe@23
|
107
|
|
jbe@23
|
108
|
|
jbe@23
|
109 --[[--
|
|
jbe@23
|
110 db_object = -- database result being an empty object (row)
|
|
jbe@23
|
111 <db_handle>:create_object()
|
|
jbe@23
|
112
|
|
jbe@436
|
113 Creates an empty database result representing an object (row). The used meta-table is "result_metatable". The attribute "_connection" is set to the database handle, and the attribute "_type" is set to "object". The attribute "_class" is initialized to the default class prototype "class_prototype" of the module. Additionally the attribute "_col" is set to a proxy table, and the attributes "_data", "_dirty" and "_ref" are initialized with an empty table. TODO: Documentation of _data, _dirty and _ref.
|
|
jbe@23
|
114
|
|
jbe@23
|
115 --]]--
|
|
jbe@23
|
116 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
117 -- static int mondelefant_conn_create_object(lua_State *L)
|
|
jbe@23
|
118 --//--
|
|
jbe@23
|
119
|
|
jbe@23
|
120
|
|
jbe@23
|
121 --[[--
|
|
jbe@23
|
122 quoted_encoded_string = -- encoded and quoted string
|
|
jbe@23
|
123 <db_handle>:quote_string(
|
|
jbe@23
|
124 unencoded_string -- string to encode and quote
|
|
jbe@23
|
125 )
|
|
jbe@23
|
126
|
|
jbe@23
|
127 Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).
|
|
jbe@23
|
128
|
|
jbe@23
|
129 --]]--
|
|
jbe@23
|
130 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
131 -- static int mondelefant_conn_quote_string(lua_State *L)
|
|
jbe@23
|
132 --//--
|
|
jbe@23
|
133
|
|
jbe@23
|
134
|
|
jbe@23
|
135 --[[--
|
|
jbe@23
|
136 quoted_encoded_data = -- encoded and quoted data (as Lua string)
|
|
jbe@395
|
137 <db_handle>:quote_binary(
|
|
jbe@23
|
138 raw_data -- data (as Lua string) to encode and quote
|
|
jbe@23
|
139 )
|
|
jbe@23
|
140
|
|
jbe@23
|
141 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
|
|
jbe@23
|
142
|
|
jbe@23
|
143 --]]--
|
|
jbe@23
|
144 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
145 -- static int mondelefant_conn_quote_binary(lua_State *L)
|
|
jbe@23
|
146 --//--
|
|
jbe@23
|
147
|
|
jbe@23
|
148
|
|
jbe@23
|
149 --[[--
|
|
jbe@23
|
150 sql_string =
|
|
jbe@23
|
151 <db_handle>:assemble_command{
|
|
jbe@23
|
152 template, -- template string
|
|
jbe@23
|
153 arg1, -- value to be inserted
|
|
jbe@23
|
154 arg2, -- another value to be inserted
|
|
jbe@23
|
155 key1 = named_arg3, -- named value
|
|
jbe@23
|
156 key2 = named_arg4, -- another named value
|
|
jbe@23
|
157 ...
|
|
jbe@23
|
158 }
|
|
jbe@23
|
159
|
|
jbe@23
|
160 This method returns a SQL command by inserting the given values into the template string. Placeholders are "?" or "$", optionally followed by alphanumeric characters (including underscores). Placeholder characters can be escaped by writing them twice. A question-mark ("?") denotes a single value to be inserted, a dollar-sign ("$") denotes a list of sub-structures to be inserted. If alphanumeric characters are following the placeholder character, then these characters form a key, which is used to lookup the value to be used, otherwise values of numeric indicies are used.
|
|
jbe@23
|
161
|
|
jbe@23
|
162 TODO: documentation of input-converters
|
|
jbe@23
|
163
|
|
jbe@23
|
164 List of sub-structures are tables with an optional "sep" value, which is used as seperator. Each (numerically indexed) entry of this table is passed to a recursive call of "assemble_command" and concatenated with the given seperator, or ", ", if no seperator is given.
|
|
jbe@23
|
165
|
|
jbe@23
|
166 --]]--
|
|
jbe@23
|
167 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
168 -- static int mondelefant_conn_assemble_command(lua_State *L)
|
|
jbe@23
|
169 --//--
|
|
jbe@23
|
170
|
|
jbe@23
|
171
|
|
jbe@23
|
172 --[[--
|
|
jbe@23
|
173 db_error, -- error object, or nil in case of success
|
|
jbe@23
|
174 result1, -- result of first command
|
|
jbe@23
|
175 result2, -- result of second command
|
|
jbe@23
|
176 ... =
|
|
jbe@23
|
177 <db_handle>:try_query(
|
|
jbe@23
|
178 command1, -- first command (to be processed by "assemble_command" method)
|
|
jbe@23
|
179 mode1, -- mode for first command: "list", "object" or "opt_object"
|
|
jbe@23
|
180 command2, -- second command (to be processed by "assemble_command" method)
|
|
jbe@23
|
181 mode2, -- mode for second command: "list", "object" or "opt_object"
|
|
jbe@23
|
182 ..
|
|
jbe@23
|
183 )
|
|
jbe@23
|
184
|
|
jbe@23
|
185 This method executes one or multiple SQL commands and returns its results. Each command is pre-processed by the "assemble_command" method of the database handle. A mode can be selected for each command: "list" for normal queries, "object" for queries which have exactly one result row, or "opt_object" which have one or zero result rows. If an error occurs, an error object is returned as first result value.
|
|
jbe@23
|
186
|
|
jbe@23
|
187 The mode of the last command may be ommitted and default to "list".
|
|
jbe@23
|
188
|
|
jbe@23
|
189 --]]--
|
|
jbe@23
|
190 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
191 -- static int mondelefant_conn_try_query(lua_State *L)
|
|
jbe@23
|
192 --//--
|
|
jbe@23
|
193
|
|
jbe@23
|
194
|
|
jbe@23
|
195 --[[--
|
|
jbe@23
|
196 <db_error>:escalate()
|
|
jbe@23
|
197
|
|
jbe@397
|
198 Deprecated alias for error(<db_error>).
|
|
jbe@397
|
199
|
|
jbe@397
|
200 Note: Previous versions converted the error object to a string unless the database connection had "error_objects" set to true. The current implementation simply calls error(...). It is deprecated to use this method, use error(...) instead.
|
|
jbe@23
|
201
|
|
jbe@23
|
202 --]]--
|
|
jbe@23
|
203 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
204 -- static int mondelefant_errorobject_escalate(lua_State *L)
|
|
jbe@23
|
205 --//--
|
|
jbe@23
|
206
|
|
jbe@23
|
207
|
|
jbe@23
|
208 --[[--
|
|
jbe@23
|
209 bool = -- true or false
|
|
jbe@23
|
210 <db_error>:is_kind_of(
|
|
jbe@23
|
211 error_code -- error code as used by this library
|
|
jbe@23
|
212 )
|
|
jbe@23
|
213
|
|
jbe@23
|
214 Checks, if a given error is of a given kind.
|
|
jbe@23
|
215
|
|
jbe@23
|
216 Example:
|
|
jbe@23
|
217 db_error:is_kind_of("IntegrityConstraintViolation")
|
|
jbe@23
|
218
|
|
jbe@23
|
219 --]]--
|
|
jbe@23
|
220 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
221 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)
|
|
jbe@23
|
222 --//--
|
|
jbe@23
|
223
|
|
jbe@23
|
224
|
|
jbe@23
|
225 --[[--
|
|
jbe@397
|
226 <db_error>.code -- hierarchical error code (separated by dots) in camel case
|
|
jbe@397
|
227
|
|
jbe@397
|
228 An error code in camel case notation with dots to separate hierarchy levels, e.g. "IntegrityConstraintViolation.UniqueViolation". See also <db_error>:is_kind_of(...).
|
|
jbe@397
|
229
|
|
jbe@397
|
230 --]]--
|
|
jbe@397
|
231 -- implemented in mondelefant_native.c as
|
|
jbe@397
|
232 -- static const char *mondelefant_translate_errcode(const char *pgcode)
|
|
jbe@397
|
233 --//--
|
|
jbe@397
|
234
|
|
jbe@397
|
235
|
|
jbe@397
|
236 --[[--
|
|
jbe@397
|
237 <db_error>.message -- string which summarizes the error
|
|
jbe@397
|
238
|
|
jbe@397
|
239 A string consisting of a single line (without CR/LF) describing the error. For more detailed information on a particular error, additional fields may be set in the <db_error> object. Refer to the source code of the mondelefant_translate_errcode C function in mondelefant_native.c.
|
|
jbe@397
|
240
|
|
jbe@397
|
241 --]]--
|
|
jbe@397
|
242 -- implemented in mondelefant_native.c
|
|
jbe@397
|
243 --//--
|
|
jbe@397
|
244
|
|
jbe@397
|
245
|
|
jbe@397
|
246 --[[--
|
|
jbe@397
|
247 channel, -- notification channel name, or nil in case of timeout or no pending notify
|
|
jbe@397
|
248 payload, -- notification payload string
|
|
jbe@397
|
249 pid = -- process ID of notifying server process
|
|
jbe@397
|
250 <db_handle>:wait(
|
|
jbe@397
|
251 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely
|
|
jbe@397
|
252 )
|
|
jbe@397
|
253
|
|
jbe@397
|
254 Same as "try_wait" but raises an error, if a connection error occurred. Timeouts are reported by returning nil as first argument.
|
|
jbe@397
|
255
|
|
jbe@397
|
256 --]]--
|
|
jbe@397
|
257 -- implemented in mondelefant_native.c as
|
|
jbe@397
|
258 -- static int mondelefant_conn_wait(lua_State *L)
|
|
jbe@397
|
259 --//--
|
|
jbe@397
|
260
|
|
jbe@397
|
261
|
|
jbe@397
|
262 --[[--
|
|
jbe@23
|
263 result1, -- result of first command
|
|
jbe@23
|
264 result2, -- result of second command
|
|
jbe@23
|
265 ... =
|
|
jbe@23
|
266 <db_handle>:query(
|
|
jbe@23
|
267 command1, -- first command (to be processed by "assemble_command" method)
|
|
jbe@23
|
268 mode1, -- mode for first command: "list", "object" or "opt_object"
|
|
jbe@23
|
269 command2, -- second command (to be processed by "assemble_command" method)
|
|
jbe@23
|
270 mode2, -- mode for second command: "list", "object" or "opt_object"
|
|
jbe@23
|
271 ..
|
|
jbe@23
|
272 )
|
|
jbe@23
|
273
|
|
jbe@23
|
274 Same as "try_query" but raises error, when occurring.
|
|
jbe@23
|
275
|
|
jbe@23
|
276 --]]--
|
|
jbe@23
|
277 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
278 -- static int mondelefant_conn_query(lua_State *L)
|
|
jbe@23
|
279 --//--
|
|
jbe@23
|
280
|
|
jbe@23
|
281
|
|
jbe@23
|
282 --[[--
|
|
jbe@23
|
283 db_list_or_object = -- first argument is returned
|
|
jbe@23
|
284 mondelefant.set_class(
|
|
jbe@23
|
285 db_list_or_object, -- database result list or object
|
|
jbe@23
|
286 db_class -- database class (model)
|
|
jbe@23
|
287 )
|
|
jbe@23
|
288
|
|
jbe@23
|
289 This function sets a class for a given database result list or object. If a result list is given as first argument, the class is also set for all elements of the list.
|
|
jbe@23
|
290
|
|
jbe@23
|
291 --]]--
|
|
jbe@23
|
292 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
293 -- static int mondelefant_set_class(lua_State *L)
|
|
jbe@23
|
294 --//--
|
|
jbe@23
|
295
|
|
jbe@23
|
296
|
|
jbe@23
|
297 --[[--
|
|
jbe@23
|
298 db_class = -- new database class (model)
|
|
jbe@23
|
299 mondelefant.new_class()
|
|
jbe@23
|
300
|
|
jbe@23
|
301 This function creates a new class (model) used for database result lists or objects.
|
|
jbe@23
|
302
|
|
jbe@23
|
303 --]]--
|
|
jbe@23
|
304 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
305 -- static int mondelefant_new_class(lua_State *L)
|
|
jbe@23
|
306 --//--
|
|
jbe@23
|
307
|
|
jbe@23
|
308
|
|
jbe@23
|
309 --[[--
|
|
jbe@23
|
310 reference_data = -- table with reference information
|
|
jbe@23
|
311 <db_class>:get_reference(
|
|
jbe@23
|
312 name -- reference name
|
|
jbe@23
|
313 )
|
|
jbe@23
|
314
|
|
jbe@272
|
315 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful.
|
|
jbe@23
|
316
|
|
jbe@23
|
317 --]]--
|
|
jbe@23
|
318 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
319 -- static int mondelefant_class_get_reference(lua_State *L)
|
|
jbe@23
|
320 --//--
|
|
jbe@23
|
321
|
|
jbe@23
|
322
|
|
jbe@23
|
323 --[[--
|
|
jbe@23
|
324 reference_name = -- reference name
|
|
jbe@23
|
325 <db_class>:get_foreign_key_reference_name(
|
|
jbe@23
|
326 foreign_key -- foreign key
|
|
jbe@23
|
327 )
|
|
jbe@23
|
328
|
|
jbe@272
|
329 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful.
|
|
jbe@23
|
330
|
|
jbe@23
|
331 --]]--
|
|
jbe@23
|
332 -- implemented in mondelefant_native.c as
|
|
jbe@23
|
333 -- static int mondelefant_class_get_reference(lua_State *L)
|
|
jbe@23
|
334 --//--
|
|
jbe@23
|
335
|
|
jbe@416
|
336
|
|
jbe@416
|
337 --[[--
|
|
jbe@417
|
338 <db_object>._col -- proxy table mapping column names to their values
|
|
jbe@416
|
339
|
|
jbe@417
|
340 This attribute can be used to access column values directly (helpful if <db_class>:document_column is set).
|
|
jbe@417
|
341
|
|
jbe@417
|
342 NOTE: Neither pairs(...) nor ipairs(...) are implemented on this proxy table. Use <db_object>._column_info instead.
|
|
jbe@416
|
343
|
|
jbe@416
|
344 --]]--
|
|
jbe@416
|
345 -- implemented in mondelefant_native.c as
|
|
jbe@416
|
346 -- static const struct luaL_Reg mondelefant_columns_mt_functions[]
|
|
jbe@416
|
347 --//--
|
|
jbe@416
|
348
|