1

2 --[[--

3 db_handle, -- database handle, or nil in case of error

4 errmsg, -- error message

5 db_error -- error object

6 mondelefant.connect{

7 engine = "postgresql", -- no other engine is supported

8 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq

9 host = host, -- hostname or directory with leading slash where Unix-domain socket resides

10 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported

11 port = port, -- TCP port or socket file name extension

12 dbname = dbname, -- name of database to connect with

13 user = user, -- login name

14 password = password, -- password

15 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite

16 ...

17 }

18

19 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.

20

21 --]]--

22 -- implemented in mondelefant_native.c as

23 -- static int mondelefant_connect(lua_State *L)

24 --//--

25

26

27 --[[--

28 <db_handle>.fd -- file descriptor of underlaying database connection

29

30 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.

31

32 --]]--

33 -- set/unset in mondelefant_native.c in

34 -- static int mondelefant_connect(lua_State *L) and

35 -- static int mondelefant_close(lua_State *L)

36 --//--

37

38

39 --[[--

40 <db_handle>:close()

41

42 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.

43

44 --]]--

45 -- implemented in mondelefant_native.c as

46 -- static int mondelefant_conn_close(lua_State *L)

47 --//--

48

49

50 --[[--

51 status = -- true, if database connection has no malfunction

52 <db_handle>:is_ok()

53

54 Returns false, if the database connection has a malfunction, otherwise true.

55

56 --]]--

57 -- implemented in mondelefant_native.c as

58 -- static int mondelefant_conn_is_ok(lua_State *L)

59 --//--

60

61

62 --[[--

63 status = -- status string

64 <db_handle>:get_transaction_status()

65

66 Depending on the transaction status of the connection a string is returned:

67 - idle

68 - active

69 - intrans

70 - inerror

71 - unknown

72

73 --]]--

74 -- implemented in mondelefant_native.c as

75 -- static int mondelefant_conn_get_transaction_status(lua_State *L)

76 --//--

77

78

79 --[[--

80 db_error, -- error object, or nil in case of success or timeout

81 channel, -- notification channel name, or nil in case of timeout or no pending notify

82 payload, -- notification payload string

83 pid = -- process ID of notifying server process

84 <db_handle>:try_wait(

85 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely

86 )

87

88 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").

89

90 --]]--

91 -- implemented in mondelefant_native.c as

92 -- static int mondelefant_conn_try_wait(lua_State *L)

93 --//--

94

95

96 --[[--

97 db_list = -- database result being an empty list

98 <db_handle>:create_list()

99

100 Creates an empty 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".

101

102 --]]--

103 -- implemented in mondelefant_native.c as

104 -- static int mondelefant_conn_create_list(lua_State *L)

105 --//--

106

107

108 --[[--

109 db_object = -- database result being an empty object (row)

110 <db_handle>:create_object()

111

112 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". Additionally the attributes "_data", "_dirty" and "_ref" are initialized with an empty table. TODO: Documentation of _data, _dirty and _ref.

113

114 --]]--

115 -- implemented in mondelefant_native.c as

116 -- static int mondelefant_conn_create_object(lua_State *L)

117 --//--

118

119

120 --[[--

121 quoted_encoded_string = -- encoded and quoted string

122 <db_handle>:quote_string(

123 unencoded_string -- string to encode and quote

124 )

125

126 Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).

127

128 --]]--

129 -- implemented in mondelefant_native.c as

130 -- static int mondelefant_conn_quote_string(lua_State *L)

131 --//--

132

133

134 --[[--

135 quoted_encoded_data = -- encoded and quoted data (as Lua string)

136 <db_handle>:quote_binary(

137 raw_data -- data (as Lua string) to encode and quote

138 )

139

140 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.

141

142 --]]--

143 -- implemented in mondelefant_native.c as

144 -- static int mondelefant_conn_quote_binary(lua_State *L)

145 --//--

146

147

148 --[[--

149 sql_string =

150 <db_handle>:assemble_command{

151 template, -- template string

152 arg1, -- value to be inserted

153 arg2, -- another value to be inserted

154 key1 = named_arg3, -- named value

155 key2 = named_arg4, -- another named value

156 ...

157 }

158

159 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.

160

161 TODO: documentation of input-converters

162

163 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.

164

165 --]]--

166 -- implemented in mondelefant_native.c as

167 -- static int mondelefant_conn_assemble_command(lua_State *L)

168 --//--

169

170

171 --[[--

172 db_error, -- error object, or nil in case of success

173 result1, -- result of first command

174 result2, -- result of second command

175 ... =

176 <db_handle>:try_query(

177 command1, -- first command (to be processed by "assemble_command" method)

178 mode1, -- mode for first command: "list", "object" or "opt_object"

179 command2, -- second command (to be processed by "assemble_command" method)

180 mode2, -- mode for second command: "list", "object" or "opt_object"

181 ..

182 )

183

184 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.

185

186 The mode of the last command may be ommitted and default to "list".

187

188 --]]--

189 -- implemented in mondelefant_native.c as

190 -- static int mondelefant_conn_try_query(lua_State *L)

191 --//--

192

193

194 --[[--

195 <db_error>:escalate()

196

197 Deprecated alias for error(<db_error>).

198

199 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.

200

201 --]]--

202 -- implemented in mondelefant_native.c as

203 -- static int mondelefant_errorobject_escalate(lua_State *L)

204 --//--

205

206

207 --[[--

208 bool = -- true or false

209 <db_error>:is_kind_of(

210 error_code -- error code as used by this library

211 )

212

213 Checks, if a given error is of a given kind.

214

215 Example:

216 db_error:is_kind_of("IntegrityConstraintViolation")

217

218 --]]--

219 -- implemented in mondelefant_native.c as

220 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)

221 --//--

222

223

224 --[[--

225 <db_error>.code -- hierarchical error code (separated by dots) in camel case

226

227 An error code in camel case notation with dots to separate hierarchy levels, e.g. "IntegrityConstraintViolation.UniqueViolation". See also <db_error>:is_kind_of(...).

228

229 --]]--

230 -- implemented in mondelefant_native.c as

231 -- static const char *mondelefant_translate_errcode(const char *pgcode)

232 --//--

233

234

235 --[[--

236 <db_error>.message -- string which summarizes the error

237

238 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.

239

240 --]]--

241 -- implemented in mondelefant_native.c

242 --//--

243

244

245 --[[--

246 channel, -- notification channel name, or nil in case of timeout or no pending notify

247 payload, -- notification payload string

248 pid = -- process ID of notifying server process

249 <db_handle>:wait(

250 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely

251 )

252

253 Same as "try_wait" but raises an error, if a connection error occurred. Timeouts are reported by returning nil as first argument.

254

255 --]]--

256 -- implemented in mondelefant_native.c as

257 -- static int mondelefant_conn_wait(lua_State *L)

258 --//--

259

260

261 --[[--

262 result1, -- result of first command

263 result2, -- result of second command

264 ... =

265 <db_handle>:query(

266 command1, -- first command (to be processed by "assemble_command" method)

267 mode1, -- mode for first command: "list", "object" or "opt_object"

268 command2, -- second command (to be processed by "assemble_command" method)

269 mode2, -- mode for second command: "list", "object" or "opt_object"

270 ..

271 )

272

273 Same as "try_query" but raises error, when occurring.

274

275 --]]--

276 -- implemented in mondelefant_native.c as

277 -- static int mondelefant_conn_query(lua_State *L)

278 --//--

279

280

281 --[[--

282 db_list_or_object = -- first argument is returned

283 mondelefant.set_class(

284 db_list_or_object, -- database result list or object

285 db_class -- database class (model)

286 )

287

288 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.

289

290 --]]--

291 -- implemented in mondelefant_native.c as

292 -- static int mondelefant_set_class(lua_State *L)

293 --//--

294

295

296 --[[--

297 db_class = -- new database class (model)

298 mondelefant.new_class()

299

300 This function creates a new class (model) used for database result lists or objects.

301

302 --]]--

303 -- implemented in mondelefant_native.c as

304 -- static int mondelefant_new_class(lua_State *L)

305 --//--

306

307

308 --[[--

309 reference_data = -- table with reference information

310 <db_class>:get_reference(

311 name -- reference name

312 )

313

314 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful.

315

316 --]]--

317 -- implemented in mondelefant_native.c as

318 -- static int mondelefant_class_get_reference(lua_State *L)

319 --//--

320

321

322 --[[--

323 reference_name = -- reference name

324 <db_class>:get_foreign_key_reference_name(

325 foreign_key -- foreign key

326 )

327

328 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful.

329

330 --]]--

331 -- implemented in mondelefant_native.c as

332 -- static int mondelefant_class_get_reference(lua_State *L)

333 --//--

334